StormByte::Buffer::Hopper< T > Class Template Reference

Single-producer single-consumer (SPSC) typed item queue. More...

#include <StormByte/buffer/hopper.hxx>

Public Member Functions
Lifecycle
	Hopper () noexcept
	Constructs an empty unbounded Hopper.
	Hopper (std::size_t capacity) noexcept
	Constructs an empty Hopper with a capacity ceiling.
	Hopper (const Hopper &)=delete
	Copy constructor is deleted (Hopper is non-copyable).
	Hopper (Hopper &&) noexcept=delete
	Move constructor is deleted (Hopper is non-movable).
	~Hopper () noexcept
	Destructor.
Hopper &	operator= (const Hopper &)=delete
	Copy assignment operator is deleted (Hopper is non-copyable).
Hopper &	operator= (Hopper &&) noexcept=delete
	Move assignment operator is deleted (Hopper is non-movable).
Capacity
std::size_t	Capacity () const noexcept
	Gets the current capacity ceiling.
void	Capacity (std::size_t capacity) noexcept
	Sets a new capacity ceiling.
std::size_t	Size () const noexcept
	Gets the number of items currently waiting in the bucket.
bool	Full () const noexcept
	Checks whether a bounded bucket cannot accept another Push without waiting.
Producer
void	Push (T item) noexcept
	Enqueues one item and signals the consumer if Notify was configured.
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.
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.
Notification
void	Notify (std::condition_variable &wake) noexcept
	Registers the consumer condition variable to notify on Push or Eof.
void	Unnotify () noexcept
	Drops the pointer set by Notify.

Friends
class	Sink< T >
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<Type::MoveConstructible T>
class StormByte::Buffer::Hopper< T >

Single-producer single-consumer (SPSC) typed item queue.

Hopper is a typed bucket queue for passing items between a single producer and a single consumer. 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.
• Non-copyable, non-movable: Shared via std::shared_ptr.

Template Parameters

T	Item type stored in the queue (must be MoveConstructible).

Constructor & Destructor Documentation

Hopper() [1/4]

template<Type::MoveConstructible T>

StormByte::Buffer::Hopper< T >::Hopper ( )

noexcept

Constructs an empty unbounded Hopper.

Hopper() [2/4]

template<Type::MoveConstructible T>

StormByte::Buffer::Hopper< T >::Hopper ( std::size_t  capacity )

explicitnoexcept

Constructs an empty Hopper with a capacity ceiling.

Parameters

capacity

Maximum number of items allowed (0 = unbounded).

Hopper() [3/4]

template<Type::MoveConstructible T>

StormByte::Buffer::Hopper< T >::Hopper ( const Hopper< T > &  )

delete

Copy constructor is deleted (Hopper is non-copyable).

Hopper() [4/4]

template<Type::MoveConstructible T>

StormByte::Buffer::Hopper< T >::Hopper ( Hopper< T > &&  )

deletenoexcept

Move constructor is deleted (Hopper is non-movable).

~Hopper()

template<Type::MoveConstructible T>

StormByte::Buffer::Hopper< T >::~Hopper ( )

noexcept

Destructor.

Wakes any Push blocked on a full bucket.

Member Function Documentation

Capacity() [1/2]

template<Type::MoveConstructible T>

std::size_t StormByte::Buffer::Hopper< T >::Capacity ( ) const

noexcept

Gets the current capacity ceiling.

Returns

Maximum items, or 0 if unbounded.

Capacity() [2/2]

template<Type::MoveConstructible T>

void StormByte::Buffer::Hopper< T >::Capacity ( std::size_t  capacity )

noexcept

Sets a new capacity ceiling.

Parameters

capacity

Maximum items allowed (0 = unbounded).

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

Empty()

template<Type::MoveConstructible T>

bool StormByte::Buffer::Hopper< T >::Empty ( ) const

noexcept

Checks whether the queue has no pending items.

Returns

true if empty.

EoF()

template<Type::MoveConstructible 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<Type::MoveConstructible 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.

Full()

template<Type::MoveConstructible T>

bool StormByte::Buffer::Hopper< T >::Full ( ) const

noexcept

Checks whether a bounded bucket cannot accept another Push without waiting.

Returns

true if Capacity > 0 and Size >= Capacity.

Notify()

template<Type::MoveConstructible T>

void StormByte::Buffer::Hopper< T >::Notify ( std::condition_variable &  wake )

noexcept

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

Parameters

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.

operator<<()

template<Type::MoveConstructible T>

Hopper & StormByte::Buffer::Hopper< T >::operator<< ( T  item )

noexcept

Write: item flows into this Hopper.

Parameters

item	Unit. Moved. Empty smart pointers are discarded.

Returns

*this.

operator=() [1/2]

template<Type::MoveConstructible T>

Hopper & StormByte::Buffer::Hopper< T >::operator= ( const Hopper< T > &  )

delete

Copy assignment operator is deleted (Hopper is non-copyable).

operator=() [2/2]

template<Type::MoveConstructible T>

Hopper & StormByte::Buffer::Hopper< T >::operator= ( Hopper< T > &&  )

deletenoexcept

Move assignment operator is deleted (Hopper is non-movable).

operator>>()

template<Type::MoveConstructible T>

Hopper & StormByte::Buffer::Hopper< T >::operator>> ( T &  item )

noexcept

Pop one unit from this Hopper into item.

Parameters

item	Destination. Becomes default T if the bucket is dry.

Returns

*this.

Pop()

template<Type::MoveConstructible 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<Type::MoveConstructible T>

void StormByte::Buffer::Hopper< T >::Push ( T  item )

noexcept

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

Parameters

item	Item to push. Empty smart pointers are discarded.

If Capacity > 0 and the bucket is full, waits until space becomes available, Eof is called, or the Hopper is destroyed. After Eof, Push does not enqueue.

Size()

template<Type::MoveConstructible T>

std::size_t StormByte::Buffer::Hopper< T >::Size ( ) const

noexcept

Gets the number of items currently waiting in the bucket.

Returns

Item count.

Unnotify()

template<Type::MoveConstructible T>

void StormByte::Buffer::Hopper< T >::Unnotify ( )

noexcept

Drops the pointer set by Notify.

Safe to call more than once or when nothing was registered. After this, Push and Eof do not signal a consumer CV; producers blocked on a full bucket still wake on m_space.

Friends And Related Symbol Documentation

operator>> [1/2]

template<Type::MoveConstructible T>

Hopper & operator>> ( T &&  item, Hopper< T > &  hopper  )

friend

Write: rvalue item flows into hopper.

Parameters

item	Unit. Empty smart pointers are discarded.
hopper	Destination hopper.

Returns

hopper.

operator>> [2/2]

template<Type::MoveConstructible T>

Hopper & operator>> ( T &  item, Hopper< T > &  hopper  )

friend

Write: lvalue item flows into hopper.

Parameters

item	Unit. Moved. Empty smart pointers are discarded.
hopper	Destination 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<Type::MoveConstructible T>

friend class Sink< T >

friend

---

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

• lib/public/StormByte/buffer/hopper.hxx