Struct Resources 

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

A collection of resources that can be accessed by external effects.

This is used to pass resources to external effects while properly scoping the resource to the running stage graph. If you want to share a resource across multiple stage graphs, you can use Arc<Mutex<T>> or similar.

API Design Choices

StageGraph supports single-threaded simulation as well as multi-threaded production code. Since effect implementations must cover both cases with the same code, the resulting API must be constrained by both environments. The simulation can easily provided a &mut Resources, but if we require that, then the production code will have to hold a lock on the Resources for the whole duration of each effect, serializing all resources.

Therefore, even though not needed in simulation, we design the API so that the effect can use its resources for shorter durations.

Sync Bound

In order to allow resources to be used without blocking the whole resource collection, shared references can be obtained with read locking. Since this fundamentally allows shared access from multiple threads, the resources must be Sync. If your resource is not Sync, you can use SyncWrapper or a mutex.

Implementations

impl Resources

pub fn put<T: Any + Send + Sync>(&self, resource: T)

Put a resource into the resources collection.

This variant uses locking to ensure that the resource is not accessed concurrently.

pub fn get<T: Any + Send + Sync>(&self) -> Result<MappedRwLockReadGuard<'_, T>>

Get a resource from the resources collection.

This variant only takes a read lock on the resource collection, allowing other get operations to proceed concurrently. get_mut will be blocked while the returned guard is held, so drop it as soon as you don’t need it any more.

pub fn get_mut<T: Any + Send + Sync>( &self, ) -> Result<MappedRwLockWriteGuard<'_, T>>

Get a mutable reference to a resource from the resources collection.

This variant takes a write lock on the resource collection, blocking all other operations. See get for a variant that uses read locking. Concurrent operations will be blocked while the returned guard is held, so drop it as soon as you don’t need it any more.

If you need exclusive access to a single resource without blocking the rest of the resource collection, consider putting an Arc<Mutex<T>> in the resources collection.

pub fn take<T: Any + Send + Sync>(&self) -> Result<T>

Take a resource from the resources collection.

This variant uses locking to ensure that the resource is not accessed concurrently.

Trait Implementations

impl Clone for Resources

fn clone(&self) -> Resources

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for Resources

fn default() -> Resources

Returns the “default value” for a type.