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#
| Attribute | Type | Description |
|---|---|---|
tx_retry | Effect[Never, Never, Transaction] | Abandon this run of the transaction and run it again once a |
Types#
| Type | Definition | Description |
|---|---|---|
TransactionRetryReason | type TransactionRetryReason = Literal['retry', 'conflict'] | Why a run of a transaction body started again: |
Classes#
Functions#
active_transaction#
active_transaction(fiber) -> TransactionMeta | NoneThe 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.
| Parameter | Type | Description |
|---|---|---|
fiber | Fiber[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 statetx#
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
restore | Restore | |
eff | Effect[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.
| Parameter | Type | Description |
|---|---|---|
f | Callable[[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)