Struct Extensions

pub struct Extensions { /* private fields */ }

Expand description

A type map of protocol extensions.

Extensions are internally stored in a type erased Arc. Since values are stored in an Arc there are extra methods exposed that build on top of this and leverage characteristics of an Arc to expose things like cheap cloning of the Arc.

Implementations§

§

impl Extensions

pub fn new() -> Extensions

Create an empty Extensions store.

pub fn insert<T>(&self, val: T) -> &T
where T: Extension,

Insert a type T into this Extensions store.

This method returns a refence to the just insert value

If the value you are inserting is an Arc<T>, prefer using Self::insert_arc() to prevent the double indirection of storing an Arc<Arc<T>>. This happens because internally we use a type erased Arc to store the actual value.

pub fn insert_arc<T>(&self, val: Arc<T>) -> Arc<T>
where T: Extension,

Insert a type Arc<T> into this [Extensions] store.

This method returns a a cloned Arc of the value just inserted

If the value you are inserting is not an Arc<T> or you don’t need a cloned Arc<T> prefer using Self::insert()

pub fn extend(&self, other: &Extensions)

Extend this Extensions store with the other Extensions.

The other Extensionss will be appended behind the current ones

pub fn contains<T>(&self) -> bool
where T: Extension,

Returns true if the Extensions store contains the given type.

pub fn get_ref<T>(&self) -> Option<&T>
where T: Extension,

Get a reference to the most recently insert item of type T, or insert in case no item was found

If an owned Arc<T> is needed prefer using Self::get_arc()

Self::get_ref will return the last added item T, in most cases this is exactly what you want, but if you need the oldest item T use Self::first_ref

pub fn get_arc<T>(&self) -> Option<Arc<T>>
where T: Extension,

Get an owned Arc<T> of the most recently insert item of type T, or insert in case no item was found

If a reference is needed prefer using Self::get_ref()

Self::get_arc will return the last added item T, in most cases this is exactly what you want, but if you need the oldest item T use Self::first_arc

pub fn get_ref_or_insert<T, F>(&self, create_fn: F) -> &T
where T: Extension, F: FnOnce() -> T,

Get a reference to the most recently insert item of type T, or insert in case no item was found

If an owned Arc<T> is needed or inserting prefer using Self::get_arc_or_insert()

pub fn get_arc_or_insert<T, F>(&self, create_fn: F) -> Arc<T>
where T: Extension, F: FnOnce() -> Arc<T>,

Get an owned Arc<T> of the most recently insert item of type T, or insert in case no item was found

If a reference is needed or the type being inserted in not an Arc<T> prefer using Self::get_ref_or_insert()

pub fn first_ref<T>(&self) -> Option<&T>
where T: Extension,

Get a shared reference to the oldest inserted item of type T

If an owned Arc<T> is needed prefer using Self::get_arc()

Self::first_ref will return the first added item T, in most cases this is not what you want, instead use Self::get_ref to get the most recently inserted item T

pub fn first_arc<T>(&self) -> Option<Arc<T>>
where T: Extension,

Get an owned Arc<T> of the oldest inserted item of type T

If a reference is needed prefer using Self::first_ref()

Self::first_arc will return the first added item T, in most cases this is not what you want, instead use Self::get_arc to get the most recently inserted item T

pub fn iter_ref<T>(&self) -> impl Iterator<Item = &T>
where T: Extension,

Iterate over all the inserted items of type T as shared references.

Items are ordered from oldest to newest.

pub fn iter_arc<T>(&self) -> impl Iterator<Item = Arc<T>>
where T: Extension,

Iterate over all the inserted items of type T as cloned Arc values.

Items are ordered from oldest to newest.

pub fn iter_all(&self) -> impl Iterator<Item = &TypeErasedExtension>

Iter over all the TypeErasedExtension

This can be used to efficiently combine different types of Extensions in only a single iteration. TypeErasedExtension exposes methods to easily convert it back to type T if it matches the erasaed type stored internally.