Struct Context

pub struct Context<S> { /* private fields */ }

Context passed to and between services as input.

See crate::context for more information.

Implementations

impl<S> Context<S>

pub fn new(state: S, executor: Executor) -> Context<S>

Create a new Context with the given state.

pub fn with_state(state: S) -> Context<S>

Create a new Context with the given state and default extension.

pub fn state(&self) -> &S

Get a reference to the state.

pub fn state_mut(&mut self) -> &mut S

Get an exclusive reference to the state.

pub fn map_state<F, W>(self, f: F) -> Context<W>

where F: FnOnce(S) -> W,

Map the state from one type to another.

pub fn swap_state<W>(self, state: W) -> (Context<W>, S)

Swap the state from one type to another, returning the new object as well as the previously defined state.

pub fn clone_map_state<F, W>(&self, f: F) -> Context<W>

where S: Clone, F: FnOnce(S) -> W,

Clones the internals of this Context to provide a new context, but while mapping the state into a new state.

pub fn clone_with_state<W>(&self, state: W) -> Context<W>

Clones the internals of this Context to provide a new context, but using the given state, instead of the one defined in the current Context.

pub fn executor(&self) -> &Executor

Get a reference to the executor.

pub fn spawn<F>(&self, future: F) -> JoinHandle<<F as Future>::Output>

where F: Future + Send + 'static, <F as Future>::Output: Send + 'static,

Spawn a future on the current executor, this is spawned gracefully in case a shutdown guard has been registered.

pub fn contains<T>(&self) -> bool

where T: Send + Sync + 'static,

Returns true if the Context contains the given type.

Use Self::get in case you want to have access to the type or Self::get_mut if you also need to mutate it.

pub fn get<T>(&self) -> Option<&T>

where T: Send + Sync + 'static,

Get a shared reference to an extension.

An extension is a type that implements Send + Sync + 'static, and can be used to inject dynamic data into the Context.

Extensions are specific to this Context. It will be cloned when the Context is cloned, but extensions inserted using Context::insert will not be visible the original Context, or any other cloned Context.

Please use the statically typed state (see Context::state) for data that is shared between all context clones.

Example

assert_eq!(ctx.get::<i32>(), Some(&5i32));

pub fn get_mut<T>(&mut self) -> Option<&mut T>

where T: Send + Sync + 'static,

Get an exclusive reference to an extension.

An extension is a type that implements Send + Sync + 'static, and can be used to inject dynamic data into the Context.

Extensions are specific to this Context. It will be cloned when the Context is cloned, but extensions inserted using Context::insert will not be visible the original Context, or any other cloned Context.

Please use the statically typed state (see Context::state) for data that is shared between all context clones.

Example

let x = ctx.get_mut::<i32>().unwrap();
assert_eq!(*x, 5i32);
*x = 8;
assert_eq!(*x, 8i32);
assert_eq!(ctx.get::<i32>(), Some(&8i32));

pub fn get_or_insert_with<T>(&mut self, f: impl FnOnce() -> T) -> &mut T

where T: Clone + Send + Sync + 'static,

Inserts a value into the map computed from f into if it is None, then returns an exclusive reference to the contained value.

Example

let mut ctx = Context::default();
let value: &i32 = ctx.get_or_insert_with(|| 42);
assert_eq!(*value, 42);
let existing_value: &mut i32 = ctx.get_or_insert_with(|| 0);
assert_eq!(*existing_value, 42);

pub fn get_or_insert_with_ctx<T>( &mut self, f: impl FnOnce(&Context<S>) -> T, ) -> &mut T

where T: Clone + Send + Sync + 'static,

Inserts a value into the map computed from f into if it is None, then returns an exclusive reference to the contained value.

Use the cheaper Self::get_or_insert_with in case you do not need access to the Context for the creation of T, as this function comes with an extra cost.

Example

struct State {
    mul: i32,
}
let mut ctx = Context::with_state(Arc::new(State{ mul: 2 }));
ctx.insert(true);
let value: &i32 = ctx.get_or_insert_with_ctx(|ctx| ctx.state().mul * 21);
assert_eq!(*value, 42);
let existing_value: &mut i32 = ctx.get_or_insert_default();
assert_eq!(*existing_value, 42);

pub fn get_or_try_insert_with_ctx<T, E>( &mut self, f: impl FnOnce(&Context<S>) -> Result<T, E>, ) -> Result<&mut T, E>

where T: Clone + Send + Sync + 'static,

Try to insert a value into the map computed from f into if it is None, then returns an exclusive reference to the contained value.

Similar to Self::get_or_insert_with_ctx but fallible.

pub fn get_or_insert_from<T, U>(&mut self, src: U) -> &mut T

where T: Clone + Send + Sync + 'static, U: Into<T>,

Inserts a value into the map computed from converting U into T if no value was already inserted is [None`], then returns an exclusive reference to the contained value.

pub fn get_or_insert<T>(&mut self, fallback: T) -> &mut T

where T: Send + Sync + Clone + 'static,

Retrieves a value of type T from the context.

If the value does not exist, the provided value is inserted and an exclusive reference to it is returned.

See Context::get for more details.

Example

let mut ctx = Context::default();
ctx.insert(5i32);

assert_eq!(*ctx.get_or_insert::<i32>(10), 5);
assert_eq!(*ctx.get_or_insert::<f64>(2.5), 2.5);

pub fn get_or_insert_default<T>(&mut self) -> &mut T

where T: Clone + Default + Send + Sync + 'static,

Get an extension or T’s Default.

See Context::get for more details.

Example

assert_eq!(*ctx.get_or_insert_default::<i32>(), 5i32);
assert_eq!(*ctx.get_or_insert_default::<f64>(), 0f64);

pub fn insert<T>(&mut self, extension: T) -> Option<T>

where T: Clone + Send + Sync + 'static,

Insert an extension into the Context.

If a extension of this type already existed, it will be returned.

See Context::get for more details regarding extensions.

Example

let mut ctx = Context::default();

assert_eq!(ctx.insert(5i32), None);
assert_eq!(ctx.get::<i32>(), Some(&5i32));

assert_eq!(ctx.insert(4i32), Some(5i32));
assert_eq!(ctx.get::<i32>(), Some(&4i32));

pub fn maybe_insert<T>(&mut self, extension: Option<T>) -> Option<T>

where T: Clone + Send + Sync + 'static,

Insert a type only into this Context, if the extension is Some(T).

See Self::insert for more information.

pub fn extensions(&self) -> &Extensions

Return the entire dynamic state of the Context by reference.

Useful only in case you have a function which works with Extensions rather then the Context itself. In case you want to have access to a specific dynamic state, it is more suitable to use Context::get directly.

pub fn extensions_mut(&mut self) -> &mut Extensions

Return the entire dynamic state of the Context by mutable reference.

Useful only in case you have a function which works with Extensions rather then the Context itself. In case you want to have access to a specific dynamic state, it is more suitable to use Context::get_or_insert or Context::insert directly.

Rollback

Extensions do not have “rollback” support. In case you are not yet certain if you want to keep the to be inserted Extensions, you are better to create a new Extensions object using Extensions::default and use Context::extend once you wish to commit the new dynamic data into the Context.

pub fn extend(&mut self, extensions: Extensions)

Extend The Context Extensions with another Extensions.

Example

let mut ctx = Context::default();
let mut ext = Extensions::default();

ctx.insert(true);
ext.insert(5i32);
ctx.extend(ext);

assert_eq!(ctx.get::<bool>(), Some(&true));
assert_eq!(ctx.get::<i32>(), Some(&5i32));

pub fn clear(&mut self)

Clear the Context of all inserted Extensions.

Example

let mut ctx = Context::default();

ctx.insert(5i32);
assert_eq!(ctx.get::<i32>(), Some(&5i32));

ctx.clear();
assert_eq!(ctx.get::<i32>(), None);

pub fn remove<T>(&mut self) -> Option<T>

where T: Clone + Send + Sync + 'static,

Remove an extension from this Context

pub fn guard(&self) -> Option<&ShutdownGuard>

Get a reference to the shutdown guard, if and only if the context was created within a graceful environment.

impl<S> Context<S>

where S: Clone,

pub fn state_clone(&self) -> S

Get a cloned reference to the state.

Trait Implementations

impl<S> Clone for Context<S>

where S: Clone,

fn clone(&self) -> Context<S>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<S> Debug for Context<S>

where S: Debug,

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

Formats the value using the given formatter.

impl Default for Context<()>

fn default() -> Context<()>

Returns the “default value” for a type.