Struct Lock 

pub struct Lock { /* private fields */ }

A named lock, not yet held.

Built by LockManager::lock. Nothing is taken until acquire or run.

Implementations

impl Lock

pub fn wait_for(self, wait: Duration) -> Self

Wait up to wait for the lock instead of giving up immediately.

Polls. That is deliberate: the alternative is a pub/sub channel per lock name, which is a lot of moving parts to shave a hundred milliseconds off a path that is by definition contended and by definition rare.

Use it for “this must happen, just not twice at once”. Leave it off for “if somebody else is already doing this, I have nothing to do” — which is the scheduler’s case, and why without_overlapping does not wait.

pub async fn acquire(&self) -> Result<Option<LockGuard>>

Take the lock, or return None if somebody else holds it.

pub async fn run<T, F>(&self, work: F) -> Result<Option<T>>

where F: Future<Output = Result<T>>,

Run work while holding the lock, or return None without running it.

The lock is released whether work succeeds or fails — a task that errors must not hold its lock until the TTL expires, or one bad night skips the next hour of runs too.

let lock = locks.lock("import", Duration::from_secs(60));

match lock.run(async { Ok::<_, rainier_support::Error>(42) }).await? {
    Some(value) => assert_eq!(value, 42),
    None => unreachable!("nobody else holds it"),
}

pub async fn force_release(&self) -> Result<bool>

Take the lock over from whoever holds it.

An escape hatch for an operator, not for code. The holder does not find out, and if it is still running you now have two.

pub async fn is_held(&self) -> Result<bool>

Whether anybody holds it.

Racy by nature — true the moment you ask and false the moment after — so it is for a status page, not for deciding whether to acquire.

pub fn key(&self) -> &str

The cache key, for diagnostics.

Trait Implementations

impl Debug for Lock

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

Formats the value using the given formatter.