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. | |
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:
hopper << item and item >> hopper enqueue; hopper >> item dequeues.| T | SafeValue with nonthrowing default construction, move construction, move assignment and destruction, and alignment no greater than __STDCPP_DEFAULT_NEW_ALIGNMENT__. |
| StormByte::Buffer::Hopper< T >::Hopper | ( | ) |
Constructs an empty unbounded Hopper.
| AllocationError | The coordinator, the gate or the signal cannot be allocated. |
|
explicit |
Constructs an empty Hopper with a capacity ceiling.
| capacity | Maximum number of items allowed (0 = unbounded). |
| AllocationError | The coordinator, the gate or the signal cannot be allocated. |
|
delete |
|
deletenoexcept |
|
noexcept |
Destructor.
Requires all users, including blocked producers, to be joined.
|
noexcept |
Close and discard entries, releasing charges outside the queue lock.
|
noexcept |
Cancel admissions already waiting; future calls remain permitted.
|
noexcept |
Gets the current capacity ceiling.
|
noexcept |
Sets a new capacity ceiling.
| capacity | Maximum items allowed (0 = unbounded). |
Lowering capacity does not drop queued items; subsequent Push calls wait until Size falls below the new ceiling.
|
noexcept |
Attach aggregate accounting and local bounds to an empty hopper.
| limits | Independent local ceilings. |
| budget | Shared queue/work accounting. |
|
noexcept |
Checks whether the queue has no pending items.
|
noexcept |
Checks whether Eof was called by a producer.
|
noexcept |
Marks end of production and wakes waiters.
Does not discard already queued items. After Eof, Push does not enqueue.
|
noexcept |
Copy of the next item without dequeuing.
Does not block and does not wake producers. Requires T copy-constructible without throwing. Not a deep copy of a shared payload.
|
noexcept |
Check whether an active local bound has been reached.
|
noexcept |
Set independent local limits without discarding existing entries.
| limits | Engaged zero is a zero ceiling, absent is unlimited. |
|
noexcept |
Registers the consumer condition variable to notify on Push or Eof.
| wake | Consumer 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.
|
noexcept |
Registers stored Push and Eof notifications alongside the condition variable.
| wake | Borrowed consumer condition variable. |
| generation | Borrowed event counter, incremented with release ordering. |
|
noexcept |
Write: item flows into this Hopper.
| item | Unit. Moved. Empty smart pointers are discarded. |
|
delete |
|
deletenoexcept |
|
noexcept |
Pop one unit from this Hopper into item.
| item | Destination. Becomes default T if the bucket is dry. |
|
noexcept |
Pops one item from the bucket, or returns default-constructed T if dry.
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.
|
noexcept |
Enqueues one item and signals the consumer if Notify was configured.
| item | Item 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.
|
noexcept |
Admit with a shared charge and bounded wait.
| item | Moved only on success. |
| lease | Existing charge retained by the caller. |
| timeout | Maximum nonnegative wait. |
| observer | Borrowed observer of actual admission waits only. |
|
noexcept |
Admit with a bounded wait; zero attempts immediately.
| item | Moved only on success. |
| bytes | Caller-defined logical weight. |
| timeout | Maximum nonnegative wait. |
| observer | Borrowed observer of actual admission waits only. |
|
noexcept |
Whether Pop can return an item or production is finished.
|
noexcept |
Gets the number of items currently waiting in the bucket.
|
noexcept |
Coherent counters under a short lock, without capacity waits or I/O.
|
noexcept |
Attempt admission sharing an existing charge.
| item | Moved only on success. |
| lease | Charge belonging to this hopper's budget. |
|
noexcept |
Attempt a weighted admission without waiting for capacity.
| item | Moved only on success. |
| bytes | Caller-defined logical weight. |
|
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.
|
noexcept |
Live writers attached to this hopper.
CloseWriter sets Eof. Write: rvalue item flows into hopper.
| item | Unit. Empty smart pointers are discarded. |
| hopper | Destination hopper. |
hopper. Write: lvalue item flows into hopper.
| item | Unit. Moved. Empty smart pointers are discarded. |
| hopper | Destination hopper. |
hopper.Namespace declaration required by GCC next to the friend (GCC will not define a friend-only operator out of line).
|
friend |
Grants Sink access to writer and observer bookkeeping.