Struct RestorationBucket 

pub struct RestorationBucket { /* private fields */ }

A RestorationBucket holds pieces of the restoration data that a part of the application needs to restore its state.

For a general overview of how state restoration works, see the RestorationManager.

RestorationBuckets are organized in a tree that is rooted in RestorationManager::root_bucket and managed by a RestorationManager. The tree is serializable and must contain all the data an application needs to restore its current state at a later point in time.

A RestorationBucket stores restoration data as key-value pairs. The key is a string representing a restoration ID that identifies a piece of data uniquely within a bucket. The value is any RestorationData. Furthermore, a RestorationBucket may have child buckets, which are identified within their parent via a unique restoration ID as well.

During state restoration, the data previously stored in the RestorationBucket hierarchy will be made available again to the application to restore it to the state it had when the data was collected. State restoration to a previous state may happen when the app is launched (e.g. after it has been terminated gracefully while running in the background) or after the app has already been running for a while.

Lifecycle

A RestorationBucket is rarely instantiated directly via its constructors. Instead, when an entity wants to store data in or retrieve data from a restoration bucket, it typically obtains a child bucket from a parent by calling claim_child. If no parent is available, RestorationManager::root_bucket may be used as a parent. When claiming a child, the claimer must provide the restoration ID of the child it would like to own. A child bucket with a given restoration ID can at most have one owner. If another owner tries to claim a bucket with the same ID from the same parent, an error is raised (see discussion in claim_child). The restoration IDs that a given owner uses to claim a child (and to store data in that child, see below) must be stable across app launches to ensure that after the app restarts the owner can retrieve the same data again that it stored during a previous run.

Per convention, the owner of the bucket has exclusive access to the values stored in the bucket. It can read, add, modify, and remove values via the read, write, and remove methods. In general, the owner should store all the data in the bucket that it needs to restore its current state. If its current state changes, the data in the bucket must be updated. At the same time, the data in the bucket should be kept to a minimum. For example, for data that can be retrieved from other sources (like a database or web service) only enough information (e.g. an ID or resource locator) to re-obtain that data should be stored in the bucket. In addition to managing the data in a bucket, an owner may also make the bucket available to other entities so they can claim child buckets from it via claim_child for their own restoration needs.

The bucket returned by claim_child may either contain state information that the owner had previously (e.g. during a previous run of the application) stored in it or it may be empty. If the bucket contains data, the owner is expected to restore its state with the information previously stored in the bucket. If the bucket is empty, it may initialize itself to default values.

When the data stored in a bucket is no longer needed to restore the application to its current state (e.g. because the owner of the bucket is no longer shown on screen), the bucket must be disposed. This will remove all information stored in the bucket from the app’s restoration data and that information will not be available again when the application is restored to this state in the future.

Implementations

impl RestorationBucket

pub fn empty( app: &mut App, restoration_id: &str, debug_owner: Option<Rc<dyn Debug>>, ) -> Handle<RestorationBucket>

Creates an empty RestorationBucket to be provided to adopt_child to add it to the bucket hierarchy.

Instantiating a bucket directly is rare, most buckets are created by claiming a child from a parent via claim_child. If no parent bucket is available, RestorationManager::root_bucket may be used as a parent.

pub fn root( app: &mut App, manager: Handle<RestorationManager>, raw_data: Option<RestorationMap>, ) -> Handle<RestorationBucket>

Creates the root RestorationBucket for the provided restoration manager.

The raw_data must either be None (in which case an empty bucket will be instantiated) or it must be a nested map describing the entire bucket hierarchy in the following format:

{
 'v': {  // key-value pairs
    // * key is a string representation of a restoration ID
    // * value is any RestorationData
   '<restoration-id>': <RestorationData>,
  },
 'c': {  // child buckets
   '<restoration-id>': <nested map representing a child bucket>
  }
}

Instantiating a bucket directly is rare, most buckets are created by claiming a child from a parent via claim_child.

pub fn child( app: &mut App, restoration_id: &str, parent: Handle<RestorationBucket>, debug_owner: Option<Rc<dyn Debug>>, ) -> Handle<RestorationBucket>

Creates a child bucket initialized with the data that the provided parent has stored under the provided restoration_id.

This constructor cannot be used if the parent does not have any child data stored under the given ID. In that case, create an empty bucket (via empty) and have the parent adopt it via adopt_child.

Instantiating a bucket directly is rare, most buckets are created by claiming a child from a parent via claim_child.

pub fn debug_owner(self: Handle<Self>, app: &App) -> Option<Rc<dyn Debug>>

The owner of the bucket that was provided when the bucket was claimed via claim_child.

The value is used in error messages. Accessing the value is only valid in debug mode, otherwise it will return None.

pub fn is_replacing(self: Handle<Self>, app: &App) -> bool

Returns true when entities processing this bucket should restore their state from the information in the bucket (e.g. via read and claim_child) instead of copying their current state information into the bucket (e.g. via write and adopt_child).

This flag is true for the frame after the RestorationManager has been instructed to restore the application from newly provided restoration data.

pub fn restoration_id(self: Handle<Self>, app: &App) -> &str

The restoration ID under which the bucket is currently stored in the parent of this bucket (or wants to be stored if it is currently parent-less).

pub fn read( self: Handle<Self>, app: &mut App, restoration_id: &str, ) -> Option<RestorationData>

Returns the value that is currently stored in the bucket under the provided restoration_id.

Returns None if nothing is stored under that ID.

See also:

• write, which stores a value in the bucket.
• remove, which removes a value from the bucket.
• contains, which checks whether any value is stored under a given restoration ID.

pub fn write( self: Handle<Self>, app: &mut App, restoration_id: &str, value: impl Into<RestorationData>, )

Stores the provided value under the provided restoration_id in the bucket.

Any value that has previously been stored under that ID is overwritten with the new value.

RestorationData::Null is stored in the bucket as-is. To remove a value, use remove.

See also:

• read, which retrieves a stored value from the bucket.
• remove, which removes a value from the bucket.
• contains, which checks whether any value is stored under a given restoration ID.

pub fn remove( self: Handle<Self>, app: &mut App, restoration_id: &str, ) -> Option<RestorationData>

Deletes the value currently stored under the provided restoration_id from the bucket.

The value removed from the bucket is returned. If no value was stored under that ID, None is returned.

See also:

• read, which retrieves a stored value from the bucket.
• write, which stores a value in the bucket.
• contains, which checks whether any value is stored under a given restoration ID.

pub fn contains(self: Handle<Self>, app: &mut App, restoration_id: &str) -> bool

Checks whether a value is stored in the bucket under the provided restoration_id.

See also:

• read, which retrieves a stored value from the bucket.
• write, which stores a value in the bucket.
• remove, which removes a value from the bucket.

pub fn claim_child( self: Handle<Self>, app: &mut App, restoration_id: &str, debug_owner: Option<Rc<dyn Debug>>, ) -> Handle<RestorationBucket>

Claims ownership of the child with the provided restoration_id from this bucket.

If the application is getting restored to a previous state, the bucket will contain all the data that was previously stored in the bucket. Otherwise, an empty bucket is returned.

The claimer of the bucket is expected to use the data stored in the bucket to restore itself to its previous state described by the data in the bucket. If the bucket is empty, it should initialize itself to default values. Whenever the information that the claimer needs to restore its state changes, the data in the bucket should be updated to reflect that.

A child bucket with a given restoration_id can only have one owner. If another owner claims a child bucket with the same restoration_id the end of the current frame panics in debug mode unless the previous owner has either deleted its bucket by calling dispose or has moved it to a new parent via adopt_child.

When the returned bucket is no longer needed, it must be disposed to delete the information stored in it from the app’s restoration data.

pub fn adopt_child( self: Handle<Self>, app: &mut App, child: Handle<RestorationBucket>, )

Adopts the provided child bucket.

The child will be dropped from its old parent, if it had one.

The child is stored under its restoration_id in this bucket. If this bucket already contains a child bucket under the same ID, the owner of that existing bucket must give it up (e.g. by moving the child bucket to a different parent or by disposing it) before the end of the current frame. Otherwise the illegal use of duplicated restoration IDs panics in debug mode.

No-op if the provided bucket is already a child of this bucket.

pub fn finalize(self: Handle<Self>, app: &mut App)

Called by the RestorationManager just before the data of the bucket is serialized and sent to the host.

pub fn rename(self: Handle<Self>, app: &mut App, new_restoration_id: &str)

Changes the restoration ID under which the bucket is (or will be) stored in its parent to new_restoration_id.

No-op if the bucket is already stored under the provided ID.

If another owner has already claimed a bucket with the provided new_restoration_id the end of the current frame panics in debug mode unless the other owner has deleted its bucket by calling dispose, renamed it using another ID, or has moved it to a new parent via adopt_child.

pub fn dispose(self: Handle<Self>, app: &mut App)

Deletes the bucket and all the data stored in it from the bucket hierarchy.

After dispose has been called, the data stored in this bucket and its children are no longer part of the app’s restoration data. The data originally stored in the bucket will not be available again when the application is restored to this state in the future. It is up to the owners of the children to either move them (via adopt_child) to a new parent that is still part of the bucket hierarchy or to dispose of them as well.

This method must only be called by the object’s owner.

Trait Implementations

impl Debug for RestorationBucket

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.