GitHub

API reference for TxQueue.

class TxQueue[A, E = Never]

Build one with TxQueue[int].bounded(8) (or unbounded, dropping, sliding); TxQueue[int, Done] can be ended.

Attributes

AttributeTypeDescription
strategyStrategy
capacityint | None

How many items the queue holds; None if unbounded.

Functions

__init__

__init__(strategy, capacity) -> None
ParameterTypeDescription
strategyStrategy
capacityint | 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.

ParameterTypeDescription
capacityint

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.

ParameterTypeDescription
capacityint

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.

ParameterTypeDescription
capacityint

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.

ParameterTypeDescription
itemA

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.

ParameterTypeDescription
itemsIterable[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.

ParameterTypeDescription
errorE

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.

ParameterTypeDescription
causeCause[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.

ParameterTypeDescription
nint

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.

ParameterTypeDescription
minimumint
maximumint

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)