Module cross_process_lock 

A cross-process lock implementation.

This is a per-process lock that may be used only for very specific use cases, where multiple processes might concurrently write to the same database at the same time; this would invalidate store caches, so that should be done mindfully. Such a lock can be obtained multiple times by the same process, and it remains active as long as there’s at least one user in a given process.

The lock is implemented using time-based leases. The lock maintains the lock identifier (key), who’s the current holder (value), and an expiration timestamp on the side; see also CryptoStore::try_take_leased_lock for more details.

The lock is initially obtained for a certain period of time (namely, the duration of a lease, aka LEASE_DURATION_MS), and then a “heartbeat” task renews the lease to extend its duration, every so often (namely, every EXTEND_LEASE_EVERY_MS). Since the Tokio scheduler might be busy, the extension request should happen way more frequently than the duration of a lease, in case a deadline is missed. The current values have been chosen to reflect that, with a ratio of 1:10 as of 2023-06-23.

Releasing the lock happens naturally, by not renewing a lease. It happens automatically after the duration of the last lease, at most.

Modules

memory_store_helper

Some code that is shared by almost all MemoryStore implementations out there.

Structs

CrossProcessLock

A cross-process lock implementation.

CrossProcessLockGuard

A guard of a cross-process lock.

Enums

CrossProcessLockError

Union of CrossProcessLockUnobtained and TryLock::LockError.

CrossProcessLockState

Represent a successful result of a locking attempt, either by CrossProcessLock::try_lock_once or CrossProcessLock::spin_lock.

CrossProcessLockUnobtained

Represent an unsuccessful result of a lock attempt, either by CrossProcessLock::try_lock_once or CrossProcessLock::spin_lock.

MappedCrossProcessLockState

A mapped CrossProcessLockState.

Constants

EXTEND_LEASE_EVERY_MS

Period of time between two attempts to extend the lease. We’ll re-request a lease for an entire duration of LEASE_DURATION_MS milliseconds, every EXTEND_LEASE_EVERY_MS, so this has to be an amount safely low compared to LEASE_DURATION_MS, to make sure that we can miss a deadline without compromising the lock.

FIRST_CROSS_PROCESS_LOCK_GENERATION

Describe the first lock generation value (see CrossProcessLockGeneration).

LEASE_DURATION_MS

Amount of time a lease of the lock should last, in milliseconds.

MAX_BACKOFF_MS

Maximal backoff, in milliseconds. This is the maximum amount of time we’ll wait for the lock, between two attempts.

NO_CROSS_PROCESS_LOCK_GENERATION

Sentinel value representing the absence of a lock generation value.

Traits

TryLock

Trait used to try to take a lock. Foundation of CrossProcessLock.

Type Aliases

CrossProcessLockGeneration

A lock generation is an integer incremented each time the lock is taken by a different holder.