momotor.shared.state

Workers sometimes share data that only one of them may change at a time. This module defines a lock interface for that shared state. Code asks for a lock by name, does its work, and releases the lock. Other code that asks for the same lock waits.

Each lock has two modes:

  • Shared mode (exclusive=False) is for reading. Many holders can have the lock at the same time.

  • Exclusive mode (exclusive=True, the default) is for writing. One holder has the lock, and every other request waits.

Which implementation runs where

StateABC is the abstract interface. Two kinds of implementations exist:

  • LocalState keeps the locks in the current process. Local workers use it because they share nothing with other processes. The broker-side implementation also builds on it.

  • Workers that connect to the broker use a subclass that asks the broker to hold the lock. The protocol package provides that subclass as momotor.rpc.shared.SharedState.

Take a lock

get_lock() is an async context manager. The lock is held inside the async with block and released when the block ends, also when the block raises an exception.

from momotor.shared.state import LocalState

state = LocalState()

async with state.get_lock('tool-cache', exclusive=True):
    ...  # only one holder runs this block at a time

async with state.get_lock('tool-cache', exclusive=False):
    ...  # readers can share this block with other readers

Use test_lock() only to check whether a lock is currently held. The answer can change right after the call returns, so do not use it to decide that a later get_lock will not wait.

If an implementation cannot grant a lock, it raises LockFailed.

API reference

class momotor.shared.state.StateABC

Abstract base class to implement shared locks

abstractmethod get_lock(key, *, exclusive=True)

Context manager to get a lock. The lock is held while the context is active.

The lock is an ‘exclusive’ or ‘read/write’ lock:

  • Many processes can hold the lock when exclusive is False (read mode), but

  • Only one process can hold the lock when exclusive is True (write mode). No other processes can hold the lock while one process has it locked exclusively.

Parameters:
  • key (str) – global name for the lock

  • exclusive (bool) – get an exclusive lock

Return type:

AbstractAsyncContextManager[None]

Returns:

An async context manager that holds the lock and yields None.

Raises:

LockFailed

abstractmethod async test_lock(key, *, exclusive=True)

Test the lock. Returns True if the lock is currently being held.

Note that this is very transient information. The lock could be acquired immediately after this method returns.

Parameters:
  • key (str) – global name for the lock

  • exclusive (bool) – test the exclusive (write) side of the lock if True, the shared (read) side if False

Return type:

bool

Returns:

True if the tested side of the lock is currently held

class momotor.shared.state.LocalState

Reference implementation of StateABC for local use.

Uses a WeakValueDictionary of momotor.shared.exlock.ExLock objects.

Produces debug logging information on the momotor.shared.state.local logger

get_lock(key, *, exclusive=True)

Context manager to get a lock. The lock is held while the context is active.

The lock is an ‘exclusive’ or ‘read/write’ lock:

  • Many processes can hold the lock when exclusive is False (read mode), but

  • Only one process can hold the lock when exclusive is True (write mode). No other processes can hold the lock while one process has it locked exclusively.

Parameters:
  • key (str) – global name for the lock

  • exclusive (bool) – get an exclusive lock

Returns:

An async context manager that holds the lock and yields None.

Raises:

LockFailed

async test_lock(key, *, exclusive=True)

Test the lock. Returns True if the lock is currently being held.

Note that this is very transient information. The lock could be acquired immediately after this method returns.

Parameters:
  • key (str) – global name for the lock

  • exclusive (bool) – test the exclusive (write) side of the lock if True, the shared (read) side if False

Return type:

bool

Returns:

True if the tested side of the lock is currently held

class momotor.shared.state.LockFailed

Exception to indicate a StateABC subclass could not acquire the lock