Struct rama::context::Context

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

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. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
§

impl<S> Debug for Context<S>
where S: Debug,

§

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

Formats the value using the given formatter. Read more
§

impl Default for Context<()>

§

fn default() -> Context<()>

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl<S> Freeze for Context<S>
where S: Freeze,

§

impl<S> !RefUnwindSafe for Context<S>

§

impl<S> Send for Context<S>
where S: Send,

§

impl<S> Sync for Context<S>
where S: Sync,

§

impl<S> Unpin for Context<S>
where S: Unpin,

§

impl<S> !UnwindSafe for Context<S>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
§

impl<T> Conv for T

§

fn conv<T>(self) -> T
where Self: Into<T>,

Converts self into T using Into<T>. Read more
§

impl<T> FmtForward for T

§

fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
§

fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
§

fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
§

fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
§

fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> FutureExt for T

§

fn with_context(self, otel_cx: Context) -> WithContext<Self>

Attaches the provided Context to this type, returning a WithContext wrapper. Read more
§

fn with_current_context(self) -> WithContext<Self>

Attaches the current Context to this type, returning a WithContext wrapper. Read more
§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pipe for T
where T: ?Sized,

§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
where Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R
where R: 'a,

Borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R
where R: 'a,

Mutably borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
where Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
where Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
where Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows self, then passes self.as_ref() into the pipe function.
§

fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
where Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.as_mut() into the pipe function.
§

fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
where Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R, ) -> R
where Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<S, P, B, E>(self, other: P) -> And<T, P>
where T: Policy<S, B, E>, P: Policy<S, B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
§

fn or<S, P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<S, B, E>, P: Policy<S, B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<T> Tap for T

§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.
§

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.
§

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
§

impl<T> TryConv for T

§

fn try_conv<T>(self) -> Result<T, Self::Error>
where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more