Locks API for Rust

Every public type, trait and function of the Locks engine in tinystore::locks, generated from its source. The Locks guide explains how to use them, and the Bun and Node, Python and Go pages list the same API.

#Store

impl Store

#Store.lock

pub fn lock(&self, name: &str) -> LockBuilder

Keys held one holder at a time, across every process of the store: hold waits for a key, runs a function and lets the key go.

#Store.semaphore

pub fn semaphore(&self, name: &str) -> SemaphoreBuilder

Keys held by up to limit holders at a time.

#Fence

pub struct Fence(_)

A number that grows with every lease a store gives, so that whoever keeps the largest it has seen can refuse a late holder: the store's epoch in the high 64 bits, which grows each time the locks of a store open, and a count of its leases since in the low 64.

#Fence.get

pub fn get(self) -> u128

The fence as one integer, compared as it is.

#LockBuilder

pub struct LockBuilder { /* private fields */ }

A lock being opened.

#LockBuilder.max_hold

pub fn max_hold(self, bound: Duration) -> Self

How long one lease may last from its grant: past it the key is given to the next in line and the holder told it lost it. Off unless given.

#LockBuilder.open

pub fn open(self) -> Result<Lock>

#SemaphoreBuilder

pub struct SemaphoreBuilder { /* private fields */ }

A semaphore being opened.

#SemaphoreBuilder.limit

pub fn limit(self, limit: u32) -> Self

How many may hold a key at once, from 1 to 1000.

#SemaphoreBuilder.max_hold

pub fn max_hold(self, bound: Duration) -> Self

#SemaphoreBuilder.open

pub fn open(self) -> Result<Semaphore>

#Lock

pub struct Lock { /* private fields */ }

A lock's keys, each held by one holder at a time.

#Lock.hold

pub fn hold<T, E: From<Error>>(
    &self,
    key: impl Key,
    work: impl FnOnce(&Lease<'_>) -> Result<T, E>,
) -> Result<T, E>

Waits for key, ten seconds at most, holds it while work runs and lets it go, answering what work answered. A key still held after the wait is in use; a lease lost while work ran is lost, even when work succeeded.

#Lock.try_hold

pub fn try_hold<T, E: From<Error>>(
    &self,
    key: impl Key,
    work: impl FnOnce(&Lease<'_>) -> Result<T, E>,
) -> Result<Option<T>, E>

Holds key while work runs if nobody holds it, and answers None without waiting if somebody does.

#Lock.key

pub fn key(&self, key: impl Key) -> LockKey<'_>

A key, for a hold that says how long it waits.

#Semaphore

pub struct Semaphore { /* private fields */ }

A semaphore's keys, each held by up to its limit at a time.

#Semaphore.hold

pub fn hold<T, E: From<Error>>(
    &self,
    key: impl Key,
    work: impl FnOnce(&Permit<'_>) -> Result<T, E>,
) -> Result<T, E>

#Semaphore.try_hold

pub fn try_hold<T, E: From<Error>>(
    &self,
    key: impl Key,
    work: impl FnOnce(&Permit<'_>) -> Result<T, E>,
) -> Result<Option<T>, E>

#Semaphore.key

pub fn key(&self, key: impl Key) -> SemaphoreKey<'_>

#LockKey

pub struct LockKey<'a> { /* private fields */ }

A key of a lock, for a hold that says how long it waits.

#LockKey.wait

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

How long the hold waits in line; ten seconds unless said.

#LockKey.hold

pub fn hold<T, E: From<Error>>(self, work: impl FnOnce(&Lease<'_>) -> Result<T, E>) -> Result<T, E>

#LockKey.try_hold

pub fn try_hold<T, E: From<Error>>(
    self,
    work: impl FnOnce(&Lease<'_>) -> Result<T, E>,
) -> Result<Option<T>, E>

#SemaphoreKey

pub struct SemaphoreKey<'a> { /* private fields */ }

A key of a semaphore, for a hold that says how long it waits.

#SemaphoreKey.wait

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

#SemaphoreKey.hold

pub fn hold<T, E: From<Error>>(self, work: impl FnOnce(&Permit<'_>) -> Result<T, E>) -> Result<T, E>

#SemaphoreKey.try_hold

pub fn try_hold<T, E: From<Error>>(
    self,
    work: impl FnOnce(&Permit<'_>) -> Result<T, E>,
) -> Result<Option<T>, E>

#Lease

pub struct Lease<'a> { /* private fields */ }

A holding of a lock's key, given to the function that holds it.

#Lease.fence

pub fn fence(&self) -> Fence

The lease's fence: hand it to whatever must refuse a late holder.

#Lease.lost

pub fn lost(&self) -> bool

Whether the lease ended while its function runs: revoked at its max_hold, or the store closed. What the function does from then on may run beside another holder.

#Permit

pub struct Permit<'a> { /* private fields */ }

A holding of a semaphore's key: one of its limit.

#Permit.lost

pub fn lost(&self) -> bool