Struct Container

pub struct Container(/* private fields */);

Containers store the current data and state of the data flow graph created by capsules and their dependencies/dependents. See the README for more.

Implementations

impl Container

pub fn new() -> Self

Initializes a new Container.

Containers contain no data when first created. Use Container::read to populate and read some capsules!

pub fn read<Capsules: CapsulesWithCloneRead>( &self, capsules: Capsules, ) -> Capsules::Data

Performs a consistent read on all supplied capsules that have cloneable data.

Consistency is important here: if you need the current data from a few different capsules, do not read them individually, but rather group them together with one read() call. If you read capsules one at a time, there will be increased overhead in addition to possible inconsistency (say if you read one capsule and then the container is updated right after).

Concurrency

First attempts to grab a read lock; if any of the requested capsules are not initialized, falls back to grabbing a write lock.

pub fn read_ref<Capsules, Callback, CallbackReturn>( &self, capsules: Capsules, callback: Callback, ) -> CallbackReturn

where Capsules: CapsulesWithRefRead, Callback: FnOnce(Capsules::Data<'_>) -> CallbackReturn,

Performs a consistent (ref) read on the supplied capsules.

Consistency is important here: if you need the current data from a few different capsules, do not read them individually, but rather group them together with one read_ref() call. If you read capsules one at a time, there will be increased overhead in addition to possible inconsistency (say if you read one capsule and then the container is updated right after).

It is typically recommended to use Container::read when your capsule data is Clone.

Concurrency

First attempts to grab a read lock; if any of the requested capsules are not initialized, falls back to grabbing a write lock, and will downgrade the write lock to a read lock once initialized.

The callback will be invoked while holding a read lock on the container, so it is best to keep the callback on the quicker side (unless you don’t mind blocking side effect updates and uninitialized reads).

pub fn listen<Effect, EffectFactory, Listener>( &self, effect_factory: EffectFactory, listener: Listener, ) -> ListenerHandle

where Effect: SideEffect, EffectFactory: 'static + Send + Fn() -> Effect, Listener: Fn(CapsuleReader<'_, '_>, <Effect as SideEffect>::Api<'_>) + Send + 'static,

Provides a mechanism to temporarily listen to changes in some capsule(s). The provided listener is called once at the time of the listener’s registration, and then once again everytime a dependency changes.

Returns a ListenerHandle, which doesn’t do anything other than implement Drop, and its Drop implementation will remove listener from the Container.

Thus, if you want the handle to live for as long as the Container itself, it is instead recommended to create a “non-idempotent” capsule (use the effects::as_listener() side effect) that acts as your listener. When you normally would call Container::listen(), instead call container.read(my_non_idempotent_listener) to initialize it.

Concurrency

Internally tries to grab a write lock, so this function is blocking.

Panics

Panics if you attempt to register the same listener twice, before the first ListenerHandle is dropped.

Trait Implementations

impl Clone for Container

fn clone(&self) -> Container

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Container

fn default() -> Container

Returns the “default value” for a type.