Module matrix_sdk_base::store_locks

Collection of small helpers that implement store-based locks.

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 acquired 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 to values inserted in a store. The store 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 acquired 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.

Structs

• CrossProcessStoreLock
  A store-based lock for a Store.
• CrossProcessStoreLockGuard
  A guard on the store lock.

Enums

• LockStoreError
  Error related to the locking API of the store.

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.
• 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.

Traits

• BackingStore
  Backing store for a cross-process lock.