class TxQueue[A, E = Never]
Build one with TxQueue[int].bounded(8) (or unbounded,
dropping, sliding); TxQueue[int, Done] can be ended.
Attributes#
| Attribute | Type | Description |
|---|---|---|
strategy | Strategy | |
capacity | int | None | How many items the queue holds; |
Functions#
__init__#
__init__(strategy, capacity) -> None| Parameter | Type | Description |
|---|---|---|
strategy | Strategy | |
capacity | int | None |
def __init__(self, strategy: Strategy, capacity: int | None) -> None:
self._strategy: Strategy = strategy
self._capacity = capacity
self._items: TxRef[tuple[A, ...]] = TxRef(())
self._state: TxRef[_State[E]] = TxRef(_OPEN)bounded#
bounded(capacity) -> Effect[TxQueue[A, E]]offer waits while the queue holds capacity items.
| Parameter | Type | Description |
|---|---|---|
capacity | int |
Returns Effect[TxQueue[A, E]]
@classmethod
def bounded(cls, capacity: int) -> Effect[TxQueue[A, E]]:
"""``offer`` waits while the queue holds ``capacity`` items."""
return cls._make("bounded", capacity)unbounded#
unbounded() -> Effect[TxQueue[A, E]]Returns Effect[TxQueue[A, E]]
@classmethod
def unbounded(cls) -> Effect[TxQueue[A, E]]:
return cls._make("unbounded", None)dropping#
dropping(capacity) -> Effect[TxQueue[A, E]]offer on a full queue drops the new item.
| Parameter | Type | Description |
|---|---|---|
capacity | int |
Returns Effect[TxQueue[A, E]]
@classmethod
def dropping(cls, capacity: int) -> Effect[TxQueue[A, E]]:
"""``offer`` on a full queue drops the new item."""
return cls._make("dropping", capacity)sliding#
sliding(capacity) -> Effect[TxQueue[A, E]]offer on a full queue drops the oldest item.
| Parameter | Type | Description |
|---|---|---|
capacity | int |
Returns Effect[TxQueue[A, E]]
@classmethod
def sliding(cls, capacity: int) -> Effect[TxQueue[A, E]]:
"""``offer`` on a full queue drops the oldest item."""
return cls._make("sliding", capacity)offer#
offer(item) -> Effect[bool]Add an item. False if the queue is closing or done, or full and
dropping. A full bounded queue waits; a full sliding one drops its
oldest item.
| Parameter | Type | Description |
|---|---|---|
item | A |
Returns Effect[bool]
def offer(self, item: A) -> Effect[bool]:
"""Add an item. ``False`` if the queue is closing or done, or full and
dropping. A full bounded queue waits; a full sliding one drops its
oldest item."""
def decide(meta: TransactionMeta) -> _Step[bool, Never]:
accepted = self._offer(meta, item)
return tx_retry if accepted is None else succeed(accepted)
return _tx_ops.decide(decide)offer_all#
offer_all[T](items) -> Effect[list[T]]Offer each item in one transaction; succeeds with those not added.
On a bounded queue, waits until all of them fit. items is read
once, here, so a one-shot iterator survives transaction retries.
| Parameter | Type | Description |
|---|---|---|
items | Iterable[T] |
Returns Effect[list[T]]
def offer_all[T](self: TxQueue[T, Any], items: Iterable[T]) -> Effect[list[T]]:
"""Offer each item in one transaction; succeeds with those not added.
On a bounded queue, waits until all of them fit. ``items`` is read
once, here, so a one-shot iterator survives transaction retries."""
batch = list(items)
def decide(meta: TransactionMeta) -> _Step[list[T], Never]:
rejected: list[T] = []
for item in batch:
accepted = self._offer(meta, item)
if accepted is None:
return tx_retry
if not accepted:
rejected.append(item)
return succeed(rejected)
return _tx_ops.decide(decide)fail#
fail(error) -> Effect[bool]Drop the items and finish the queue with error at once: takers
fail with it. False if the queue was already closing or done.
| Parameter | Type | Description |
|---|---|---|
error | E |
Returns Effect[bool]
def fail(self, error: E) -> Effect[bool]:
"""Drop the items and finish the queue with ``error`` at once: takers
fail with it. ``False`` if the queue was already closing or done."""
def decide(meta: TransactionMeta) -> _Step[bool, Never]:
if not isinstance(_tx_ops.value(meta, self._state), _Open):
return succeed(False)
_tx_ops.write(meta, self._items, ())
_tx_ops.write(meta, self._state, _Done(fail_cause(error)))
return succeed(True)
return _tx_ops.decide(decide)fail_cause#
fail_cause(cause) -> Effect[bool]Finish the queue with cause once its items are taken. False
if the queue was already closing or done.
| Parameter | Type | Description |
|---|---|---|
cause | Cause[E] |
Returns Effect[bool]
def fail_cause(self, cause: Cause[E]) -> Effect[bool]:
"""Finish the queue with ``cause`` once its items are taken. ``False``
if the queue was already closing or done."""
def decide(meta: TransactionMeta) -> _Step[bool, Never]:
if not isinstance(_tx_ops.value(meta, self._state), _Open):
return succeed(False)
items = _tx_ops.value(meta, self._items)
_tx_ops.write(meta, self._state, _Closing(cause) if items else _Done(cause))
return succeed(True)
return _tx_ops.decide(decide)end#
end() -> Effect[bool]No more items: takers fail with Done() once the queue drains.
Only on queues whose error type is Done.
Returns Effect[bool]
def end(self: TxEnqueue[Any, Done]) -> Effect[bool]:
"""No more items: takers fail with ``Done()`` once the queue drains.
Only on queues whose error type is ``Done``."""
return self.fail_cause(fail_cause(Done()))interrupt#
interrupt() -> Effect[bool]Takers are interrupted (by the calling fiber) once the queue drains.
Returns Effect[bool]
def interrupt(self) -> Effect[bool]:
"""Takers are interrupted (by the calling fiber) once the queue
drains."""
return fiber_id().flat_map(lambda fid: self.fail_cause(interrupt_cause(fid)))shutdown#
shutdown() -> Effect[bool]Drop the items and interrupt the queue; False if it was
already closing or done.
Returns Effect[bool]
def shutdown(self) -> Effect[bool]:
"""Drop the items and interrupt the queue; ``False`` if it was
already closing or done."""
return tx(self.clear().ignore_cause().and_then(self.interrupt()))take#
take() -> Effect[A, E]Wait for an item. Once the queue is done, fails with its cause.
Returns Effect[A, E]
def take(self) -> Effect[A, E]:
"""Wait for an item. Once the queue is done, fails with its cause."""
def decide(meta: TransactionMeta) -> _Step[A, E]:
state = _tx_ops.value(meta, self._state)
if isinstance(state, _Done):
return fail_with(state.cause)
items = _tx_ops.value(meta, self._items)
if not items:
return tx_retry
self._remove(meta, state, items, 1)
return succeed(items[0])
return _tx_ops.decide(decide)poll#
poll() -> Effect[Option[A]]An item if one is there now; None if not, or if the queue is
done.
Returns Effect[Option[A]]
def poll(self) -> Effect[Option[A]]:
"""An item if one is there now; ``None`` if not, or if the queue is
done."""
def decide(meta: TransactionMeta) -> _Step[Option[A], Never]:
state = _tx_ops.value(meta, self._state)
items = _tx_ops.value(meta, self._items)
if isinstance(state, _Done) or not items:
return succeed(None)
self._remove(meta, state, items, 1)
return succeed(Some(items[0]))
return _tx_ops.decide(decide)peek#
peek() -> Effect[A, E]Wait for an item and succeed with it, leaving it in the queue.
Returns Effect[A, E]
def peek(self) -> Effect[A, E]:
"""Wait for an item and succeed with it, leaving it in the queue."""
def decide(meta: TransactionMeta) -> _Step[A, E]:
state = _tx_ops.value(meta, self._state)
if isinstance(state, _Done):
return fail_with(state.cause)
items = _tx_ops.value(meta, self._items)
return succeed(items[0]) if items else tx_retry
return _tx_ops.decide(decide)take_all#
take_all() -> Effect[list[A], E]Wait for at least one item, then take them all.
Returns Effect[list[A], E]
def take_all(self) -> Effect[list[A], E]:
"""Wait for at least one item, then take them all."""
def decide(meta: TransactionMeta) -> _Step[list[A], E]:
state = _tx_ops.value(meta, self._state)
if isinstance(state, _Done):
return fail_with(state.cause)
items = _tx_ops.value(meta, self._items)
if not items:
return tx_retry
self._remove(meta, state, items, len(items))
return succeed(list(items))
return _tx_ops.decide(decide)take_n#
take_n(n) -> Effect[list[A], E]Wait for n items and take them. A bounded queue never holds
more than its capacity, so asking for more takes that many; a closing
queue gives what is left. A count of 0 or less takes nothing.
| Parameter | Type | Description |
|---|---|---|
n | int |
Returns Effect[list[A], E]
def take_n(self, n: int) -> Effect[list[A], E]:
"""Wait for ``n`` items and take them. A bounded queue never holds
more than its capacity, so asking for more takes that many; a closing
queue gives what is left. A count of 0 or less takes nothing."""
wanted = max(n, 0)
minimum = wanted if self._capacity is None else min(wanted, self._capacity)
return self._take_at_least(minimum, minimum)take_between#
take_between(minimum, maximum) -> Effect[list[A], E]Wait for minimum items, then take up to maximum; a closing
queue gives what is left. Takes nothing if either count is 0 or less,
or minimum > maximum.
| Parameter | Type | Description |
|---|---|---|
minimum | int | |
maximum | int |
Returns Effect[list[A], E]
def take_between(self, minimum: int, maximum: int) -> Effect[list[A], E]:
"""Wait for ``minimum`` items, then take up to ``maximum``; a closing
queue gives what is left. Takes nothing if either count is 0 or less,
or ``minimum > maximum``."""
if minimum <= 0 or maximum <= 0 or minimum > maximum:
return self._take_at_least(0, 0)
return self._take_at_least(minimum, maximum)clear#
clear[AA]() -> Effect[list[AA], Never]
clear[AA, EE]() -> Effect[list[AA], EE]
clear() -> Effect[list[A], E]Take every item there is now, without waiting. On a queue that is
done: [] if it was ended, otherwise fails with its cause.
@overload
def clear[AA](self: TxQueue[AA, Done[Any]]) -> Effect[list[AA], Never]: ...
@overload
def clear[AA, EE](self: TxQueue[AA, EE | Done[Any]]) -> Effect[list[AA], EE]: ...
@overload
def clear(self) -> Effect[list[A], E]: ...
def clear(self: TxQueue[Any, Any]) -> Effect[list[Any], Any]:
"""Take every item there is now, without waiting. On a queue that is
done: ``[]`` if it was ended, otherwise fails with its cause."""
def decide(meta: TransactionMeta) -> _Step[list[Any], Any]:
state = _tx_ops.value(meta, self._state)
if isinstance(state, _Done):
return succeed([]) if is_done_cause(state.cause) else fail_with(state.cause)
items = _tx_ops.value(meta, self._items)
_tx_ops.write(meta, self._items, ())
if isinstance(state, _Closing):
_tx_ops.write(meta, self._state, _Done(state.cause))
return succeed(list(items))
return _tx_ops.decide(decide)size#
size() -> Effect[int]Returns Effect[int]
def size(self) -> Effect[int]:
return _tx_ops.read(self._items, len)is_empty#
is_empty() -> Effect[bool]Returns Effect[bool]
def is_empty(self) -> Effect[bool]:
return _tx_ops.read(self._items, lambda items: not items)is_non_empty#
is_non_empty() -> Effect[bool]Returns Effect[bool]
def is_non_empty(self) -> Effect[bool]:
return _tx_ops.read(self._items, bool)is_full#
is_full() -> Effect[bool]Returns Effect[bool]
def is_full(self) -> Effect[bool]:
capacity = self._capacity
if capacity is None:
return succeed(False)
return _tx_ops.read(self._items, lambda items: len(items) >= capacity)is_open#
is_open() -> Effect[bool]Returns Effect[bool]
def is_open(self) -> Effect[bool]:
return self._state_is(_Open)is_closing#
is_closing() -> Effect[bool]Returns Effect[bool]
def is_closing(self) -> Effect[bool]:
return self._state_is(_Closing)is_done#
is_done() -> Effect[bool]Returns Effect[bool]
def is_done(self) -> Effect[bool]:
return self._state_is(_Done)is_shutdown#
is_shutdown() -> Effect[bool]is_done.
Returns Effect[bool]
def is_shutdown(self) -> Effect[bool]:
"""``is_done``."""
return self.is_done()await_completion#
await_completion() -> Effect[None]Wait until the queue is done, however it finished.
Returns Effect[None]
def await_completion(self) -> Effect[None]:
"""Wait until the queue is done, however it finished."""
def decide(meta: TransactionMeta) -> _Step[None, Never]:
done = isinstance(_tx_ops.value(meta, self._state), _Done)
return succeed(None) if done else tx_retry
return _tx_ops.decide(decide)