GitHub

TxPriorityQueue

API reference for TxPriorityQueue.

class TxPriorityQueue[A = Unsubscripted]

TxPriorityQueue(ref, key) wraps an existing TxRef of sorted items (Effect's makeUnsafe); empty, from_iterable and make are the effects. Without key, items compare as they are.

Attributes

AttributeTypeDescription
refTxRef[tuple[A, ...]]

The items, sorted.

keyKey[A]

Functions

__init__

__init__(ref, key) -> None
ParameterTypeDescription
refTxRef[tuple[A, ...]]
keyKey[A]
def __init__(self, ref: TxRef[tuple[A, ...]], key: Key[A]) -> None:
    self._ref = ref
    self._key = key

empty

empty[T: SupportsRichComparison]() -> Effect[TxPriorityQueue[T]]
empty(*, key: Key[A]) -> Effect[TxPriorityQueue[A]]

Spelled TxPriorityQueue[int].empty() or TxPriorityQueue[Task].empty(key=priority).

ParameterTypeDescription
key= _identity
@overload
@classmethod
def empty[T: SupportsRichComparison](
    cls: type[TxPriorityQueue[T]],
) -> Effect[TxPriorityQueue[T]]: ...
@overload
@classmethod
def empty(cls, *, key: Key[A]) -> Effect[TxPriorityQueue[A]]: ...
@classmethod
def empty(cls, *, key: Key[Any] = _identity) -> Effect[TxPriorityQueue[Any]]:
    """Spelled ``TxPriorityQueue[int].empty()`` or
    ``TxPriorityQueue[Task].empty(key=priority)``."""
    empty: tuple[Any, ...] = ()
    return TxRef.make(empty).map(lambda ref: TxPriorityQueue(ref, key))

from_iterable

from_iterable[T: SupportsRichComparison](items: Iterable[T]) -> Effect[TxPriorityQueue[T]]
from_iterable[T](items: Iterable[T], *, key: Key[T]) -> Effect[TxPriorityQueue[T]]
from_iterable[T: SupportsRichComparison](items: Iterable[T]) -> Effect[TxPriorityQueue[T]]
from_iterable(items: Iterable[A], *, key: Key[A]) -> Effect[TxPriorityQueue[A]]

A new queue each time the effect runs. items is read once, here, so a one-shot iterator survives transaction retries. TxPriorityQueue[A].from_iterable(...) takes the subscript.

ParameterTypeDescription
items
key= _identity
@overload
@classmethod
def from_iterable[T: SupportsRichComparison](
    cls: type[TxPriorityQueue[Unsubscripted]], items: Iterable[T]
) -> Effect[TxPriorityQueue[T]]: ...
@overload
@classmethod
def from_iterable[T](
    cls: type[TxPriorityQueue[Unsubscripted]], items: Iterable[T], *, key: Key[T]
) -> Effect[TxPriorityQueue[T]]: ...
@overload
@classmethod
def from_iterable[T: SupportsRichComparison](
    cls: type[TxPriorityQueue[T]], items: Iterable[T]
) -> Effect[TxPriorityQueue[T]]: ...
@overload
@classmethod
def from_iterable(cls, items: Iterable[A], *, key: Key[A]) -> Effect[TxPriorityQueue[A]]: ...
@classmethod
def from_iterable(
    cls, items: Iterable[Any], *, key: Key[Any] = _identity
) -> Effect[TxPriorityQueue[Any]]:
    """A new queue each time the effect runs. ``items`` is read once,
    here, so a one-shot iterator survives transaction retries.
    ``TxPriorityQueue[A].from_iterable(...)`` takes the subscript."""
    initial = tuple(sorted(items, key=key))
    return TxRef.make(initial).map(lambda ref: TxPriorityQueue(ref, key))

make

make[T: SupportsRichComparison](*items: T = ()) -> Effect[TxPriorityQueue[T]]
make[T](*items: T = (), key: Key[T]) -> Effect[TxPriorityQueue[T]]
make[T: SupportsRichComparison](*items: T = ()) -> Effect[TxPriorityQueue[T]]
make(*items: A = (), key: Key[A]) -> Effect[TxPriorityQueue[A]]
ParameterTypeDescription
items= ()
key= _identity
@overload
@classmethod
def make[T: SupportsRichComparison](
    cls: type[TxPriorityQueue[Unsubscripted]], *items: T
) -> Effect[TxPriorityQueue[T]]: ...
@overload
@classmethod
def make[T](
    cls: type[TxPriorityQueue[Unsubscripted]], *items: T, key: Key[T]
) -> Effect[TxPriorityQueue[T]]: ...
@overload
@classmethod
def make[T: SupportsRichComparison](
    cls: type[TxPriorityQueue[T]], *items: T
) -> Effect[TxPriorityQueue[T]]: ...
@overload
@classmethod
def make(cls, *items: A, key: Key[A]) -> Effect[TxPriorityQueue[A]]: ...
@classmethod
def make(cls, *items: Any, key: Key[Any] = _identity) -> Effect[TxPriorityQueue[Any]]:
    return TxPriorityQueue.from_iterable(items, key=key)

size

size() -> Effect[int]

Returns Effect[int]

def size(self) -> Effect[int]:
    return _tx_ops.read(self._ref, len)

is_empty

is_empty() -> Effect[bool]

Returns Effect[bool]

def is_empty(self) -> Effect[bool]:
    return _tx_ops.read(self._ref, 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._ref, bool)

peek

peek() -> Effect[A]

The smallest item, left in the queue; waits while it is empty.

Returns Effect[A]

def peek(self) -> Effect[A]:
    """The smallest item, left in the queue; waits while it is empty."""

    def decide(state: TransactionMeta) -> Effect[A, Never, Transaction]:
        items = _tx_ops.value(state, self._ref)
        return succeed(items[0]) if items else tx_retry

    return _tx_ops.decide(decide)

peek_option

peek_option() -> Effect[Option[A]]

Some of the smallest item, or None if the queue is empty.

Returns Effect[Option[A]]

def peek_option(self) -> Effect[Option[A]]:
    """``Some`` of the smallest item, or ``None`` if the queue is empty."""
    return _tx_ops.read(self._ref, lambda items: Some(items[0]) if items else None)

offer

offer(item) -> Effect[None]
ParameterTypeDescription
itemA

Returns Effect[None]

def offer(self, item: A) -> Effect[None]:
    return self._ref.update(lambda items: _merge_sorted(items, [item], self._key))

offer_all

offer_all(items) -> Effect[None]

Add several items. items is read once, here, so a one-shot iterator survives transaction retries.

ParameterTypeDescription
itemsIterable[A]

Returns Effect[None]

def offer_all(self, items: Iterable[A]) -> Effect[None]:
    """Add several items. ``items`` is read once, here, so a one-shot
    iterator survives transaction retries."""
    added = sorted(items, key=self._key)
    return self._ref.update(lambda current: _merge_sorted(current, added, self._key))

take

take() -> Effect[A]

Remove and succeed with the smallest item; waits while the queue is empty.

Returns Effect[A]

def take(self) -> Effect[A]:
    """Remove and succeed with the smallest item; waits while the queue
    is empty."""

    def decide(state: TransactionMeta) -> Effect[A, Never, Transaction]:
        items = _tx_ops.value(state, self._ref)
        if not items:
            return tx_retry
        _tx_ops.write(state, self._ref, items[1:])
        return succeed(items[0])

    return _tx_ops.decide(decide)

take_all

take_all() -> Effect[list[A]]

Remove every item, smallest first.

Returns Effect[list[A]]

def take_all(self) -> Effect[list[A]]:
    """Remove every item, smallest first."""
    return self._ref.modify(lambda items: (list(items), ()))

take_option

take_option() -> Effect[Option[A]]

Remove the smallest item if there is one.

Returns Effect[Option[A]]

def take_option(self) -> Effect[Option[A]]:
    """Remove the smallest item if there is one."""
    return self._ref.modify(
        lambda items: (Some(items[0]), items[1:]) if items else (None, items)
    )

take_up_to

take_up_to(n) -> Effect[list[A]]

Remove up to n of the smallest items; none when n is 0 or less.

ParameterTypeDescription
nint

Returns Effect[list[A]]

def take_up_to(self, n: int) -> Effect[list[A]]:
    """Remove up to ``n`` of the smallest items; none when ``n`` is 0 or
    less."""
    count = max(n, 0)
    return self._ref.modify(lambda items: (list(items[:count]), items[count:]))

remove_if

remove_if(predicate) -> Effect[None]
ParameterTypeDescription
predicateCallable[[A], bool]

Returns Effect[None]

def remove_if(self, predicate: Callable[[A], bool]) -> Effect[None]:
    return self._ref.update(lambda items: tuple(item for item in items if not predicate(item)))

retain_if

retain_if(predicate) -> Effect[None]
ParameterTypeDescription
predicateCallable[[A], bool]

Returns Effect[None]

def retain_if(self, predicate: Callable[[A], bool]) -> Effect[None]:
    return self._ref.update(lambda items: tuple(item for item in items if predicate(item)))

to_list

to_list() -> Effect[list[A]]

The items, smallest first (Effect's toArray).

Returns Effect[list[A]]

def to_list(self) -> Effect[list[A]]:
    """The items, smallest first (Effect's ``toArray``)."""
    return _tx_ops.read(self._ref, list)