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 (StormByte::Size 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
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
	Checks whether a bounded bucket cannot accept another Push without waiting.

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.

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 (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.
Query: Size, Capacity, Full, Empty, EoF, Ready, Writers, Front (peek, copy).
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 ( StormByte::Size 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>

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

void StormByte::Buffer::Hopper< T >::Capacity ( StormByte::Size 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.

◆ Front()

template<Type::MoveConstructible 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 (shared_ptr Packet/Frame). Not a deep copy of the payload.

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

◆ Ready()

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

StormByte::Size 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.

◆ Writers()

template<Type::MoveConstructible T>

unsigned StormByte::Buffer::Hopper< T >::Writers ( ) const

noexcept

Live writers attached to this hopper.

Returns: Writer count. Last CloseWriter sets Eof.

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

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Hopper() [1/4]

◆ Hopper() [2/4]

◆ Hopper() [3/4]

◆ Hopper() [4/4]

◆ ~Hopper()

Member Function Documentation

◆ Capacity() [1/2]

◆ Capacity() [2/2]

◆ Empty()

◆ EoF()

◆ Eof()

◆ Front()

◆ Full()

◆ Notify()

◆ operator<<()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator>>()

◆ Pop()

◆ Push()

◆ Ready()

◆ Size()

◆ Unnotify()

◆ Writers()

Friends And Related Symbol Documentation

◆ operator>> [1/2]

◆ operator>> [2/2]

◆ Sink< T >