The Mail class allows you to control, send, receive or wait for mail. More...

#include <Mail.h>

Inheritance diagram for Mail< T, queue_sz >:

Public Member Functions
	Mail ()=default
	Create and initialize Mail queue. More...

bool	empty () const
	Check if the mail queue is empty. More...

bool	full () const
	Check if the mail queue is full. More...

T *	alloc (MBED_UNUSED uint32_t millisec=0)
	Allocate a memory block of type T, without blocking. More...

T *	try_alloc ()
	Allocate a memory block of type T, without blocking. More...

T *	try_alloc_for (Kernel::Clock::duration_u32 rel_time)
	Allocate a memory block of type T, optionally blocking. More...

T *	alloc_for (uint32_t millisec)
	Allocate a memory block of type T, optionally blocking. More...

T *	try_alloc_until (Kernel::Clock::time_point abs_time)
	Allocate a memory block of type T, blocking. More...

T *	alloc_until (uint64_t millisec)
	Allocate a memory block of type T, blocking. More...

T *	calloc (MBED_UNUSED uint32_t millisec=0)
	Allocate a memory block of type T, and set memory block to zero. More...

T *	try_calloc ()
	Allocate a memory block of type T, and set memory block to zero. More...

T *	try_calloc_for (Kernel::Clock::duration_u32 rel_time)
	Allocate a memory block of type T, optionally blocking, and set memory block to zero. More...

T *	calloc_for (uint32_t millisec)
	Allocate a memory block of type T, optionally blocking, and set memory block to zero. More...

T *	try_calloc_until (Kernel::Clock::time_point abs_time)
	Allocate a memory block of type T, blocking, and set memory block to zero. More...

T *	calloc_until (uint64_t millisec)
	Allocate a memory block of type T, blocking, and set memory block to zero. More...

osStatus	put (T *mptr)
	Put a mail in the queue. More...

osEvent	get (uint32_t millisec=osWaitForever)
	Get a mail from the queue. More...

T *	try_get ()
	Get a mail from the queue. More...

T *	try_get_for (Kernel::Clock::duration_u32 rel_time)
	Get a mail from the queue. More...

osStatus	free (T *mptr)
	Free a memory block from a mail. More...

Detailed Description

template<typename T, uint32_t queue_sz>
class rtos::Mail< T, queue_sz >

The Mail class allows you to control, send, receive or wait for mail.

A mail is a memory block that is sent to a thread or interrupt service routine (ISR).

Template Parameters

T	Data type of a single mail message element.
queue_sz	Maximum number of mail messages in queue.

Note: Memory considerations: The mail data store and control structures are part of this class - they do not (themselves) allocate memory on the heap, both for the Mbed OS and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).; Bare metal profile: This class is not supported.

Definition at line 68 of file Mail.h.

Constructor & Destructor Documentation

◆ Mail()

Mail ( )

default

Create and initialize Mail queue.

Note: You cannot call this function from ISR context.

Member Function Documentation

◆ empty()

bool empty ( ) const

Check if the mail queue is empty.

Returns: State of queue.

Return values

true	Mail queue is empty.
false	Mail queue contains mail.

Note: You may call this function from ISR context.

Definition at line 84 of file Mail.h.

◆ full()

bool full ( ) const

Check if the mail queue is full.

Returns: State of queue.

Return values

true	Mail queue is full.
false	Mail queue is not full.

Note: You may call this function from ISR context.

Definition at line 97 of file Mail.h.

◆ alloc()

T * alloc ( MBED_UNUSED uint32_t millisec = 0 )

Allocate a memory block of type T, without blocking.

Parameters

millisec Not used (see note).

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You may call this function from ISR context.; If blocking is required, use Mail::try_alloc_for or Mail::try_alloc_until

Deprecated:: Replaced with try_alloc. In future alloc() will be an untimed blocking call.

Definition at line 113 of file Mail.h.

◆ try_alloc()

T * try_alloc ( )

Allocate a memory block of type T, without blocking.

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You may call this function from ISR context.; If blocking is required, use Mail::try_alloc_for or Mail::try_alloc_until

Definition at line 125 of file Mail.h.

◆ try_alloc_for()

T * try_alloc_for ( Kernel::Clock::duration_u32 rel_time )

Allocate a memory block of type T, optionally blocking.

Parameters

rel_time Timeout value, or Kernel::wait_for_u32_forever.

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You may call this function from ISR context if the millisec parameter is set to 0.

Definition at line 138 of file Mail.h.

◆ alloc_for()

T * alloc_for ( uint32_t millisec )

Allocate a memory block of type T, optionally blocking.

Parameters

millisec Timeout value, or osWaitForever.

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You may call this function from ISR context if the millisec parameter is set to 0.

Deprecated:: Pass a chrono duration, not an integer millisecond count. For example use 5s rather than 5000.

Definition at line 153 of file Mail.h.

◆ try_alloc_until()

T * try_alloc_until ( Kernel::Clock::time_point abs_time )

Allocate a memory block of type T, blocking.

Parameters

abs_time Absolute timeout time, referenced to Kernel::Clock.

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You cannot call this function from ISR context.; the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the wait will time out earlier than specified.

Definition at line 170 of file Mail.h.

◆ alloc_until()

T * alloc_until ( uint64_t millisec )

Allocate a memory block of type T, blocking.

Parameters

millisec Absolute timeout time, referenced to Kernel::get_ms_count().

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You cannot call this function from ISR context.; the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the wait will time out earlier than specified.

Deprecated:: Pass a chrono time_point, not an integer millisecond count. For example use Kernel::Clock::now() + 5s rather than Kernel::get_ms_count() + 5000.

Definition at line 190 of file Mail.h.

◆ calloc()

T * calloc ( MBED_UNUSED uint32_t millisec = 0 )

Allocate a memory block of type T, and set memory block to zero.

Parameters

millisec Not used (see note).

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You may call this function from ISR context.; If blocking is required, use Mail::try_calloc_for or Mail::try_calloc_until

Deprecated:: Replaced with try_calloc. In future calloc() will be an untimed blocking call.

Definition at line 206 of file Mail.h.

◆ try_calloc()

T * try_calloc ( )

Allocate a memory block of type T, and set memory block to zero.

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You may call this function from ISR context.; If blocking is required, use Mail::try_calloc_for or Mail::try_calloc_until

Definition at line 218 of file Mail.h.

◆ try_calloc_for()

T * try_calloc_for ( Kernel::Clock::duration_u32 rel_time )

Allocate a memory block of type T, optionally blocking, and set memory block to zero.

Parameters

rel_time Timeout value, or Kernel::wait_for_u32_forever.

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You may call this function from ISR context if the rel_time parameter is set to 0.

Definition at line 231 of file Mail.h.

◆ calloc_for()

T * calloc_for ( uint32_t millisec )

Allocate a memory block of type T, optionally blocking, and set memory block to zero.

Parameters

millisec Timeout value, or osWaitForever.

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You may call this function from ISR context if the millisec parameter is set to 0.

Deprecated:: Pass a chrono duration, not an integer millisecond count. For example use 5s rather than 5000.

Definition at line 246 of file Mail.h.

◆ try_calloc_until()

T * try_calloc_until ( Kernel::Clock::time_point abs_time )

Allocate a memory block of type T, blocking, and set memory block to zero.

Parameters

abs_time Absolute timeout time, referenced to Kernel::Clock.

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You cannot call this function from ISR context.; the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the wait will time out earlier than specified.

Definition at line 263 of file Mail.h.

◆ calloc_until()

T * calloc_until ( uint64_t millisec )

Allocate a memory block of type T, blocking, and set memory block to zero.

Parameters

millisec Absolute timeout time, referenced to Kernel::get_ms_count().

Returns: Pointer to memory block that you can fill with mail or nullptr in case error.

Note: You cannot call this function from ISR context.; the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the wait will time out earlier than specified.

Deprecated:: Pass a chrono time_point, not an integer millisecond count. For example use Kernel::Clock::now() + 5s rather than Kernel::get_ms_count() + 5000.

Definition at line 283 of file Mail.h.

◆ put()

osStatus put ( T * mptr )

Put a mail in the queue.

Parameters

mptr	Memory block previously allocated with Mail::alloc or Mail::calloc.

Returns: Status code that indicates the execution status of the function (osOK on success). See note.

Note: You may call this function from ISR context.; As the mail should have already been allocated, and the memory pool is the same size as the queue, the put operation should always succeed, despite being implemented with Queue::try_put - there is room in the queue for every mail from the pool. Therefore use of the return value is deprecated, and the function will return void in future.

Definition at line 301 of file Mail.h.

◆ get()

osEvent get ( uint32_t millisec = osWaitForever )

Get a mail from the queue.

Parameters

millisec Timeout value (default: osWaitForever).

Returns: Event that contains mail information and status code. The status code is stored in the status member: osEventMail Mail successfully received. osOK No mail is available (and no timeout was specified). osEventTimeout No mail has arrived during the given timeout period. osErrorParameter A parameter is invalid or outside of a permitted range.

Note: You may call this function from ISR context if the millisec parameter is set to 0.

Deprecated:: Replaced with try_get and try_get_for. In future get will be an untimed blocking call.

Definition at line 323 of file Mail.h.

◆ try_get()

T * try_get ( )

Get a mail from the queue.

Returns: Pointer to received mail, or nullptr if none was received.

Note: You may call this function from ISR context.

Definition at line 338 of file Mail.h.

◆ try_get_for()

T * try_get_for ( Kernel::Clock::duration_u32 rel_time )

Get a mail from the queue.

Parameters

rel_time Timeout value or Kernel::wait_for_u32_forever.

Returns: Pointer to received mail, or nullptr if none was received.

Note: You may call this function from ISR context if the millisec parameter is set to 0.

Definition at line 353 of file Mail.h.

◆ free()

osStatus free ( T * mptr )

Free a memory block from a mail.

Parameters

mptr	Pointer to the memory block that was obtained with Mail::get.

Returns: Status code that indicates the execution status of the function (osOK on success).

Note: You may call this function from ISR context.

Definition at line 368 of file Mail.h.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Mail()

Member Function Documentation

◆ empty()

◆ full()

◆ alloc()

◆ try_alloc()

◆ try_alloc_for()

◆ alloc_for()

◆ try_alloc_until()

◆ alloc_until()

◆ calloc()

◆ try_calloc()

◆ try_calloc_for()

◆ calloc_for()

◆ try_calloc_until()

◆ calloc_until()

◆ put()

◆ get()

◆ try_get()

◆ try_get_for()

◆ free()