StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Buffer::Sink< T > Class Template Reference

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).

Detailed Description

template<Detail::HopperValue T>
class StormByte::Buffer::Sink< T >

Forward declaration of the keyed typed queue.

Set of Hopper buckets keyed by an integer.

Template Parameters
TSupported 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:

  • Wiring: 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.
  • Drain: Terminal producer flag. Push to an un-wired key discards the item without waiting for a consumer.
  • Pop: Retrieves items across buckets using Round-Robin, custom Select, or a single key (Pop(int)).
  • Query: Keys, Contains, per-key Size/Capacity/Full/Empty/EoF/Ready/Front.
  • EoF: Closes the Sink and CloseWriter on hoppers this Sink writes.
Template Parameters
TSafeValue satisfying the same nonthrowing movement and alignment contract as Hopper.
Note
Stop and join all users before destruction. Unnotify must finish before a borrowed condition variable dies. Base and all template, element and callback provider modules must remain loaded, with compatible C++/STL ABI. Template callbacks are not certified provider-local merely because they are inline. Allocation failure in the nonthrowing queue operations terminates the process.

Member Typedef Documentation

◆ Select

template<Detail::HopperValue T>
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.

Constructor & Destructor Documentation

◆ Sink() [1/3]

template<Detail::HopperValue T>
StormByte::Buffer::Sink< T >::Sink ( )

Constructs an empty Sink with zero buckets.

Exceptions
AllocationErrorThe coordinator cannot be allocated.

◆ Sink() [2/3]

template<Detail::HopperValue T>
StormByte::Buffer::Sink< T >::Sink ( const Sink< T > & )
delete

◆ Sink() [3/3]

template<Detail::HopperValue T>
StormByte::Buffer::Sink< T >::Sink ( Sink< T > && )
deletenoexcept

◆ ~Sink()

template<Detail::HopperValue T>
StormByte::Buffer::Sink< T >::~Sink ( )
noexcept

Removes borrowed observers, closes writer holds and releases the coordinator after all users are joined.

Member Function Documentation

◆ Abort()

template<Detail::HopperValue T>
void StormByte::Buffer::Sink< T >::Abort ( )
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.

◆ Buckets()

template<Detail::HopperValue T>
StormByte::Size StormByte::Buffer::Sink< T >::Buckets ( ) const
noexcept

Number of hoppers wired on this Sink.

Returns
Keys size.

◆ CancelPending()

template<Detail::HopperValue T>
void StormByte::Buffer::Sink< T >::CancelPending ( int key)
noexcept

Cancel weighted admissions currently waiting on a shared hopper.

Parameters
keyExisting bucket key.

◆ Capacity() [1/2]

template<Detail::HopperValue T>
StormByte::Size StormByte::Buffer::Sink< T >::Capacity ( int key) const
noexcept

Gets capacity ceiling of bucket key.

Parameters
keyBucket key identifier.
Returns
Hopper capacity, or 0 if key bucket does not exist.

◆ Capacity() [2/2]

template<Detail::HopperValue T>
void StormByte::Buffer::Sink< T >::Capacity ( int key,
StormByte::Size capacity )
noexcept

Sets capacity ceiling of bucket key.

Parameters
keyBucket key identifier.
capacityMaximum items allowed (0 = unbounded).

◆ Configure()

template<Detail::HopperValue T>
QueueStatus StormByte::Buffer::Sink< T >::Configure ( int key,
QueueLimits limits,
const ByteBudget & budget )
noexcept

Attach local limits and aggregate accounting to an empty, idle bucket.

Parameters
keyExisting bucket key.
limitsLocal ceilings.
budgetShared queue/work budget.
Returns
Ok, Missing or Invalid without partial changes.

◆ Contains()

template<Detail::HopperValue T>
bool StormByte::Buffer::Sink< T >::Contains ( int key) const
noexcept

Whether hopper key exists on this Sink.

Parameters
keyBucket key identifier.
Returns
true if the key is wired.

◆ Drain()

template<Detail::HopperValue T>
void StormByte::Buffer::Sink< T >::Drain ( )
noexcept

Marks Sink as a terminal producer (un-wired Push calls drop instead of waiting).

◆ Draining()

template<Detail::HopperValue T>
bool StormByte::Buffer::Sink< T >::Draining ( ) const
noexcept

Checks whether Drain was called.

Returns
true if Drain was set.

◆ Empty()

template<Detail::HopperValue T>
bool StormByte::Buffer::Sink< T >::Empty ( int key) const
noexcept

Whether bucket key has no pending items.

Parameters
keyBucket key identifier.
Returns
true if the key is missing or the hopper is empty.

◆ EoF() [1/2]

template<Detail::HopperValue T>
bool StormByte::Buffer::Sink< T >::EoF ( ) const
noexcept

Checks if the Sink is finished.

Returns
true if no items remain and no new items can arrive in the current hoppers.

Contract details for EoF():

  • With zero hoppers: EoF() returns true only if this Sink is closed (via Eof() or destruction).
  • With hoppers: EoF() returns true when all hoppers are empty and Hopper::EoF() is true, even if this Sink itself did not call Eof() (because wiring shares the Hopper and the producer closed it from the other Sink).
  • Wiring a new key after EoF() returned true may cause EoF() to return false again if new work becomes available.
  • EoF() does not mean "this object called Eof()", but "no items remain and none can enter current buckets".

◆ EoF() [2/2]

template<Detail::HopperValue T>
bool StormByte::Buffer::Sink< T >::EoF ( int key) const
noexcept

Whether producers marked Eof on bucket key.

Parameters
keyBucket key identifier.
Returns
Hopper EoF, or false if the key does not exist.

◆ Eof()

template<Detail::HopperValue T>
void StormByte::Buffer::Sink< T >::Eof ( )
noexcept

Closes the Sink and releases writer holds on its hoppers.

Hoppers this Sink created (or attached to as a co-writer) decrement their writer count. A hopper shared by several producers Eofs when the last writer closes. Idempotent and allocation-free.

Wakes Push and Pop waiters.

◆ Front()

template<Detail::HopperValue T>
T StormByte::Buffer::Sink< T >::Front ( int key) const
noexcept

Copy of the next item in bucket key without dequeuing.

Parameters
keyBucket key identifier.
Returns
Front item, or default T if the key is missing or the hopper is empty.

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.

◆ Full()

template<Detail::HopperValue T>
bool StormByte::Buffer::Sink< T >::Full ( int key) const
noexcept

Checks if bucket key is full.

Parameters
keyBucket key identifier.
Returns
true if full, or false if key does not exist.

◆ Keys()

template<Detail::HopperValue T>
StormByte::Safe::Vector< int > StormByte::Buffer::Sink< T >::Keys ( ) const
noexcept

Keys of hoppers currently wired on this Sink.

Returns
Owned StormByte::Safe::Vector of keys in ascending order. Empty if none.

Snapshot. Does not create buckets. Sink does not interpret keys.

◆ Limits()

template<Detail::HopperValue T>
QueueStatus StormByte::Buffer::Sink< T >::Limits ( int key,
QueueLimits limits )
noexcept

Configure independent local limits on an existing shared hopper.

Parameters
keyBucket key.
limitsOptional local ceilings; zero is an active zero limit.
Returns
Ok or Missing.

◆ Notify() [1/2]

template<Detail::HopperValue T>
void StormByte::Buffer::Sink< T >::Notify ( Safe::ConditionVariable & consumer)
noexcept

Registers consumer condition variable to notify on all current and future hoppers.

Parameters
consumerConsumer condition variable reference. Not owned.
Note
Replacement waits for active notifications. The referent must remain alive until Unnotify completes; do not register it again while destroying it. Notification is not a stored event. Callers must coordinate predicate checks, waits and producer operations with the consumer's wait mutex to avoid lost wakeups.

◆ Notify() [2/2]

template<Detail::HopperValue T>
void StormByte::Buffer::Sink< T >::Notify ( Safe::ConditionVariable & consumer,
Safe::Atomic< std::size_t > & generation )
noexcept

Registers stored notifications on current and future hoppers and Sink closure.

Parameters
consumerBorrowed consumer condition variable.
generationBorrowed event counter, incremented with release ordering.
Note
Load generation with acquire ordering before checking Ready or EoF, then wait on the captured value if false and repeat. Explicit stop/failure events must increment and notify the same counter. Both referents must remain alive until Unnotify returns. Shared hoppers retain one observer; the latest registration wins, including its counter and owner identity.

◆ operator<<() [1/2]

template<Detail::HopperValue T>
Sink & StormByte::Buffer::Sink< T >::operator<< ( Lane lane)
noexcept

Same as lane >> *this.

Parameters
laneTo result from the producer.
Returns
*this.

◆ operator<<() [2/2]

template<Detail::HopperValue T>
Sink & StormByte::Buffer::Sink< T >::operator<< ( Sink< T > & src)
noexcept

Same as src >> *this (all hoppers).

Parameters
srcProducer Sink.
Returns
*this.

◆ operator=() [1/2]

template<Detail::HopperValue T>
Sink & StormByte::Buffer::Sink< T >::operator= ( const Sink< T > & )
delete

◆ operator=() [2/2]

template<Detail::HopperValue T>
Sink & StormByte::Buffer::Sink< T >::operator= ( Sink< T > && )
deletenoexcept

◆ operator>>()

template<Detail::HopperValue T>
Sink & StormByte::Buffer::Sink< T >::operator>> ( Sink< T > & dest)
noexcept

Share every existing hopper with dest.

Parameters
destConsumer Sink.
Returns
dest.

Zero buckets: no-op. Does not create keys.

◆ Pop() [1/4]

template<Detail::HopperValue T>
T StormByte::Buffer::Sink< T >::Pop ( )
noexcept

Pops one item from the Sink using default round-robin order.

Returns
Next item, or default T if empty/closed.

Blocks while zero buckets exist and Sink is not closed.

◆ Pop() [2/4]

template<Detail::HopperValue T>
T StormByte::Buffer::Sink< T >::Pop ( const Select & select)
noexcept

Pops one item from the Sink using a custom selection function.

Parameters
selectBucket index selection callback.
Returns
Next item, or default T if empty/closed.

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.

◆ Pop() [3/4]

template<Detail::HopperValue T>
T StormByte::Buffer::Sink< T >::Pop ( int key)
noexcept

Pops one item from bucket key only.

Parameters
keyBucket key identifier.
Returns
Next item of that hopper, or default T if the key is missing, the hopper is empty, or the Sink is closed.

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.

◆ Pop() [4/4]

template<Detail::HopperValue T>
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 StormByte::Buffer::Sink< T >::Pop ( Selector && select)
noexcept

Pops using a synchronously borrowed callable without copying its captures.

Template Parameters
SelectorCallable accepting Size and returning Size.
Parameters
selectCallable kept alive until this call returns; never retained.
Returns
Next item, or default T on an exception or when no item exists.
Note
Invocation is synchronous and may mutate the original callable. No owning Select is constructed from this borrow; move-only callables are supported without creating a clonable callback context. The callable and all referenced captures must remain alive and must not be concurrently mutated. Its provider must remain loaded during the call.

◆ Push()

template<Detail::HopperValue T>
void StormByte::Buffer::Sink< T >::Push ( int key,
T item )
noexcept

Pushes an item into the bucket specified by key.

Parameters
keyInteger bucket identifier.
itemItem 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.

◆ PushFor() [1/2]

template<Detail::HopperValue T>
QueueStatus StormByte::Buffer::Sink< T >::PushFor ( int key,
T & item,
const ByteBudget::Lease & lease,
std::chrono::milliseconds timeout,
AdmissionWaitObserver observer = {} )
noexcept

Shared-charge admission with a bounded wait.

Parameters
keyExisting bucket key.
itemMoved only on success.
leaseShared payload charge.
timeoutNonnegative wait bound; zero is immediate.
observerBorrowed observer of actual admission waits only.
Returns
Explicit admission result.

◆ PushFor() [2/2]

template<Detail::HopperValue T>
QueueStatus StormByte::Buffer::Sink< T >::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.

Parameters
keyExisting bucket key.
itemMoved only on success.
bytesCaller-defined weight.
timeoutNonnegative wait bound; zero is immediate.
observerBorrowed observer of actual admission waits only.
Returns
Explicit admission result.

◆ Ready() [1/2]

template<Detail::HopperValue T>
bool StormByte::Buffer::Sink< T >::Ready ( ) const
noexcept

Checks whether a Pop call can return immediately (item available or EoF).

Returns
true if any hopper has an item or if Sink is EoF.

◆ Ready() [2/2]

template<Detail::HopperValue T>
bool StormByte::Buffer::Sink< T >::Ready ( int key) const
noexcept

Whether Pop(int) on key can return an item or that hopper is finished.

Parameters
keyBucket key identifier.
Returns
true if the hopper has an item or is EoF. false if missing.

◆ Size()

template<Detail::HopperValue T>
StormByte::Size StormByte::Buffer::Sink< T >::Size ( int key) const
noexcept

Gets pending item count in bucket key.

Parameters
keyBucket key identifier.
Returns
Item count, or 0 if key bucket does not exist.

◆ Snapshot()

template<Detail::HopperValue T>
QueueSnapshot StormByte::Buffer::Sink< T >::Snapshot ( int key) const
noexcept

Read shared-hopper counters without waiting for capacity or doing I/O.

Parameters
keyBucket key.
Returns
Snapshot; Exists is false when missing.

◆ To()

template<Detail::HopperValue T>
Lane StormByte::Buffer::Sink< T >::To ( int key)
noexcept

Redirect of one hopper key.

Parameters
keyBucket key.
Returns
Lane for >> dest.

◆ TryPush() [1/2]

template<Detail::HopperValue T>
QueueStatus StormByte::Buffer::Sink< T >::TryPush ( int key,
T & item,
const ByteBudget::Lease & lease )
noexcept

Admit using a shared payload charge without charging twice.

Parameters
keyExisting bucket key.
itemMoved only on success.
leaseCharge belonging to the configured budget.
Returns
Explicit admission result.

◆ TryPush() [2/2]

template<Detail::HopperValue T>
QueueStatus StormByte::Buffer::Sink< T >::TryPush ( int key,
T & item,
StormByte::ByteSize bytes )
noexcept

Attempt a weighted admission to an existing bucket.

Parameters
keyBucket key; no implicit wiring wait.
itemMoved only on success.
bytesCaller-defined logical weight.
Returns
Explicit admission result; Missing for an unwired key.

◆ Unnotify()

template<Detail::HopperValue T>
void StormByte::Buffer::Sink< T >::Unnotify ( )
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.


The documentation for this class was generated from the following files: