Struct riot_wrappers::mutex::Mutex

pub struct Mutex<T> { /* private fields */ }

A mutual exclusion primitive useful for protecting shared data

Unlike the std::sync::Mutex, this has no concept of poisoning, so waiting for mutexes in paniced (and thus locked) threads will lock the accessing thread as well. This is because RIOT threds don’t unwind Rust code. As a consequence, the mutex interface is different from the standard library’s.

Several methods (into_inner, get_mut) are not implemented until they’re actually needed.

Implementations

impl<T> Mutex<T>

pub const fn new(t: T) -> Mutex<T>

Create a new mutex in an unlocked state

pub fn lock(&self) -> MutexGuard<'_, T>

Get an accessor to the mutex when the mutex is available

Panics

This function checks at runtime whether it is called in a thread context, and panics otherwise. Consider promoting a reference with an InThread token’s .promote(&my_mutex) to gain access to a better .lock() method, which suffers neither the panic condition nor the runtime overhead.

pub fn try_lock(&self) -> Option<MutexGuard<'_, T>>

Get an accessor to the mutex if the mutex is available

pub fn try_leak(&'static self) -> Option<&'static mut T>

Lock the mutex and throw away the key

Try to lock the mutex (returning None if it is locked). When successful, a mutable reference for the complete lifetime of the mutex is produced, without the usual mechanisms that’d free the mutex later.

This is an easy way to get a &’static mut refence in RIOT. Its downsides (compared to cortex-m-rt’s entry mechanisms) are:

• It has runtime storage cost (one mutex_t)
• It has runtime processing cost (primarily the accompanying unwrap which the compiler can’t know to optimze out)
• It needs a good default value (can be mitigated with MaybeUninit)

but then again, it’s easy.

API rationale

This requires access to the original mutex and not just an acquired guard that’d be leaked in the process: The latter could also be done on a more short-lived mutex, which would then be dropped (or even leaked-and-pushed-off-the-stack) even in a locked state. (A possibility that is fine – we sure don’t want to limit mutex usage to require a Pin reference.)

The function could be generalized to some generic lifetime, but there doesn’t seem to be a point to it.

impl<'a, T> ValueInThread<&'a Mutex<T>>

pub fn lock(self) -> MutexGuard<'a, T>

Get an accessor to the mutex when the mutex is available

Through the crate::thread::ValueInThread, this is already guaranteed to run in a thread context, so no additional check is performed.

Trait Implementations

impl<T: Default> Default for Mutex<T>

fn default() -> Self

Returns the “default value” for a type.

impl<'b, H> Handler for &'b Mutex<H>

where H: Handler,

Available on riot_module_gcoap only.

Blanket implementation for mutex wrapped resources

This is useful in combination with the defauilt implementation for Option as well.

type RequestData = Option<<H as Handler>::RequestData>

Type constructed in extract_request_data() passed on to build_response().

type ExtractRequestError = <H as Handler>::ExtractRequestError

Error type for extract_request_data().

type BuildResponseError<M: MinimalWritableMessage> = <H as Handler>::BuildResponseError<M>

Error type for writing response data.

fn extract_request_data<M: ReadableMessage>( &mut self, request: &M ) -> Result<Self::RequestData, Self::ExtractRequestError>

Process an incoming request.

fn estimate_length(&mut self, request: &Self::RequestData) -> usize

Estimate an upper bound for the number of bytes in the response

fn build_response<M: MutableWritableMessage>( &mut self, response: &mut M, request: Self::RequestData ) -> Result<(), Self::BuildResponseError<M>>

Build a response for the request

impl<'b, H> Handler for &'b Mutex<H>

where H: Handler,

Available on riot_module_gcoap only.

Blanket implementation for mutex wrapped resources

This is useful in combination with the defauilt implementation for Option as well.

type RequestData = Option<<H as Handler>::RequestData>

fn extract_request_data<'a>( &mut self, request: &'a impl ReadableMessage ) -> Self::RequestData

fn estimate_length(&mut self, request: &Self::RequestData) -> usize

fn build_response( &mut self, response: &mut impl MutableWritableMessage, request: Self::RequestData )

impl<T> Mutex for &Mutex<T>

type Data = T

Data protected by the mutex.

fn lock<R>(&mut self, f: impl FnOnce(&mut Self::Data) -> R) -> R

Creates a critical section and grants temporary access to the protected data.

impl<T: Send> Send for Mutex<T>

impl<T: Send> Sync for Mutex<T>