Module save_restore

Traits and types for save/restore support.

To implement save/restore for your device or state unit, you must do these things:

1. You define a saved state type. This type needs to be stable across releases, so you should not share types with your implementation even if they are currently identical. By decoupling your runtime types and your saved state types, you are much less likely to accidentally break saved state compatibility.

2. derive some traits on your type. Specifically, you must derive Protobuf so that your type can be encoded into protobuf format, and any fields in your type must also implement Protobuf.

   So that your saved state type can show up in generated .proto files, you must also set an attribute #[mesh(package = "my.package.name")]. This specifies the protobuf package, as well as the file name of your protobuf file. For the root object of your device’s saved state, this package name becomes part of the serialized state, so you cannot change it later.

   Finally, in the root object of your saved state, you must additionally derive SavedStateRoot. This provides some additional metadata so that we can find your saved state type and generate a .proto file from it for analysis. You only need to put this on the root types or types that will be converted to SavedStateBlob; the infrastructure will find any dependent types. But it doesn’t hurt to put it on other types, too.

3. Typically, you implement the SaveRestore trait. This trait allows you to specify your associated saved state type and to implement save and restore methods that act on this type.

   For some device types (such as vmbus devices), you may need to use a device-specific trait that provides additional parameters. But the pattern should be the same.

Structs

• NoSavedState
  Convenience type for objects that have no saved state.
• SavedStateBlob
  An opaque saved state blob, encoded as a protobuf message.

Enums

• CollectError
  A save operation error.
• RestoreError
  A restore error.
• SaveError
  A save error.
• SavedStateNotSupported
  Convenience type for objects that do not support being saved.

Traits

• ProtobufSaveRestore
  Trait implemented by objects that implement SaveRestore with an associated type that can be serialized as a protobuf message.
• SaveRestore
  Implemented by objects which can be saved/restored
• SavedStateRoot
  Trait implemented by “root” saved state blobs, which are ones that either form the root of a saved state tree, or at points in the tree where the type is not known at compile time.

Functions

• saved_state_roots
  Gets the message descriptions for all types deriving SavedStateRoot.

Derive Macros

• SavedStateRoot
  Derives SavedStateRoot for a type.