#include <Mailbox.h>

Inheritance diagram for Mailbox< T, preallocatedSize, Notifications >:

Collaboration diagram for Mailbox< T, preallocatedSize, Notifications >:

Classes
class	ActiveOperation

Public Types
enum	Error { NoError , Empty , WouldBlock , TimedOut , Interrupted , ThreadTerminating , Closed }

Public Member Functions
	Mailbox (size_t ringSize)

	~Mailbox ()
	Destructor - closes the ring and drains every admitted operation.

void	close ()

MUST_USE_RESULT bool	takeAfterClose (T &out)

Error	write (const T &obj, Time::Timestamp &timeout)
	Writes one object, waiting for space up to the supplied timeout.

Error	write (const T &obj)

bool	closeWritesWithFinal (const T &obj)

Error	tryWrite (const T &obj)

size_t	write (const T *obj, size_t n, Time::Timestamp &timeout)
	Publishes each available chunk before waiting for more space.

size_t	write (const T *obj, size_t n)

MUST_USE_RESULT bool	read (T &out, Time::Timestamp &timeout, Error &error)

MUST_USE_RESULT bool	read (T &out, Error &error)

size_t	read (T *out, size_t n, Time::Timestamp &timeout)
	Removes each available chunk before waiting for more data.

size_t	read (T *out, size_t n)

bool	dataReady ()
	dataReady - is data ready for reading from the ring buffer?

bool	canWrite ()
	canWrite - is it possible to write to the ring buffer without blocking?

MUST_USE_RESULT bool	waitFor (MailboxWait::WaitType wait, Time::Timestamp &timeout, Error &error)
	waitFor - block until the given condition is true (readable/writeable)

bool	waitFor (MailboxWait::WaitType wait, Time::Timestamp &timeout)

bool	waitFor (MailboxWait::WaitType wait)

Protected Member Functions
bool	readsClosed () const

Protected Attributes
RingQueue< T, preallocatedSize >	m_Ring

Notifications	m_Notifications

bool	m_Closing = false

bool	m_WriteClosed = false

bool	m_FinalPending = false

Private Member Functions
Error	waitForLocked (MailboxWait::WaitType direction, Time::Timestamp &timeout)

size_t	pushLocked (const T *items, size_t count)

size_t	popLocked (T *items, size_t count)

bool	waitForChange (ConditionVariable &condition, size_t &waiters, Time::Timestamp &timeout, ConditionVariable::Error &error)

bool	beginOperation ()

void	endOperation ()

Error	errorFromConditionVariable (ConditionVariable::Error err)

Private Attributes
Mutex	m_Lock

ConditionVariable	m_WriteCondition

ConditionVariable	m_ReadCondition

ConditionVariable	m_DrainCondition

size_t	m_ActiveOperations = 0

size_t	m_ReadWaiters = 0

size_t	m_WriteWaiters = 0

Detailed Description

template<class T, size_t preallocatedSize = 0, class Notifications = MailboxNotifications>
class Mailbox< T, preallocatedSize, Notifications >

Blocking bounded queue. Publication, waiter enrolment and close admission share one mutex. Notifications run under that mutex; the default policy compiles away and carries no readiness or subscriber state.

Definition at line 57 of file Mailbox.h.

Member Enumeration Documentation

◆ Error

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

enum Mailbox::Error

Definition at line 85 of file Mailbox.h.

Constructor & Destructor Documentation

◆ Mailbox()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

Mailbox< T, preallocatedSize, Notifications >::Mailbox ( size_t ringSize )

inlineexplicit

Definition at line 103 of file Mailbox.h.

◆ ~Mailbox()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

Mailbox< T, preallocatedSize, Notifications >::~Mailbox ( )

inline

Destructor - closes the ring and drains every admitted operation.

Definition at line 106 of file Mailbox.h.

Member Function Documentation

◆ beginOperation()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::beginOperation ( )

inlineprivate

Definition at line 431 of file Mailbox.h.

◆ canWrite()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::canWrite ( )

inline

canWrite - is it possible to write to the ring buffer without blocking?

Definition at line 340 of file Mailbox.h.

Referenced by UnixSocket::select().

Here is the caller graph for this function:

◆ close()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

void Mailbox< T, preallocatedSize, Notifications >::close ( )

inline

Stop admitting operations, wake every blocked operation and monitor, and wait for already-admitted operations to retire.

Definition at line 114 of file Mailbox.h.

Referenced by sys_mbox_free().

Here is the caller graph for this function:

◆ closeWritesWithFinal()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::closeWritesWithFinal ( const T & obj )

inline

Closes write admission after appending one final object. Readers can drain the objects already present, including the final object.

Definition at line 176 of file Mailbox.h.

◆ dataReady()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::dataReady ( )

inline

dataReady - is data ready for reading from the ring buffer?

Definition at line 330 of file Mailbox.h.

Referenced by UnixSocket::select().

Here is the caller graph for this function:

◆ endOperation()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

void Mailbox< T, preallocatedSize, Notifications >::endOperation ( )

inlineprivate

Definition at line 442 of file Mailbox.h.

◆ errorFromConditionVariable()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

Error Mailbox< T, preallocatedSize, Notifications >::errorFromConditionVariable ( ConditionVariable::Error err )

inlineprivate

Definition at line 451 of file Mailbox.h.

◆ popLocked()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

size_t Mailbox< T, preallocatedSize, Notifications >::popLocked	(	T *	items,
		size_t	count
	)

inlineprivate

Definition at line 407 of file Mailbox.h.

◆ pushLocked()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

size_t Mailbox< T, preallocatedSize, Notifications >::pushLocked	(	const T *	items,
		size_t	count
	)

inlineprivate

Definition at line 391 of file Mailbox.h.

◆ read() [1/4]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

MUST_USE_RESULT bool Mailbox< T, preallocatedSize, Notifications >::read	(	T &	out,
		Error &	error
	)

inline

Definition at line 297 of file Mailbox.h.

◆ read() [2/4]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

MUST_USE_RESULT bool Mailbox< T, preallocatedSize, Notifications >::read	(	T &	out,
		Time::Timestamp &	timeout,
		Error &	error
	)

inline

Read one object from the ring buffer.

On success, out contains the removed object and error is NoError. On failure, out is reset to T() and error describes the failure. The internal mutex is reacquired after a wait and released before this function returns; no lock or reference into the ring escapes to the caller. The Mailbox must outlive any blocked read.

Definition at line 276 of file Mailbox.h.

Referenced by UnixSocket::receiveDatagram().

Here is the caller graph for this function:

◆ read() [3/4]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

size_t Mailbox< T, preallocatedSize, Notifications >::read	(	T *	out,
		size_t	n
	)

inline

Definition at line 324 of file Mailbox.h.

◆ read() [4/4]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

size_t Mailbox< T, preallocatedSize, Notifications >::read	(	T *	out,
		size_t	n,
		Time::Timestamp &	timeout
	)

inline

Removes each available chunk before waiting for more data.

Definition at line 303 of file Mailbox.h.

◆ readsClosed()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::readsClosed ( ) const

inlineprotected

Definition at line 475 of file Mailbox.h.

◆ takeAfterClose()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

MUST_USE_RESULT bool Mailbox< T, preallocatedSize, Notifications >::takeAfterClose ( T & out )

inline

Remove one object after close() has drained all admitted operations.

Pointer queues use this to retire payload ownership which the generic container cannot infer. No producer or consumer can race this path once close() has returned.

Definition at line 142 of file Mailbox.h.

◆ tryWrite()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

Error Mailbox< T, preallocatedSize, Notifications >::tryWrite ( const T & obj )

inline

Atomically writes one object without waiting for lock ownership or space. A WouldBlock result leaves the ring unchanged.

Definition at line 213 of file Mailbox.h.

References ProcessorBase::inDeviceHardIrq().

Referenced by UnixSocket::sendDatagram().

Here is the caller graph for this function:

◆ waitFor() [1/3]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::waitFor ( MailboxWait::WaitType wait )

inline

Definition at line 367 of file Mailbox.h.

◆ waitFor() [2/3]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::waitFor	(	MailboxWait::WaitType	wait,
		Time::Timestamp &	timeout
	)

inline

Definition at line 362 of file Mailbox.h.

◆ waitFor() [3/3]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

MUST_USE_RESULT bool Mailbox< T, preallocatedSize, Notifications >::waitFor	(	MailboxWait::WaitType	wait,
		Time::Timestamp &	timeout,
		Error &	error
	)

inline

waitFor - block until the given condition is true (readable/writeable)

Definition at line 350 of file Mailbox.h.

Referenced by UnixSocket::select().

Here is the caller graph for this function:

◆ waitForChange()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::waitForChange	(	ConditionVariable &	condition,
		size_t &	waiters,
		Time::Timestamp &	timeout,
		ConditionVariable::Error &	error
	)

inlineprivate

Definition at line 423 of file Mailbox.h.

◆ waitForLocked()

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

Error Mailbox< T, preallocatedSize, Notifications >::waitForLocked	(	MailboxWait::WaitType	direction,
		Time::Timestamp &	timeout
	)

inlineprivate

Definition at line 373 of file Mailbox.h.

◆ write() [1/4]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

Error Mailbox< T, preallocatedSize, Notifications >::write ( const T & obj )

inline

Definition at line 167 of file Mailbox.h.

◆ write() [2/4]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

Error Mailbox< T, preallocatedSize, Notifications >::write	(	const T &	obj,
		Time::Timestamp &	timeout
	)

inline

Writes one object, waiting for space up to the supplied timeout.

Definition at line 154 of file Mailbox.h.

Referenced by UnixSocket::sendDatagram().

Here is the caller graph for this function:

◆ write() [3/4]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

size_t Mailbox< T, preallocatedSize, Notifications >::write	(	const T *	obj,
		size_t	n
	)

inline

Definition at line 262 of file Mailbox.h.

◆ write() [4/4]

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

size_t Mailbox< T, preallocatedSize, Notifications >::write	(	const T *	obj,
		size_t	n,
		Time::Timestamp &	timeout
	)

inline

Publishes each available chunk before waiting for more space.

Definition at line 242 of file Mailbox.h.

Member Data Documentation

◆ m_ActiveOperations

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

size_t Mailbox< T, preallocatedSize, Notifications >::m_ActiveOperations = 0

private

Definition at line 491 of file Mailbox.h.

◆ m_Closing

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::m_Closing = false

protected

Definition at line 481 of file Mailbox.h.

◆ m_DrainCondition

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

ConditionVariable Mailbox< T, preallocatedSize, Notifications >::m_DrainCondition

private

Definition at line 490 of file Mailbox.h.

◆ m_FinalPending

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::m_FinalPending = false

protected

Definition at line 484 of file Mailbox.h.

◆ m_Lock

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

Mutex Mailbox< T, preallocatedSize, Notifications >::m_Lock

private

Definition at line 487 of file Mailbox.h.

◆ m_Notifications

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

Notifications Mailbox< T, preallocatedSize, Notifications >::m_Notifications

protected

Definition at line 480 of file Mailbox.h.

◆ m_ReadCondition

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

ConditionVariable Mailbox< T, preallocatedSize, Notifications >::m_ReadCondition

private

Definition at line 489 of file Mailbox.h.

◆ m_ReadWaiters

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

size_t Mailbox< T, preallocatedSize, Notifications >::m_ReadWaiters = 0

private

Definition at line 493 of file Mailbox.h.

◆ m_Ring

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

RingQueue<T, preallocatedSize> Mailbox< T, preallocatedSize, Notifications >::m_Ring

protected

Definition at line 479 of file Mailbox.h.

◆ m_WriteClosed

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

bool Mailbox< T, preallocatedSize, Notifications >::m_WriteClosed = false

protected

Definition at line 482 of file Mailbox.h.

◆ m_WriteCondition

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

ConditionVariable Mailbox< T, preallocatedSize, Notifications >::m_WriteCondition

private

Definition at line 488 of file Mailbox.h.

◆ m_WriteWaiters

template<class T , size_t preallocatedSize = 0, class Notifications = MailboxNotifications>

size_t Mailbox< T, preallocatedSize, Notifications >::m_WriteWaiters = 0

private

Definition at line 494 of file Mailbox.h.

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

Mailbox.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ Error

Constructor & Destructor Documentation

◆ Mailbox()

◆ ~Mailbox()

Member Function Documentation

◆ beginOperation()

◆ canWrite()

◆ close()

◆ closeWritesWithFinal()

◆ dataReady()

◆ endOperation()

◆ errorFromConditionVariable()

◆ popLocked()

◆ pushLocked()

◆ read() [1/4]

◆ read() [2/4]

◆ read() [3/4]

◆ read() [4/4]

◆ readsClosed()

◆ takeAfterClose()

◆ tryWrite()

◆ waitFor() [1/3]

◆ waitFor() [2/3]

◆ waitFor() [3/3]

◆ waitForChange()

◆ waitForLocked()

◆ write() [1/4]

◆ write() [2/4]

◆ write() [3/4]

◆ write() [4/4]

Member Data Documentation

◆ m_ActiveOperations

◆ m_Closing

◆ m_DrainCondition

◆ m_FinalPending

◆ m_Lock

◆ m_Notifications

◆ m_ReadCondition

◆ m_ReadWaiters

◆ m_Ring

◆ m_WriteClosed

◆ m_WriteCondition

◆ m_WriteWaiters