GitHub

TxPubSub

API reference for TxPubSub.

class TxPubSub[A]

Build one with TxPubSub[int].bounded(16) (or unbounded, dropping, sliding). isinstance(x, TxPubSub) is Effect's isTxPubSub.

Attributes

AttributeTypeDescription
strategyStrategy
capacityint | None

Each subscriber's capacity; 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._subscribers: TxRef[tuple[TxQueue[A], ...]] = TxRef(())
    self._shutdown = TxRef(False)

bounded

bounded(capacity) -> Effect[TxPubSub[A]]

publish waits while a subscriber holds capacity values.

ParameterTypeDescription
capacityint

Returns Effect[TxPubSub[A]]

@classmethod
def bounded(cls, capacity: int) -> Effect[TxPubSub[A]]:
    """``publish`` waits while a subscriber holds ``capacity`` values."""
    return cls._make("bounded", capacity)

unbounded

unbounded() -> Effect[TxPubSub[A]]

Returns Effect[TxPubSub[A]]

@classmethod
def unbounded(cls) -> Effect[TxPubSub[A]]:
    return cls._make("unbounded", None)

dropping

dropping(capacity) -> Effect[TxPubSub[A]]

A full subscriber misses the new value.

ParameterTypeDescription
capacityint

Returns Effect[TxPubSub[A]]

@classmethod
def dropping(cls, capacity: int) -> Effect[TxPubSub[A]]:
    """A full subscriber misses the new value."""
    return cls._make("dropping", capacity)

sliding

sliding(capacity) -> Effect[TxPubSub[A]]

A full subscriber drops its oldest value for the new one.

ParameterTypeDescription
capacityint

Returns Effect[TxPubSub[A]]

@classmethod
def sliding(cls, capacity: int) -> Effect[TxPubSub[A]]:
    """A full subscriber drops its oldest value for the new one."""
    return cls._make("sliding", capacity)

size

size() -> Effect[int]

The most values any subscriber has waiting; 0 without subscribers.

Returns Effect[int]

def size(self) -> Effect[int]:
    """The most values any subscriber has waiting; 0 without
    subscribers."""
    return tx(self._each(lambda queue: queue.size()).map(lambda sizes: max(sizes, default=0)))

is_empty

is_empty() -> Effect[bool]

Returns Effect[bool]

def is_empty(self) -> Effect[bool]:
    return self.size().map(lambda size: size == 0)

is_non_empty

is_non_empty() -> Effect[bool]

Returns Effect[bool]

def is_non_empty(self) -> Effect[bool]:
    return self.size().map(lambda size: size > 0)

is_full

is_full() -> Effect[bool]

Whether any subscriber's queue is at capacity.

Returns Effect[bool]

def is_full(self) -> Effect[bool]:
    """Whether any subscriber's queue is at capacity."""
    if self._capacity is None:
        return succeed(False)
    return tx(self._each(lambda queue: queue.is_full()).map(any))

is_shutdown

is_shutdown() -> Effect[bool]

Returns Effect[bool]

def is_shutdown(self) -> Effect[bool]:
    return self._shutdown.get()

publish

publish(value) -> Effect[bool]

Offer value to every subscriber. False if the hub is shut down or a dropping subscriber was full; True without subscribers.

ParameterTypeDescription
valueA

Returns Effect[bool]

def publish(self, value: A) -> Effect[bool]:
    """Offer ``value`` to every subscriber. ``False`` if the hub is shut
    down or a dropping subscriber was full; ``True`` without
    subscribers."""
    return self.publish_all((value,))

publish_all

publish_all(values) -> Effect[bool]

Publish each value in one transaction; False if the hub is shut down or any value was dropped for a subscriber. values is read once, here, so a one-shot iterator survives transaction retries.

ParameterTypeDescription
valuesIterable[A]

Returns Effect[bool]

def publish_all(self, values: Iterable[A]) -> Effect[bool]:
    """Publish each value in one transaction; ``False`` if the hub is shut
    down or any value was dropped for a subscriber. ``values`` is read
    once, here, so a one-shot iterator survives transaction retries."""
    batch = tuple(values)

    @gen
    def body():
        if (yield from self._shutdown.get()):
            return False
        subscribers = yield from self._subscribers.get()
        accepted = True
        for value in batch:
            for queue in subscribers:
                accepted = (yield from queue.offer(value)) and accepted
        return accepted

    return tx(body)

subscribe

subscribe() -> Effect[TxDequeue[A, Never], Never, Scope]

A queue of the values published from now on, until the current scope closes.

Returns Effect[TxDequeue[A, Never], Never, Scope]

def subscribe(self) -> Effect[TxDequeue[A, Never], Never, Scope]:
    """A queue of the values published from now on, until the current
    scope closes."""
    return acquire_release(
        self.acquire_subscriber(), lambda queue, _: self.release_subscriber(queue)
    )

acquire_subscriber

acquire_subscriber() -> Effect[TxDequeue[A, Never]]

Add a subscriber, in the running transaction or one of its own. Pair it with release_subscriber; subscribe does both.

Returns Effect[TxDequeue[A, Never]]

def acquire_subscriber(self) -> Effect[TxDequeue[A, Never]]:
    """Add a subscriber, in the running transaction or one of its own.
    Pair it with ``release_subscriber``; ``subscribe`` does both."""
    return self._acquire_queue()

release_subscriber

release_subscriber(queue) -> Effect[None]

Remove queue's subscriber and shut its queue down.

ParameterTypeDescription
queueTxDequeue[A, Never]

Returns Effect[None]

def release_subscriber(self, queue: TxDequeue[A, Never]) -> Effect[None]:
    """Remove ``queue``'s subscriber and shut its queue down."""

    @gen
    def body():
        subscribers = yield from self._subscribers.get()
        mine = tuple(q for q in subscribers if q is queue)
        if mine:
            yield from self._subscribers.set(tuple(q for q in subscribers if q is not queue))
        yield from for_each(mine, lambda q: q.shutdown())

    return tx(body)

shutdown

shutdown() -> Effect[None]

Stop accepting values and shut every subscriber's queue down. Shutting down twice does nothing more.

Returns Effect[None]

def shutdown(self) -> Effect[None]:
    """Stop accepting values and shut every subscriber's queue down.
    Shutting down twice does nothing more."""

    @gen
    def body():
        if (yield from self._shutdown.get()):
            return
        yield from self._shutdown.set(True)
        yield from self._each(lambda queue: queue.shutdown())

    return tx(body)

await_shutdown

await_shutdown() -> Effect[None]

Wait until the hub is shut down.

Returns Effect[None]

def await_shutdown(self) -> Effect[None]:
    """Wait until the hub is shut down."""

    def decide(meta: TransactionMeta) -> Effect[None, Never, Transaction]:
        return succeed(None) if _tx_ops.value(meta, self._shutdown) else tx_retry

    return _tx_ops.decide(decide)