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

Synchronized typed item queue with shared-writer support. More...

#include <StormByte/buffer/hopper.hxx>

Public Member Functions

Lifecycle
 Hopper () noexcept(false)
 Constructs an empty unbounded Hopper.
 Hopper (StormByte::Size capacity)
 Constructs an empty Hopper with a capacity ceiling.
 Hopper (const Hopper &)=delete
 Hopper (Hopper &&) noexcept=delete
 ~Hopper () noexcept
 Destructor.
Hopper & operator= (const Hopper &)=delete
Hopper & operator= (Hopper &&) noexcept=delete
Capacity
StormByte::Size Capacity () const noexcept
 Gets the current capacity ceiling.
void Capacity (StormByte::Size capacity) noexcept
 Sets a new capacity ceiling.
StormByte::Size Size () const noexcept
 Gets the number of items currently waiting in the bucket.
bool Full () const noexcept
 Check whether an active local bound has been reached.
unsigned Writers () const noexcept
 Live writers attached to this hopper.
Producer
void Push (T item) noexcept
 Enqueues one item and signals the consumer if Notify was configured.
QueueStatus TryPush (T &item, StormByte::ByteSize bytes) noexcept
 Attempt a weighted admission without waiting for capacity.
QueueStatus TryPush (T &item, const ByteBudget::Lease &lease) noexcept
 Attempt admission sharing an existing charge.
QueueStatus PushFor (T &item, StormByte::ByteSize bytes, std::chrono::milliseconds timeout, AdmissionWaitObserver observer={}) noexcept
 Admit with a bounded wait; zero attempts immediately.
QueueStatus PushFor (T &item, const ByteBudget::Lease &lease, std::chrono::milliseconds timeout, AdmissionWaitObserver observer={}) noexcept
 Admit with a shared charge and bounded wait.
void Limits (QueueLimits limits) noexcept
 Set independent local limits without discarding existing entries.
QueueStatus Configure (QueueLimits limits, const ByteBudget &budget) noexcept
 Attach aggregate accounting and local bounds to an empty hopper.
QueueSnapshot Snapshot () const noexcept
 Coherent counters under a short lock, without capacity waits or I/O.
void CancelPending () noexcept
 Cancel admissions already waiting; future calls remain permitted.
void Abort () noexcept
 Close and discard entries, releasing charges outside the queue lock.
Hopper & operator<< (T item) noexcept
 Write: item flows into this Hopper.
void Eof () noexcept
 Marks end of production and wakes waiters.
Consumer
T Pop () noexcept
 Pops one item from the bucket, or returns default-constructed T if dry.
T Front () const noexcept
 Copy of the next item without dequeuing.
Hopper & operator>> (T &item) noexcept
 Pop one unit from this Hopper into item.
bool EoF () const noexcept
 Checks whether Eof was called by a producer.
bool Empty () const noexcept
 Checks whether the queue has no pending items.
bool Ready () const noexcept
 Whether Pop can return an item or production is finished.
Notification
void Notify (Safe::ConditionVariable &wake) noexcept
 Registers the consumer condition variable to notify on Push or Eof.
void Notify (Safe::ConditionVariable &wake, Safe::Atomic< std::size_t > &generation) noexcept
 Registers stored Push and Eof notifications alongside the condition variable.
void Unnotify () noexcept
 Drops both borrowed pointers set by Notify.

Friends

class Sink< T >
 Grants Sink access to writer and observer bookkeeping.
Hopper & operator>> (T &item, Hopper &hopper) noexcept
 Write: lvalue item flows into hopper.
Hopper & operator>> (T &&item, Hopper &hopper) noexcept
 Write: rvalue item flows into hopper.

Detailed Description

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

Synchronized typed item queue with shared-writer support.

Hopper is a typed bucket queue for passing items between producers and consumers. Unlike byte-oriented FIFOs, Hopper operates on discrete typed elements.

Key characteristics:

  • Capacity ceiling: Optional capacity ceiling (0 = unbounded). Push waits when full.
  • EoF handling: Marking Eof signals end of production; queued items can still be drained via Pop.
  • Consumer notification: Points to a consumer condition variable via Notify to signal when items or EoF are available.
  • Item flow: hopper << item and item >> hopper enqueue; hopper >> item dequeues.
  • Query: Size, Capacity, Full, Empty, EoF, Ready, Writers, Front (peek, copy).
  • Non-copyable, non-movable: Shared via StormByte::Safe::Shared.
Template Parameters
TSafeValue with nonthrowing default construction, move construction, move assignment and destruction, and alignment no greater than __STDCPP_DEFAULT_NEW_ALIGNMENT__.
Note
Conditional DLL safety requires compatible C++/STL ABI, Base and all template/provider modules remaining loaded, and the element provider's SafeValue guarantees. Derived classes must preserve these guarantees; this is not a certification of arbitrary derived payloads or owners. Private state is released through its creator callback; shared handle control-block providers must remain loaded. Ordinary inline is not a provider-locality guarantee.
Stop and join all users before destruction. Destruction is not cancellation of concurrent member calls. Unnotify must complete before a borrowed condition variable dies. Allocation failure in the nonthrowing queue operations terminates the process.

Constructor & Destructor Documentation

◆ Hopper() [1/4]

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

Constructs an empty unbounded Hopper.

Exceptions
AllocationErrorThe coordinator, the gate or the signal cannot be allocated.

◆ Hopper() [2/4]

template<Detail::HopperValue T>
StormByte::Buffer::Hopper< T >::Hopper ( StormByte::Size capacity)
explicit

Constructs an empty Hopper with a capacity ceiling.

Parameters
capacityMaximum number of items allowed (0 = unbounded).
Exceptions
AllocationErrorThe coordinator, the gate or the signal cannot be allocated.

◆ Hopper() [3/4]

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

◆ Hopper() [4/4]

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

◆ ~Hopper()

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

Destructor.

Requires all users, including blocked producers, to be joined.

Member Function Documentation

◆ Abort()

template<Detail::HopperValue T>
void StormByte::Buffer::Hopper< T >::Abort ( )
noexcept

Close and discard entries, releasing charges outside the queue lock.

◆ CancelPending()

template<Detail::HopperValue T>
void StormByte::Buffer::Hopper< T >::CancelPending ( )
noexcept

Cancel admissions already waiting; future calls remain permitted.

◆ Capacity() [1/2]

template<Detail::HopperValue T>
StormByte::Size StormByte::Buffer::Hopper< T >::Capacity ( ) const
noexcept

Gets the current capacity ceiling.

Returns
Maximum items, or 0 if unbounded.

◆ Capacity() [2/2]

template<Detail::HopperValue T>
void StormByte::Buffer::Hopper< T >::Capacity ( StormByte::Size capacity)
noexcept

Sets a new capacity ceiling.

Parameters
capacityMaximum items allowed (0 = unbounded).

Lowering capacity does not drop queued items; subsequent Push calls wait until Size falls below the new ceiling.

◆ Configure()

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

Attach aggregate accounting and local bounds to an empty hopper.

Parameters
limitsIndependent local ceilings.
budgetShared queue/work accounting.
Returns
Invalid if entries or admissions are active; no partial change.

◆ Empty()

template<Detail::HopperValue T>
bool StormByte::Buffer::Hopper< T >::Empty ( ) const
noexcept

Checks whether the queue has no pending items.

Returns
true if empty.

◆ EoF()

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

Checks whether Eof was called by a producer.

Returns
true if Eof was called. Note that queued items may still remain.

◆ Eof()

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

Marks end of production and wakes waiters.

Does not discard already queued items. After Eof, Push does not enqueue.

◆ Front()

template<Detail::HopperValue T>
T StormByte::Buffer::Hopper< T >::Front ( ) const
noexcept

Copy of the next item without dequeuing.

Returns
Front item, or default T if empty.

Does not block and does not wake producers. Requires T copy-constructible without throwing. Not a deep copy of a shared payload.

◆ Full()

template<Detail::HopperValue T>
bool StormByte::Buffer::Hopper< T >::Full ( ) const
noexcept

Check whether an active local bound has been reached.

Returns
True when the item or byte ceiling is reached; ignores shared budget pressure.

◆ Limits()

template<Detail::HopperValue T>
void StormByte::Buffer::Hopper< T >::Limits ( QueueLimits limits)
noexcept

Set independent local limits without discarding existing entries.

Parameters
limitsEngaged zero is a zero ceiling, absent is unlimited.

◆ Notify() [1/2]

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

Registers the consumer condition variable to notify on Push or Eof.

Parameters
wakeConsumer condition variable reference. Not owned.

The referent must outlive this Hopper, or the owner must call Unnotify before destroying wake. Sink wiring shares the Hopper: a producer Eof after the consumer died is the usual case. Replacement waits for an active notification; registration must not race with destruction of either condition variable. 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::Hopper< T >::Notify ( Safe::ConditionVariable & wake,
Safe::Atomic< std::size_t > & generation )
noexcept

Registers stored Push and Eof notifications alongside the condition variable.

Parameters
wakeBorrowed consumer condition variable.
generationBorrowed event counter, incremented with release ordering.
Note
Load generation with acquire ordering before checking readiness, then wait on that captured value if not ready and repeat. Control events must increment and notify the same counter. Both referents must remain alive until Unnotify returns; replacement synchronizes with active notifications.

◆ operator<<()

template<Detail::HopperValue T>
Hopper & StormByte::Buffer::Hopper< T >::operator<< ( T item)
noexcept

Write: item flows into this Hopper.

Parameters
itemUnit. Moved. Empty smart pointers are discarded.
Returns
*this.

◆ operator=() [1/2]

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

◆ operator=() [2/2]

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

◆ operator>>()

template<Detail::HopperValue T>
Hopper & StormByte::Buffer::Hopper< T >::operator>> ( T & item)
noexcept

Pop one unit from this Hopper into item.

Parameters
itemDestination. Becomes default T if the bucket is dry.
Returns
*this.

◆ Pop()

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

Pops one item from the bucket, or returns default-constructed T if dry.

Returns
Next item, or default T if empty.

Does not block. If empty and EoF is false, the consumer waits on its condition variable. Wakes one producer blocked in Push if space becomes available.

◆ Push()

template<Detail::HopperValue T>
void StormByte::Buffer::Hopper< T >::Push ( T item)
noexcept

Enqueues one item and signals the consumer if Notify was configured.

Parameters
itemItem to push. Empty smart pointers are discarded.

If Capacity > 0 and the bucket is full, waits until space becomes available, or Eof is called. After Eof, Push does not enqueue. Call Eof and join blocked producers before destroying the Hopper.

◆ PushFor() [1/2]

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

Admit with a shared charge and bounded wait.

Parameters
itemMoved only on success.
leaseExisting charge retained by the caller.
timeoutMaximum nonnegative wait.
observerBorrowed observer of actual admission waits only.
Returns
Explicit admission result.

◆ PushFor() [2/2]

template<Detail::HopperValue T>
QueueStatus StormByte::Buffer::Hopper< T >::PushFor ( T & item,
StormByte::ByteSize bytes,
std::chrono::milliseconds timeout,
AdmissionWaitObserver observer = {} )
noexcept

Admit with a bounded wait; zero attempts immediately.

Parameters
itemMoved only on success.
bytesCaller-defined logical weight.
timeoutMaximum nonnegative wait.
observerBorrowed observer of actual admission waits only.
Returns
Explicit admission result.

◆ Ready()

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

Whether Pop can return an item or production is finished.

Returns
true if !Empty() or EoF().

◆ Size()

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

Gets the number of items currently waiting in the bucket.

Returns
Item count.

◆ Snapshot()

template<Detail::HopperValue T>
QueueSnapshot StormByte::Buffer::Hopper< T >::Snapshot ( ) const
noexcept

Coherent counters under a short lock, without capacity waits or I/O.

Returns
Current logical weights, bounds, peaks and waits.

◆ TryPush() [1/2]

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

Attempt admission sharing an existing charge.

Parameters
itemMoved only on success.
leaseCharge belonging to this hopper's budget.
Returns
Explicit admission result.

◆ TryPush() [2/2]

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

Attempt a weighted admission without waiting for capacity.

Parameters
itemMoved only on success.
bytesCaller-defined logical weight.
Returns
Explicit admission result.

◆ Unnotify()

template<Detail::HopperValue T>
void StormByte::Buffer::Hopper< T >::Unnotify ( )
noexcept

Drops both borrowed pointers set by Notify.

Safe to call more than once or when nothing was registered. After this, Push and Eof do not signal a consumer condition variable; producers blocked on a full bucket still wake on the space signal. Waits for in-flight notifications. Do not concurrently register the condition variable or counter again while destroying either referent.

◆ Writers()

template<Detail::HopperValue T>
unsigned StormByte::Buffer::Hopper< T >::Writers ( ) const
noexcept

Live writers attached to this hopper.

Returns
Writer count. Last CloseWriter sets Eof.

◆ operator>> [1/2]

template<Detail::HopperValue T>
Hopper & operator>> ( T && item,
Hopper< T > & hopper )
friend

Write: rvalue item flows into hopper.

Parameters
itemUnit. Empty smart pointers are discarded.
hopperDestination hopper.
Returns
hopper.

◆ operator>> [2/2]

template<Detail::HopperValue T>
Hopper & operator>> ( T & item,
Hopper< T > & hopper )
friend

Write: lvalue item flows into hopper.

Parameters
itemUnit. Moved. Empty smart pointers are discarded.
hopperDestination hopper.
Returns
hopper.

Namespace declaration required by GCC next to the friend (GCC will not define a friend-only operator out of line).

◆ Sink< T >

template<Detail::HopperValue T>
friend class Sink< T >
friend

Grants Sink access to writer and observer bookkeeping.


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