module ti.sysbios.knl.Mailbox

Mailbox Manager

C synopsis
Individual elements
XDCscript usage
Individual elements

The Mailbox module makes available a set of functions that manipulate mailbox objects accessed through handles of type Mailbox_Handle. [ more ... ]

C synopsis target-domain sourced in ti/sysbios/knl/Mailbox.xdc

#include <ti/sysbios/knl/Mailbox.h>

Functions
Void	Mailbox_construct// Initialize a new instance object inside the provided structure(Mailbox_Struct structP, SizeT msgSize, UInt numMsgs, const Mailbox_Params params, Error_Block *eb);
Mailbox_Handle	Mailbox_create// Allocate and initialize a new instance object and return its handle(SizeT msgSize, UInt numMsgs, const Mailbox_Params params, Error_Block eb);
Void	Mailbox_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Mailbox_Handle *handleP);
Void	Mailbox_destruct// Finalize the instance object inside the provided structure(Mailbox_Struct *structP);
SizeT	Mailbox_getMsgSize// Get the message size(Mailbox_Handle handle);
Int	Mailbox_getNumFreeMsgs// Get the number messages available for use(Mailbox_Handle handle);
Int	Mailbox_getNumPendingMsgs// Get the number of messages that are ready to be read(Mailbox_Handle handle);
Void	Mailbox_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Mailbox_Params *params);
Bool	Mailbox_pend// Wait for a message from mailbox(Mailbox_Handle handle, Ptr msg, UInt timeout);
Bool	Mailbox_post// Post a message to mailbox(Mailbox_Handle handle, Ptr msg, UInt timeout);
Functions common to all target instances
	Mailbox_handle// Convert this instance structure pointer into an instance handle, Mailbox_Handle_label// The label associated with this instance object, Mailbox_Handle_name// The name of this instance object, Mailbox_Object_count// The number of statically-created instance objects, Mailbox_Object_first// The handle of the first dynamically-created instance object, or NULL, Mailbox_Object_get// The handle of the i-th statically-created instance object (array == NULL), Mailbox_Object_heap// The heap used to allocate dynamically-created instance objects, Mailbox_Object_next// The handle of the next dynamically-created instance object, or NULL, Mailbox_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	Mailbox_Module_getMask// Returns the diagnostics mask for this module, Mailbox_Module_hasMask// Test whether this module has a diagnostics mask, Mailbox_Module_heap// The heap from which this module allocates memory, Mailbox_Module_id// Get this module's unique id, Mailbox_Module_setMask// Set the diagnostics mask for this module, Mailbox_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Mailbox_Object *	Mailbox_Handle// Client reference to an instance object;
typedef struct	Mailbox_MbxElem// The header used to save each Mailbox message ...
typedef struct	Mailbox_Object// Opaque internal representation of an instance object Mailbox_Object;
typedef struct	Mailbox_Params// Instance config-params structure ...
typedef struct	Mailbox_Struct// Opaque client structure large enough to hold an instance object Mailbox_Struct;
Constants
extern const Assert_Id	Mailbox_A_invalidBufSize// Assert raised when the bufSize parameter is too small;

DETAILS

The Mailbox module makes available a set of functions that manipulate mailbox objects accessed through handles of type Mailbox_Handle.

pend() is used to wait for a message from a mailbox. The timeout parameter to Mailbox_pend allows the task to wait until a timeout specified in terms of system clock ticks. A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for a message. A timeout value of BIOS_NO_WAIT causes Mailbox_pend to return immediately. Mailbox_pend's return value indicates whether the mailbox was signaled successfully.

When a Mailbox has been configured with a readerEvent Event object and a task has returned from Event.pend() with the corresponding readerEventId, then BIOS_NO_WAIT should be passed to Mailbox_pend() to retrieve the message.

NOTE: Since only a single reader can pend on a readerEvent Event object, a Mailbox configured with a readerEvent Event object does not support multiple readers.

post() is used to send a message to a mailbox. The timeout parameter to Mailbox_post specifies the amount of time the calling task waits if the mailbox is full.

When a Mailbox has been configured with a writerEvent Event object and a task has returned from Event.pend() with the corresponding writerEventId, then BIOS_NO_WAIT should be passed to Mailbox_post() knowing that the message will be successfully posted.

NOTE: Since only a single writer can pend on a writerEvent Event object, a Mailbox configured with a writerEvent Event object does not support multiple writers.

Calling Context

Function	Hwi	Swi	Task	Main	Startup
Params_init	Y	Y	Y	Y	Y
construct	N	N	Y	Y	N
create	N	N	Y	Y	N
delete	N	N	Y	Y	N
destruct	N	N	Y	Y	N
getNumFreeMsgs	Y	Y	Y	N	N
getNumPendingMsgs	Y	Y	Y	N	N
pend	N*	N*	Y	N*	N
post	N*	N*	Y	N*	N
Definitions: (N* means OK to call iff the timeout parameter is set to '0'.) Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. Mailbox_Module_startupDone() returns TRUE). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. Mailbox_Module_startupDone() returns FALSE).

struct Mailbox_MbxElem