Forward declaration of the keyed typed queue. More...
#include <StormByte/buffer/sink.hxx>
Classes | |
| class | Lane |
One-key redirect: from.To(key) >> dest. More... | |
Public Types | |
| using | Select = StormByte::Safe::Function<StormByte::Size(StormByte::Size)> |
| Index chooser for Pop selection across multiple buckets. | |
Public Member Functions | |
Lifecycle | |
| Sink () | |
| Constructs an empty Sink with zero buckets. | |
| Sink (const Sink &)=delete | |
| Sink (Sink &&) noexcept=delete | |
| ~Sink () noexcept | |
| Removes borrowed observers, closes writer holds and releases the coordinator after all users are joined. | |
| Sink & | operator= (const Sink &)=delete |
| Sink & | operator= (Sink &&) noexcept=delete |
Producer | |
| void | Push (int key, T item) noexcept |
| Pushes an item into the bucket specified by key. | |
| QueueStatus | TryPush (int key, T &item, StormByte::ByteSize bytes) noexcept |
| Attempt a weighted admission to an existing bucket. | |
| QueueStatus | TryPush (int key, T &item, const ByteBudget::Lease &lease) noexcept |
| Admit using a shared payload charge without charging twice. | |
| QueueStatus | PushFor (int key, T &item, StormByte::ByteSize bytes, std::chrono::milliseconds timeout, AdmissionWaitObserver observer={}) noexcept |
| Weighted admission with a bounded wait, cancellable by this Sink's closure. | |
| QueueStatus | PushFor (int key, T &item, const ByteBudget::Lease &lease, std::chrono::milliseconds timeout, AdmissionWaitObserver observer={}) noexcept |
| Shared-charge admission with a bounded wait. | |
| QueueStatus | Limits (int key, QueueLimits limits) noexcept |
| Configure independent local limits on an existing shared hopper. | |
| QueueStatus | Configure (int key, QueueLimits limits, const ByteBudget &budget) noexcept |
| Attach local limits and aggregate accounting to an empty, idle bucket. | |
| QueueSnapshot | Snapshot (int key) const noexcept |
| Read shared-hopper counters without waiting for capacity or doing I/O. | |
| void | CancelPending (int key) noexcept |
| Cancel weighted admissions currently waiting on a shared hopper. | |
| void | Eof () noexcept |
| Closes the Sink and releases writer holds on its hoppers. | |
| void | Abort () noexcept |
| Closes every connected hopper and discards queued items. | |
Wiring & Connection | |
| Lane | To (int key) noexcept |
| Redirect of one hopper key. | |
| Sink & | operator>> (Sink &dest) noexcept |
Share every existing hopper with dest. | |
| Sink & | operator<< (Sink &src) noexcept |
Same as src >> *this (all hoppers). | |
| Sink & | operator<< (Lane lane) noexcept |
Same as lane >> *this. | |
| void | Drain () noexcept |
| Marks Sink as a terminal producer (un-wired Push calls drop instead of waiting). | |
| bool | Draining () const noexcept |
| Checks whether Drain was called. | |
| void | Notify (Safe::ConditionVariable &consumer) noexcept |
| Registers consumer condition variable to notify on all current and future hoppers. | |
| void | Notify (Safe::ConditionVariable &consumer, Safe::Atomic< std::size_t > &generation) noexcept |
| Registers stored notifications on current and future hoppers and Sink closure. | |
| void | Unnotify () noexcept |
| Removes only this Sink's matching borrowed registrations. | |
Bucket Capacity & Query | |
| StormByte::Safe::Vector< int > | Keys () const noexcept |
| Keys of hoppers currently wired on this Sink. | |
| StormByte::Size | Buckets () const noexcept |
| Number of hoppers wired on this Sink. | |
| bool | Contains (int key) const noexcept |
Whether hopper key exists on this Sink. | |
| StormByte::Size | Capacity (int key) const noexcept |
| Gets capacity ceiling of bucket key. | |
| void | Capacity (int key, StormByte::Size capacity) noexcept |
| Sets capacity ceiling of bucket key. | |
| StormByte::Size | Size (int key) const noexcept |
| Gets pending item count in bucket key. | |
| bool | Full (int key) const noexcept |
| Checks if bucket key is full. | |
| bool | Empty (int key) const noexcept |
Whether bucket key has no pending items. | |
| bool | EoF (int key) const noexcept |
Whether producers marked Eof on bucket key. | |
| bool | Ready (int key) const noexcept |
Whether Pop(int) on key can return an item or that hopper is finished. | |
| T | Front (int key) const noexcept |
Copy of the next item in bucket key without dequeuing. | |
Consumer | |
| T | Pop () noexcept |
| Pops one item from the Sink using default round-robin order. | |
| T | Pop (const Select &select) noexcept |
| Pops one item from the Sink using a custom selection function. | |
| template<typename Selector> requires (!Type::SameAs<std::remove_cvref_t<Selector>, Select>) && requires(Selector& select, StormByte::Size count) { { std::invoke(select, count) } -> Type::SameAs<StormByte::Size>; } | |
| T | Pop (Selector &&select) noexcept |
| Pops using a synchronously borrowed callable without copying its captures. | |
| T | Pop (int key) noexcept |
Pops one item from bucket key only. | |
| bool | EoF () const noexcept |
| Checks if the Sink is finished. | |
| bool | Ready () const noexcept |
| Checks whether a Pop call can return immediately (item available or EoF). | |
Forward declaration of the keyed typed queue.
Set of Hopper buckets keyed by an integer.
| T | Supported Safe value. |
Sink manages a collection of Hopper queues keyed by an integer (representing channels, tracks, sessions, etc.). Sink does not interpret the integer key.
Key characteristics:
producer >> consumer shares every existing hopper. producer.To(key) >> consumer creates or shares one key. When this Sink already holds that hopper, dest is a co-writer: Eof on this Sink then only closes the hopper when the last writer closes. consumer << producer and consumer << producer.To(key) are the same edges.| T | SafeValue satisfying the same nonthrowing movement and alignment contract as Hopper. |
| using StormByte::Buffer::Sink< T >::Select = StormByte::Safe::Function<StormByte::Size(StormByte::Size)> |
Index chooser for Pop selection across multiple buckets.
Given the count of active buckets, returns an index in range [0, count). A Select is borrowed for the synchronous Pop call and is not retained. Call must report Success before any item is removed. Missing, Failure or an exception returns default T. The callback provider owns and releases its captures and must remain loaded through callback destruction. Construction requires provider-owned context plus Invoke, Clone and Release callbacks. Copies clone independent provider-owned context.
| StormByte::Buffer::Sink< T >::Sink | ( | ) |
Constructs an empty Sink with zero buckets.
| AllocationError | The coordinator cannot be allocated. |
|
delete |
|
deletenoexcept |
|
noexcept |
Removes borrowed observers, closes writer holds and releases the coordinator after all users are joined.
|
noexcept |
Closes every connected hopper and discards queued items.
Unlike Eof, Abort does not preserve buffered items or wait for the last writer. It is idempotent, allocation-free and wakes blocked producers and consumers.
|
noexcept |
|
noexcept |
Cancel weighted admissions currently waiting on a shared hopper.
| key | Existing bucket key. |
|
noexcept |
Gets capacity ceiling of bucket key.
| key | Bucket key identifier. |
|
noexcept |
Sets capacity ceiling of bucket key.
| key | Bucket key identifier. |
| capacity | Maximum items allowed (0 = unbounded). |
|
noexcept |
Attach local limits and aggregate accounting to an empty, idle bucket.
| key | Existing bucket key. |
| limits | Local ceilings. |
| budget | Shared queue/work budget. |
|
noexcept |
Whether hopper key exists on this Sink.
| key | Bucket key identifier. |
|
noexcept |
Marks Sink as a terminal producer (un-wired Push calls drop instead of waiting).
|
noexcept |
Checks whether Drain was called.
|
noexcept |
Whether bucket key has no pending items.
| key | Bucket key identifier. |
|
noexcept |
Checks if the Sink is finished.
Contract details for EoF():
|
noexcept |
Whether producers marked Eof on bucket key.
| key | Bucket key identifier. |
|
noexcept |
|
noexcept |
Copy of the next item in bucket key without dequeuing.
| key | Bucket key identifier. |
Does not block and does not wake producers. Requires nonthrowing Type::CopyConstructible. Not a deep copy of the payload. Does not read any other key.
|
noexcept |
Checks if bucket key is full.
| key | Bucket key identifier. |
|
noexcept |
Keys of hoppers currently wired on this Sink.
Snapshot. Does not create buckets. Sink does not interpret keys.
|
noexcept |
Configure independent local limits on an existing shared hopper.
| key | Bucket key. |
| limits | Optional local ceilings; zero is an active zero limit. |
|
noexcept |
Registers consumer condition variable to notify on all current and future hoppers.
| consumer | Consumer condition variable reference. Not owned. |
|
noexcept |
Registers stored notifications on current and future hoppers and Sink closure.
| consumer | Borrowed consumer condition variable. |
| generation | Borrowed event counter, incremented with release ordering. |
|
noexcept |
|
noexcept |
|
delete |
|
deletenoexcept |
|
noexcept |
|
noexcept |
|
noexcept |
Pops one item from the Sink using a custom selection function.
| select | Bucket index selection callback. |
Borrows the callback by const reference without copying or retaining it. Blocks while zero buckets exist and Sink is not closed. A throwing selector returns default T and leaves queued items untouched. A non-Success status does likewise, even when only one bucket exists.
|
noexcept |
Pops one item from bucket key only.
| key | Bucket key identifier. |
Waits until the key exists or the Sink is closed. Does not wait for an item: an empty hopper returns default T (same as Hopper::Pop). Does not read any other key. Sink does not interpret key.
|
noexcept |
Pops using a synchronously borrowed callable without copying its captures.
| select | Callable kept alive until this call returns; never retained. |
|
noexcept |
Pushes an item into the bucket specified by key.
| key | Integer bucket identifier. |
| item | Item to enqueue. Empty smart pointers are discarded. |
Waits until the bucket exists, the Sink is closed, or Drain is set. A closed Sink discards the item; Drain discards it only if the key is missing. A call already handed to a shared Hopper is not cancelled by this Sink's Eof: it may wait for capacity or the final writer's Eof. Join all calls before destruction.
|
noexcept |
Shared-charge admission with a bounded wait.
| key | Existing bucket key. |
| item | Moved only on success. |
| lease | Shared payload charge. |
| timeout | Nonnegative wait bound; zero is immediate. |
| observer | Borrowed observer of actual admission waits only. |
|
noexcept |
Weighted admission with a bounded wait, cancellable by this Sink's closure.
| key | Existing bucket key. |
| item | Moved only on success. |
| bytes | Caller-defined weight. |
| timeout | Nonnegative wait bound; zero is immediate. |
| observer | Borrowed observer of actual admission waits only. |
|
noexcept |
Checks whether a Pop call can return immediately (item available or EoF).
|
noexcept |
Whether Pop(int) on key can return an item or that hopper is finished.
| key | Bucket key identifier. |
|
noexcept |
Gets pending item count in bucket key.
| key | Bucket key identifier. |
|
noexcept |
Read shared-hopper counters without waiting for capacity or doing I/O.
| key | Bucket key. |
|
noexcept |
|
noexcept |
Admit using a shared payload charge without charging twice.
| key | Existing bucket key. |
| item | Moved only on success. |
| lease | Charge belonging to the configured budget. |
|
noexcept |
Attempt a weighted admission to an existing bucket.
| key | Bucket key; no implicit wiring wait. |
| item | Moved only on success. |
| bytes | Caller-defined logical weight. |
|
noexcept |
Removes only this Sink's matching borrowed registrations.
Call after Eof when the consumer condition variable is about to die. Waits for active notifications and wiring; a newer registration made by another Sink is preserved. Destruction also removes this registration. Registration must not race destruction of any borrowed condition variable or event counter.