Struct Mutex 

pub struct Mutex<P: Priority, T: ?Sized, Q: MutexQueue<P> = DefaultMutexQueue<P>> { /* private fields */ }

A mutex that queues waiters by priority. Higher priority requesters will receive access first.

If the evict feature is enabled, the current holder of the lock will be notified if a higher priority waiter is queued.

Note that requesters with the same priority may receive their access in an arbitrary priority - if this is non-desireable, FIFO and LIFO may be used.

Example:

use async_priority_lock::{FIFO, HighestFirst, Mutex, MutexGuard};

static MY_LOCK: Mutex<FIFO<HighestFirst<usize>>, Vec<usize>> =
    Mutex::const_new(vec![]);

async fn push_num(num: usize, priority: usize) {
    // Pushes our number to the queue.  If multiple writers are waiting on this, the waiters
    // will acquire access by order of priority.  As the priority is FIFO, rquesters with the
    // same priority will execute oldest first.
    MY_LOCK.lock_from(priority).await.push(num);
}

async fn wait_and_push(num: usize, priority: usize) {
    loop {
        let mut guard = MY_LOCK.lock_from(priority).await;
        // wait a second or abort and retry if the resource is requested with a higher
        // priority in the meantime
        tokio::select! {
            _ = tokio::time::sleep(tokio::time::Duration::from_secs(1)) => {},
            _ = MutexGuard::evicted(&mut guard) => {
                // drop the guard and try again
                continue;
            }
        }

        guard.push(num)
    }
}

Implementations

impl<P: Priority, T: ?Sized, Q: MutexQueue<P>> Mutex<P, T, Q>

pub fn try_lock( &self, priority: impl Into<P>, ) -> Result<MutexGuard<'_, P, T, Q>, TryLockError>

Try to acquire the lock without blocking or requesting eviction of the current holder.

Priority will be stored in guard; higher priority requesters will try to evict the returned guard if the evict flag is enabled.

i.e. the holder may wait / check for eviction via MutexGuard::evicted.

pub async fn lock(&self, priority: P) -> MutexGuard<'_, P, T, Q>

Acquire exclusive access to the locked resource, waiting until after higher priority requesters acquire and release the lock.

If the evict feature is enabled, this will also notify the current holder to request it to release the lock if the current holder is lower priority.

i.e. the holder may wait / check for eviction via MutexGuard::evicted.

Cancel Safety: This function is cancel safe.

pub fn lock_from( &self, priority: impl Into<P>, ) -> impl Future<Output = MutexGuard<'_, P, T, Q>>

Acquire exclusive access to the locked resource, waiting until higher priority requesters release the lock.

Shorthand for self.lock(priority.into()).

Cancel Safety: This function is cancel safe.

pub fn lock_default(&self) -> impl Future<Output = MutexGuard<'_, P, T, Q>>

where P: Default,

Acquire exclusive access to the locked resource, waiting until higher priority requesters release the lock.

Shorthand for self.lock(Default::default()).

Cancel Safety: This function is cancel safe.

pub fn new(val: T) -> Self

where T: Sized,

Create a new Mutex, unlocked and ready for use.

pub const fn const_new(val: T) -> Self

where Q: ConstDefault, T: Sized,

Create a new Mutex, unlocked and ready for use.

Available when the queue is ConstDefault if the const-default feature is enabled.

All builtin queues are ConstDefault.

Trait Implementations

impl<P: Priority, T: ConstDefault, Q: ConstDefault + MutexQueue<P>> ConstDefault for Mutex<P, T, Q>

Available on crate feature const-default only.

const DEFAULT: Self

The constant default value.

impl<P, T, Q: MutexQueue<P>> Debug for Mutex<P, T, Q>

where T: Debug + ?Sized, P: Default + Priority,

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

Formats the value using the given formatter.

impl<P: Priority, T: Default, Q: MutexQueue<P>> Default for Mutex<P, T, Q>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, P: Priority, T, Q: MutexQueue<P>> Deserialize<'de> for Mutex<P, T, Q>

where T: Deserialize<'de>,

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<P: Priority, T: ?Sized + Send, Q: Send + MutexQueue<P>> Send for Mutex<P, T, Q>

impl<P: Priority, T: ?Sized + Send, Q: Send + Sync + MutexQueue<P>> Sync for Mutex<P, T, Q>

For the mutex to be Sync, T must be Send (Sync is not needed).

Also see rust Mutex docs

(however, both Sync and Send are required for the queue; usually these are implemented if P is Send + Sync)

impl<P: Priority, T: ?Sized + Unpin, Q: Unpin + MutexQueue<P>> Unpin for Mutex<P, T, Q>