GitHub

transaction

API reference for transaction.

Transactions over TxRef values (Effect's Effect.tx).

tx(eff) runs eff all or nothing: the TxRef values it reads and writes go through a journal, and only a successful run publishes its writes. Transactions are optimistic. At the end of a run the journal is checked against the refs: if another transaction committed to a ref this one read, the run is discarded and the body runs again (a "conflict"). tx_retry discards the run on purpose and parks the fiber until one of the refs it read is written (a "retry").

The check and the commit happen in one fiber step, holding the process-wide commit lock, so no other fiber, of this run or of a run on another thread, sees a half-published transaction or commits in between. tx inside a running transaction joins it: nested calls share one journal and commit together, and a failure caught inside the transaction keeps the writes made before it.

Yield Transaction() inside a body to read its TransactionMeta.

Values

AttributeTypeDescription
tx_retryEffect[Never, Never, Transaction]

Abandon this run of the transaction and run it again once a TxRef it read has been written.

Types

TypeDefinitionDescription
TransactionRetryReasontype TransactionRetryReason = Literal['retry', 'conflict']

Why a run of a transaction body started again: "retry" after tx_retry, "conflict" after a ref it read changed before it could commit.

Classes

Functions

active_transaction

active_transaction(fiber) -> TransactionMeta | None

The transaction fiber is running in, if any. A child fiber inherits its parent's; once that transaction has ended it no longer counts, and the child's next tx starts its own.

ParameterTypeDescription
fiberFiber[Any, Any]

Returns TransactionMeta | None

def active_transaction(fiber: Fiber[Any, Any]) -> TransactionMeta | None:
    """The transaction ``fiber`` is running in, if any. A child fiber
    inherits its parent's; once that transaction has ended it no longer
    counts, and the child's next ``tx`` starts its own."""
    found, state = fiber._context.lookup(Transaction)
    if not found or state._completed:
        return None
    return state

tx

tx[A, E](eff: Effect[A, E, Transaction]) -> Effect[A, E]
tx[A, E, R](eff: Effect[A, E, Transaction | R]) -> Effect[A, E, R]

Run eff as one transaction, or as part of the running one.

ParameterTypeDescription
eff
@overload
def tx[A, E](eff: Effect[A, E, Transaction]) -> Effect[A, E]: ...
@overload
def tx[A, E, R](eff: Effect[A, E, Transaction | R]) -> Effect[A, E, R]: ...
def tx(eff: Effect[Any, Any, Any]) -> Effect[Any, Any, Any]:
    """Run ``eff`` as one transaction, or as part of the running one."""
    require_effect(eff, "eff")
    return _WithFiber(
        lambda fiber: eff if active_transaction(fiber) is not None else _boundary(fiber, eff)
    )

tx_restoring

tx_restoring[A, E](restore, eff) -> Effect[A, E]

tx(eff) called from an uninterruptible region: the body and its tx_retry wait run under restore, while the commit and what the caller does next stay uninterruptible, so an interrupt cannot land between committing a claim (a permit, a lock) and guarding it.

ParameterTypeDescription
restoreRestore
effEffect[A, E, Transaction]

Returns Effect[A, E]

def tx_restoring[A, E](restore: Restore, eff: Effect[A, E, Transaction]) -> Effect[A, E]:
    """``tx(eff)`` called from an uninterruptible region: the body and its
    ``tx_retry`` wait run under ``restore``, while the commit and what the
    caller does next stay uninterruptible, so an interrupt cannot land
    between committing a claim (a permit, a lock) and guarding it."""
    require_effect(eff, "eff")
    return _tx_restoring(restore, eff)

transactional

transactional[A](f) -> Effect[A]

f applied to the running transaction, in a transaction of its own when none is running. The building block of TxRef.

ParameterTypeDescription
fCallable[[TransactionMeta], A]

Returns Effect[A]

def transactional[A](f: Callable[[TransactionMeta], A]) -> Effect[A]:
    """``f`` applied to the running transaction, in a transaction of its
    own when none is running. The building block of ``TxRef``."""

    def body(fiber: Fiber[Any, Any]) -> Effect[A]:
        state = active_transaction(fiber)
        if state is not None:
            return _Sync(lambda: f(state))
        return _boundary(fiber, Transaction().map(f))

    return _WithFiber(body)