Skip to content

salvus.flow.acta.memo.single_flight

salvus.flow.acta.memo.single_flight salvus flow acta memo single_flight

Per-key leases to avoid duplicate task execution.

Recheck the cache after acquiring a lease, commit before releasing it, and renew or release only leases owned by the caller. Expired leases may be acquired by other callers, allowing duplicate computation.

Functions

async_acquire_lock()

def async_acquire_lock(
    records: RecordStore, key: str, holder: str, ttl_seconds: float
) -> bool: ...

Acquire in a thread without stranding a lock if the caller is cancelled.

Parameters
  • records RecordStore — Record database owning the lease.
  • key str — Computation to lock.
  • holder str — Unique identity for this acquisition.
  • ttl_seconds float — Lease lifetime.
Returns bool

async_lookup_or_acquire()

def async_lookup_or_acquire(
    records: RecordStore,
    store: ContentStoreBase,
    key: str,
    holder: str,
    ttl_seconds: float = 60.0,
    poll_interval_seconds: float = 0.05,
    on_wait: Callable[[], None] | None = None,
) -> Hit | Acquired: ...

Await a verified cache hit or acquire the computation lease.

Use event-loop polling; only database operations occupy worker threads.

Parameters
  • records RecordStore — Record store backing both the record and lock tables.
  • store ContentStoreBase — Content store verifying hit payloads.
  • key str — The envelope key to look up or acquire.
  • holder str — This caller’s opaque identity. Must be passed again to release/renew.
  • ttl_seconds float = 60.0 — Lock lease duration.
  • poll_interval_seconds float = 0.05 — Delay between polls while waiting.
  • on_wait Callable[[], None] | None = None — Called once if another caller holds the lease.
Returns Hit | Acquired — A verified Hit, or an Acquired lease.

lookup_or_acquire()

def lookup_or_acquire(
    records: RecordStore,
    store: ContentStoreBase,
    key: str,
    holder: str,
    ttl_seconds: float = 60.0,
    poll_interval_seconds: float = 0.05,
) -> Hit | Acquired: ...

Wait for a verified cache hit or acquire the computation lease.

Poll until a result is available or the lease can be acquired.

Parameters
  • records RecordStore — Record store backing both the record and lock tables.
  • store ContentStoreBase — Content store verifying hit payloads.
  • key str — The envelope key to look up or acquire.
  • holder str — Caller identity, reused for release and renew.
  • ttl_seconds float = 60.0 — Lease duration; renew before expiry if computation takes longer.
  • poll_interval_seconds float = 0.05 — Sleep between polls while waiting.
Returns Hit | Acquired — A verified Hit, or an Acquired lease that the caller must release after committing its result.

release()

def release(records: RecordStore, key: str, holder: str) -> None: ...

Release the lock on key, only if holder still owns it.

Parameters
  • records RecordStore — Record store backing the lock table.
  • key str — The envelope key whose lock should be released.
  • holder str — This caller’s opaque identity, as passed to lookup_or_acquire.
Returns None

renew()

def renew(
    records: RecordStore, key: str, holder: str, ttl_seconds: float
) -> bool: ...

Extend the lease on key, only if holder still owns it.

Sessions renew automatically; other callers must arrange renewal.

Parameters
  • records RecordStore — Record store backing the lock table.
  • key str — The envelope key whose lease should be extended.
  • holder str — This caller’s opaque identity, as passed to lookup_or_acquire.
  • ttl_seconds float — New lease duration from now.
Returns bool — True if renewed, False if holder no longer owns the lock (e.g. it was already stolen after expiring).

Classes

Acquired

class Acquired(builtins.object):
    def __init__(self, holder: str) -> None: ...

A lease requiring the caller to compute, commit, and release.

Parameters
  • holder str — This caller’s opaque identity, to be passed to release/renew after computing.