The Mailbox class. This class implements an IPC mechnism based on sending/receiving envelopes containing data of a fixed size, configured at initialization) that reside within a buffer of memory provided by the user. More...

#include <mailbox.h>

Public Member Functions
void *	operator new (size_t sz, void *pv)

	~Mailbox ()

void	Init (void *pvBuffer_, uint16_t u16BufferSize_, uint16_t u16ElementSize_)
	Init Initialize the mailbox object prior to its use. This must be called before any calls can be made to the object. More...

bool	Send (void *pvData_)
	Send Send an envelope to the mailbox. This safely copies the data contents of the datastructure to the previously-initialized mailbox buffer. If there is a thread already blocking, awaiting delivery to the mailbox, it will be unblocked at this time. More...

bool	SendTail (void *pvData_)
	SendTail Send an envelope to the mailbox. This safely copies the data contents of the datastructure to the previously-initialized mailbox buffer. If there is a thread already blocking, awaiting delivery to the mailbox, it will be unblocked at this time. More...

bool	Send (void *pvData_, uint32_t u32TimeoutMS_)
	Send Send an envelope to the mailbox. This safely copies the data contents of the datastructure to the previously-initialized mailbox buffer. If there is a thread already blocking, awaiting delivery to the mailbox, it will be unblocked at this time. More...

bool	SendTail (void *pvData_, uint32_t u32TimeoutMS_)
	SendTail Send an envelope to the mailbox. This safely copies the data contents of the datastructure to the previously-initialized mailbox buffer. If there is a thread already blocking, awaiting delivery to the mailbox, it will be unblocked at this time. More...

void	Receive (void *pvData_)
	Receive Read one envelope from the head of the mailbox. If the mailbox is currently empty, the calling thread will block until an envelope is delivered. More...

void	ReceiveTail (void *pvData_)
	ReceiveTail Read one envelope from the tail of the mailbox. If the mailbox is currently empty, the calling thread will block until an envelope is delivered. More...

bool	Receive (void *pvData_, uint32_t u32TimeoutMS_)
	Receive Read one envelope from the head of the mailbox. If the mailbox is currently empty, the calling thread will block until an envelope is delivered, or the specified time has elapsed without delivery. More...

bool	ReceiveTail (void *pvData_, uint32_t u32TimeoutMS_)
	ReceiveTail Read one envelope from the tail of the mailbox. If the mailbox is currently empty, the calling thread will block until an envelope is delivered, or the specified time has elapsed without delivery. More...

uint16_t	GetFreeSlots (void)

bool	IsFull (void)

bool	IsEmpty (void)

Static Public Member Functions
static Mailbox *	Init (uint16_t u16BufferSize_, uint16_t u16ElementSize_)
	Init Create and initialize the mailbox object prior to its use. This must be called before any calls can be made to the object. This version of the API alloctes the buffer space from the kernel's Auto-Allocation heap, which cannot be returned back. As a result, this is only suitable for cases where the mailbox will be created once on startup, and persist for the duration of the system. More...

Private Member Functions
void *	GetHeadPointer (void)
	GetHeadPointer Return a pointer to the current head of the mailbox's internal circular buffer. More...

void *	GetTailPointer (void)
	GetTailPointer Return a pointer to the current tail of the mailbox's internal circular buffer. More...

void	CopyData (const void src_, void dst_, uint16_t len_)
	CopyData Perform a direct byte-copy from a source to a destination object. More...

void	MoveTailForward (void)
	MoveTailForward Move the tail index forward one element. More...

void	MoveHeadForward (void)
	MoveHeadForward Move the head index forward one element. More...

void	MoveTailBackward (void)
	MoveTailBackward Move the tail index backward one element. More...

void	MoveHeadBackward (void)
	MoveHeadBackward Move the head index backward one element. More...

bool	Send_i (const void *pvData_, bool bTail_, uint32_t u32TimeoutMS_)
	Send_i Internal method which implements all Send() methods in the class. More...

bool	Receive_i (void *pvData_, bool bTail_, uint32_t u32WaitTimeMS_)
	Receive_i Internal method which implements all Read() methods in the class. More...

Private Attributes
uint16_t	m_u16Head
	Current head index. More...

uint16_t	m_u16Tail
	Current tail index. More...

uint16_t	m_u16Count
	Count of items in the mailbox. More...

volatile uint16_t	m_u16Free
	Current number of free slots in the mailbox. More...

uint16_t	m_u16ElementSize
	Size of the objects tracked in this mailbox. More...

const void *	m_pvBuffer
	Pointer to the data-buffer managed by this mailbox. More...

Semaphore	m_clRecvSem
	Counting semaphore used to synchronize threads on the object. More...

Semaphore	m_clSendSem
	Binary semaphore for send-blocked threads. More...

Detailed Description

The Mailbox class. This class implements an IPC mechnism based on sending/receiving envelopes containing data of a fixed size, configured at initialization) that reside within a buffer of memory provided by the user.

Examples:: lab11_mailboxes/main.cpp.

Definition at line 35 of file mailbox.h.

Constructor & Destructor Documentation

◆ ~Mailbox()

Mark3::Mailbox::~Mailbox ( )

Definition at line 25 of file mailbox.cpp.

Member Function Documentation

◆ CopyData()

void Mark3::Mailbox::CopyData	(	const void *	src_,
		void *	dst_,
		uint16_t	len_
	)

inlineprivate

CopyData Perform a direct byte-copy from a source to a destination object.

Parameters

src_	Pointer to an object to read from
dst_	Pointer to an object to write to
len_	Length to copy (in bytes)

Definition at line 216 of file mailbox.h.

◆ GetFreeSlots()

uint16_t Mark3::Mailbox::GetFreeSlots ( void )

inline

Definition at line 170 of file mailbox.h.

◆ GetHeadPointer()

void* Mark3::Mailbox::GetHeadPointer ( void )

inlineprivate

GetHeadPointer Return a pointer to the current head of the mailbox's internal circular buffer.

Returns: pointer to the head element in the mailbox

Definition at line 187 of file mailbox.h.

◆ GetTailPointer()

void* Mark3::Mailbox::GetTailPointer ( void )

inlineprivate

GetTailPointer Return a pointer to the current tail of the mailbox's internal circular buffer.

Returns: pointer to the tail element in the mailbox

Definition at line 201 of file mailbox.h.

◆ Init() [1/2]

void Mark3::Mailbox::Init	(	void *	pvBuffer_,
		uint16_t	u16BufferSize_,
		uint16_t	u16ElementSize_
	)

Init Initialize the mailbox object prior to its use. This must be called before any calls can be made to the object.

Parameters

pvBuffer_	Pointer to the static buffer to use for the mailbox
u16BufferSize_	Size of the mailbox buffer, in bytes
u16ElementSize_	Size of each envelope, in bytes

Definition at line 34 of file mailbox.cpp.

◆ Init() [2/2]

Mailbox * Mark3::Mailbox::Init	(	uint16_t	u16BufferSize_,
		uint16_t	u16ElementSize_
	)

static

Init Create and initialize the mailbox object prior to its use. This must be called before any calls can be made to the object. This version of the API alloctes the buffer space from the kernel's Auto-Allocation heap, which cannot be returned back. As a result, this is only suitable for cases where the mailbox will be created once on startup, and persist for the duration of the system.

Parameters

u16BufferSize_	Size of the mailbox buffer, in bytes
u16ElementSize_	Size of each envelope, in bytes

Definition at line 59 of file mailbox.cpp.

◆ IsEmpty()

bool Mark3::Mailbox::IsEmpty ( void )

inline

Definition at line 177 of file mailbox.h.

◆ IsFull()

bool Mark3::Mailbox::IsFull ( void )

inline

Definition at line 176 of file mailbox.h.

◆ MoveHeadBackward()

void Mark3::Mailbox::MoveHeadBackward ( void )

inlineprivate

MoveHeadBackward Move the head index backward one element.

Definition at line 263 of file mailbox.h.

◆ MoveHeadForward()

void Mark3::Mailbox::MoveHeadForward ( void )

inlineprivate

MoveHeadForward Move the head index forward one element.

Definition at line 239 of file mailbox.h.

◆ MoveTailBackward()

void Mark3::Mailbox::MoveTailBackward ( void )

inlineprivate

MoveTailBackward Move the tail index backward one element.

Definition at line 251 of file mailbox.h.

◆ MoveTailForward()

void Mark3::Mailbox::MoveTailForward ( void )

inlineprivate

MoveTailForward Move the tail index forward one element.

Definition at line 227 of file mailbox.h.

◆ operator new()

void* Mark3::Mailbox::operator new	(	size_t	sz,
		void *	pv
	)

inline

Definition at line 38 of file mailbox.h.

◆ Receive() [1/2]

void Mark3::Mailbox::Receive ( void * pvData_ )

Receive Read one envelope from the head of the mailbox. If the mailbox is currently empty, the calling thread will block until an envelope is delivered.

Parameters

pvData_ Pointer to a buffer that will have the envelope's contents copied into upon delivery.

Examples:: lab11_mailboxes/main.cpp.

Definition at line 83 of file mailbox.cpp.

◆ Receive() [2/2]

bool Mark3::Mailbox::Receive	(	void *	pvData_,
		uint32_t	u32TimeoutMS_
	)

Receive Read one envelope from the head of the mailbox. If the mailbox is currently empty, the calling thread will block until an envelope is delivered, or the specified time has elapsed without delivery.

Parameters

pvData_	Pointer to a buffer that will have the envelope's contents copied into upon delivery.
u32TimeoutMS_	Maximum time to wait for delivery.

Returns: true - envelope was delivered, false - delivery timed out.

Definition at line 90 of file mailbox.cpp.

◆ Receive_i()

bool Mark3::Mailbox::Receive_i	(	void *	pvData_,
		bool	bTail_,
		uint32_t	u32WaitTimeMS_
	)

private

Receive_i Internal method which implements all Read() methods in the class.

Parameters

pvData_	Pointer to the envelope data
bTail_	true - read from tail, false - read from head
u32WaitTimeMS_	Time to wait before timeout (in ms).

Returns: true - read successfully, false - timeout.

Definition at line 197 of file mailbox.cpp.

◆ ReceiveTail() [1/2]

void Mark3::Mailbox::ReceiveTail ( void * pvData_ )

ReceiveTail Read one envelope from the tail of the mailbox. If the mailbox is currently empty, the calling thread will block until an envelope is delivered.

Parameters

pvData_ Pointer to a buffer that will have the envelope's contents copied into upon delivery.

Definition at line 97 of file mailbox.cpp.

◆ ReceiveTail() [2/2]

bool Mark3::Mailbox::ReceiveTail	(	void *	pvData_,
		uint32_t	u32TimeoutMS_
	)

ReceiveTail Read one envelope from the tail of the mailbox. If the mailbox is currently empty, the calling thread will block until an envelope is delivered, or the specified time has elapsed without delivery.

Parameters

pvData_	Pointer to a buffer that will have the envelope's contents copied into upon delivery.
u32TimeoutMS_	Maximum time to wait for delivery.

Returns: true - envelope was delivered, false - delivery timed out.

Definition at line 104 of file mailbox.cpp.

◆ Send() [1/2]

bool Mark3::Mailbox::Send ( void * pvData_ )

Send Send an envelope to the mailbox. This safely copies the data contents of the datastructure to the previously-initialized mailbox buffer. If there is a thread already blocking, awaiting delivery to the mailbox, it will be unblocked at this time.

This method delivers the envelope at the head of the mailbox.

Parameters

pvData_ Pointer to the data object to send to the mailbox.

Returns: true - envelope was delivered, false - mailbox is full.

Examples:: lab11_mailboxes/main.cpp.

Definition at line 111 of file mailbox.cpp.

◆ Send() [2/2]

bool Mark3::Mailbox::Send	(	void *	pvData_,
		uint32_t	u32TimeoutMS_
	)

Send Send an envelope to the mailbox. This safely copies the data contents of the datastructure to the previously-initialized mailbox buffer. If there is a thread already blocking, awaiting delivery to the mailbox, it will be unblocked at this time.

This method delivers the envelope at the head of the mailbox.

Parameters

pvData_	Pointer to the data object to send to the mailbox.
u32TimeoutMS_	Maximum time to wait for a free transmit slot

Returns: true - envelope was delivered, false - mailbox is full.

Definition at line 125 of file mailbox.cpp.

◆ Send_i()

bool Mark3::Mailbox::Send_i	(	const void *	pvData_,
		bool	bTail_,
		uint32_t	u32TimeoutMS_
	)

private

Send_i Internal method which implements all Send() methods in the class.

Parameters

pvData_	Pointer to the envelope data
bTail_	true - write to tail, false - write to head
u32TimeoutMS_	Time to wait before timeout (in ms).

Returns: true - data successfully written, false - buffer full

Definition at line 139 of file mailbox.cpp.

◆ SendTail() [1/2]

bool Mark3::Mailbox::SendTail ( void * pvData_ )

SendTail Send an envelope to the mailbox. This safely copies the data contents of the datastructure to the previously-initialized mailbox buffer. If there is a thread already blocking, awaiting delivery to the mailbox, it will be unblocked at this time.

This method delivers the envelope at the tail of the mailbox.

Parameters

pvData_ Pointer to the data object to send to the mailbox.

Returns: true - envelope was delivered, false - mailbox is full.

Definition at line 118 of file mailbox.cpp.

◆ SendTail() [2/2]

bool Mark3::Mailbox::SendTail	(	void *	pvData_,
		uint32_t	u32TimeoutMS_
	)

SendTail Send an envelope to the mailbox. This safely copies the data contents of the datastructure to the previously-initialized mailbox buffer. If there is a thread already blocking, awaiting delivery to the mailbox, it will be unblocked at this time.

This method delivers the envelope at the tail of the mailbox.

Parameters

pvData_	Pointer to the data object to send to the mailbox.
u32TimeoutMS_	Maximum time to wait for a free transmit slot

Returns: true - envelope was delivered, false - mailbox is full.

Definition at line 132 of file mailbox.cpp.

Member Data Documentation

◆ m_clRecvSem

Semaphore Mark3::Mailbox::m_clRecvSem

private

Counting semaphore used to synchronize threads on the object.

Definition at line 302 of file mailbox.h.

◆ m_clSendSem

Semaphore Mark3::Mailbox::m_clSendSem

private

Binary semaphore for send-blocked threads.

Definition at line 303 of file mailbox.h.

◆ m_pvBuffer

const void* Mark3::Mailbox::m_pvBuffer

private

Pointer to the data-buffer managed by this mailbox.

Definition at line 300 of file mailbox.h.

◆ m_u16Count

uint16_t Mark3::Mailbox::m_u16Count

private

Count of items in the mailbox.

Definition at line 296 of file mailbox.h.

◆ m_u16ElementSize

uint16_t Mark3::Mailbox::m_u16ElementSize

private

Size of the objects tracked in this mailbox.

Definition at line 299 of file mailbox.h.

◆ m_u16Free

volatile uint16_t Mark3::Mailbox::m_u16Free

private

Current number of free slots in the mailbox.

Definition at line 297 of file mailbox.h.

◆ m_u16Head

uint16_t Mark3::Mailbox::m_u16Head

private

Current head index.

Definition at line 293 of file mailbox.h.

◆ m_u16Tail

uint16_t Mark3::Mailbox::m_u16Tail

private

Current tail index.

Definition at line 294 of file mailbox.h.

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

/mnt/c/Users/moslevin/m3-repo2/kernel/src/public/mailbox.h
/mnt/c/Users/moslevin/m3-repo2/kernel/src/mailbox.cpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~Mailbox()

Member Function Documentation

◆ CopyData()

◆ GetFreeSlots()

◆ GetHeadPointer()

◆ GetTailPointer()

◆ Init() [1/2]

◆ Init() [2/2]

◆ IsEmpty()

◆ IsFull()

◆ MoveHeadBackward()

◆ MoveHeadForward()

◆ MoveTailBackward()

◆ MoveTailForward()

◆ operator new()

◆ Receive() [1/2]

◆ Receive() [2/2]

◆ Receive_i()

◆ ReceiveTail() [1/2]

◆ ReceiveTail() [2/2]

◆ Send() [1/2]

◆ Send() [2/2]

◆ Send_i()

◆ SendTail() [1/2]

◆ SendTail() [2/2]

Member Data Documentation

◆ m_clRecvSem

◆ m_clSendSem

◆ m_pvBuffer

◆ m_u16Count

◆ m_u16ElementSize

◆ m_u16Free

◆ m_u16Head

◆ m_u16Tail