Struct riot_wrappers::mutex::Mutex

source ·
pub struct Mutex<T> { /* private fields */ }
Expand description

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§

Create a new mutex in an unlocked state

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.

Get an accessor to the mutex if the mutex is available

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.

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§

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

Blanket implementation for mutex wrapped resources

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

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

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

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

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.