MessageQueue module for the RTOS Porting Interface.
============================================================================
MessageQueueP objects are RTOS message queues backed by OS-specific queue or mailbox objects.
Message queues can be used for intertask communication. They support sending messages between tasks, and between interrupts and tasks. Message queues can either be allocated statically with MessageQueueP_construct() or dynamically with MessageQueueP_create().
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <ti/devices/DeviceFamily.h>
Go to the source code of this file.
Data Structures | |
union | MessageQueueP_Struct |
MessageQueueP structure. More... | |
Macros | |
#define | MessageQueueP_STRUCT_SIZE (104) |
Number of bytes greater than or equal to the size of any RTOS Queue/Mailbox data structure. More... | |
#define | MessageQueueP_BUFFER_SIZE(msgSize, msgCount) ((msgCount) * ((msgSize) + 8)) |
Required number of bytes of a statically allocated message queue buffer. More... | |
#define | MessageQueueP_WAIT_FOREVER ~(0) |
Wait forever define. More... | |
#define | MessageQueueP_NO_WAIT (0) |
No wait define. More... | |
Typedefs | |
typedef union MessageQueueP_Struct | MessageQueueP_Struct |
MessageQueueP structure. More... | |
typedef void * | MessageQueueP_Handle |
Opaque client reference to an instance of a MessageQueueP. More... | |
Enumerations | |
enum | MessageQueueP_Status { MessageQueueP_OK = 0, MessageQueueP_TIMEOUT = -1 } |
Status codes for MessageQueueP APIs. More... | |
Functions | |
MessageQueueP_Handle | MessageQueueP_create (size_t msgSize, size_t msgCount) |
Create a MessageQueueP, allocating memory on the heap. More... | |
MessageQueueP_Handle | MessageQueueP_construct (MessageQueueP_Struct *queueStruct, size_t msgSize, size_t msgCount, void *msgBuf) |
Construct a MessageQueueP from statically allocated memory. More... | |
void | MessageQueueP_delete (MessageQueueP_Handle handle) |
Delete a MessageQueueP. More... | |
void | MessageQueueP_destruct (MessageQueueP_Handle handle) |
Destruct a MessageQueueP. More... | |
MessageQueueP_Status | MessageQueueP_pend (MessageQueueP_Handle handle, void *message, uint32_t timeout) |
Receive an item from a message queue. More... | |
MessageQueueP_Status | MessageQueueP_peek (MessageQueueP_Handle handle, void *message, uint32_t timeout) |
Receive an item from a message queue without removing the item from the queue. More... | |
MessageQueueP_Status | MessageQueueP_post (MessageQueueP_Handle handle, const void *message, uint32_t timeout) |
Post an item on a message queue. More... | |
MessageQueueP_Status | MessageQueueP_postFront (MessageQueueP_Handle handle, const void *message, uint32_t timeout) |
Post an item in the front of a message queue. More... | |
size_t | MessageQueueP_getPendingCount (MessageQueueP_Handle handle) |
Get the number of messages stored in a message queue. More... | |
size_t | MessageQueueP_getFreeCount (MessageQueueP_Handle handle) |
Get the number of free spaces in a message queue. More... | |
#define MessageQueueP_STRUCT_SIZE (104) |
Number of bytes greater than or equal to the size of any RTOS Queue/Mailbox data structure.
TI-RTOS7: 104 FreeRTOS: 80
#define MessageQueueP_BUFFER_SIZE | ( | msgSize, | |
msgCount | |||
) | ((msgCount) * ((msgSize) + 8)) |
Required number of bytes of a statically allocated message queue buffer.
This macro is defined to support the user in configuring the size of a message queue buffer. A pointer to this user defined buffer is one of the arguments of the MessageQueueP_construct() function. The macro gives the minimal number of bytes required for the message queue. Please note the following for devices supporting TI-RTOS7:
#define MessageQueueP_WAIT_FOREVER ~(0) |
Wait forever define.
#define MessageQueueP_NO_WAIT (0) |
No wait define.
typedef union MessageQueueP_Struct MessageQueueP_Struct |
MessageQueueP structure.
Opaque structure that should be large enough to hold any of the RTOS specific MessageQueueP objects.
typedef void* MessageQueueP_Handle |
Opaque client reference to an instance of a MessageQueueP.
A MessageQueueP_Handle returned from MessageQueueP_create() or MessageQueueP_construct() represents that instance. It is then is used in the other instance based functions (e.g. MessageQueueP_pend(), MessageQueueP_post(), etc.).
enum MessageQueueP_Status |
MessageQueueP_Handle MessageQueueP_create | ( | size_t | msgSize, |
size_t | msgCount | ||
) |
Create a MessageQueueP, allocating memory on the heap.
MessageQueueP_create creates a new message queue object. MessageQueueP_create returns the handle of the new message queue object or NULL if the message queue could not be created.
The message queue object will be allocated on the heap - make sure you have a sufficiently large heap.
For FreeRTOS, configSUPPORT_DYNAMIC_ALLOCATION has to be set to 1 in FreeRTOSConfig.h. See 'Configuration with FreeRTOS' in the Core SDK User's Guide for how to do this.
msgSize | The size, in bytes, required to hold each item in the message queue |
msgCount | The maximum number of items the message queue can hold at any one time |
MessageQueueP | handle (NULL on failure) |
MessageQueueP_Handle MessageQueueP_construct | ( | MessageQueueP_Struct * | queueStruct, |
size_t | msgSize, | ||
size_t | msgCount, | ||
void * | msgBuf | ||
) |
Construct a MessageQueueP from statically allocated memory.
MessageQueueP_construct creates a new message queue object. MessageQueueP_construct returns the handle of the new message queue object or NULL if the message queue could not be created.
To use MessageQueueP_construct msgBuf must point to a valid preallocated memory array that is at least large enough to hold the maximum number of items that can be in the message queue at any one time.
For FreeRTOS, configSUPPORT_STATIC_ALLOCATION has to be set to 1 in FreeRTOSConfig.h. See 'Configuration with FreeRTOS' in the Core SDK User's Guide for how to do this.
queueStruct | Must point to a variable that holds the message queue's data structure |
msgSize | The size, in bytes, required to hold each item in the message queue |
msgCount | The maximum number of items the message queue can hold at any one time |
msgBuf | Pointer to variable that holds the message queue's data buffer |
MessageQueueP | handle (NULL on failure) |
void MessageQueueP_delete | ( | MessageQueueP_Handle | handle | ) |
Delete a MessageQueueP.
MessageQueueP_delete finalizes and frees this previously allocated message queue object, setting the referenced handle to NULL. This function should be used when the message queue was created by the MessageQueueP_create() function.
handle | A handle to the message queue to be deleted |
void MessageQueueP_destruct | ( | MessageQueueP_Handle | handle | ) |
Destruct a MessageQueueP.
MessageQueueP_destruct finalizes the message queue object inside the provided structure. This function should be used when the message queue was constructed by the MessageQueueP_construct() function.
handle | A handle to the message queue to be destructed |
MessageQueueP_Status MessageQueueP_pend | ( | MessageQueueP_Handle | handle, |
void * | message, | ||
uint32_t | timeout | ||
) |
Receive an item from a message queue.
MessageQueueP_pend receives an item from the provided message queue.
handle | The handle to the message queue from which the item is to be received |
message | Pointer to the buffer into which the received item will be copied |
timeout | The maximum duration in system clock ticks a task should block waiting for an item to be received. When no wait or wait forever options are wanted the MessageQueueP_NO_WAIT and MessageQueueP_WAIT_FOREVER defines can be used. |
Status | of the function
|
MessageQueueP_Status MessageQueueP_peek | ( | MessageQueueP_Handle | handle, |
void * | message, | ||
uint32_t | timeout | ||
) |
Receive an item from a message queue without removing the item from the queue.
MessageQueueP_peek receives an item from the provided message queue without removing the item from the queue.
handle | The handle to the message queue from which the item is to be received |
message | Pointer to the buffer into which the received item will be copied |
timeout | The maximum duraton in system clock ticks a task should block waiting for an item to be received. When no wait or wait forever options are wanted the MessageQueueP_NO_WAIT and MessageQueueP_WAIT_FOREVER defines can be used. |
Status | of the function
|
MessageQueueP_Status MessageQueueP_post | ( | MessageQueueP_Handle | handle, |
const void * | message, | ||
uint32_t | timeout | ||
) |
Post an item on a message queue.
MessageQueueP_post posts an item on the provided message queue.
handle | The handle to the message queue to which the item is to be posted |
message | Pointer to the buffer from which the item to be posted is copied |
timeout | The maximum duraton in system clock ticks a task should block waiting for an item to be posted. When no wait or wait forever options are wanted the MessageQueueP_NO_WAIT and MessageQueueP_WAIT_FOREVER defines can be used. |
Status | of the function
|
MessageQueueP_Status MessageQueueP_postFront | ( | MessageQueueP_Handle | handle, |
const void * | message, | ||
uint32_t | timeout | ||
) |
Post an item in the front of a message queue.
MessageQueueP_postFront posts an item in the front of the provided message queue.
handle | The handle to the message queue to which the item is to be posted |
message | Pointer to the buffer from which the item to be posted is copied |
timeout | The maximum duraton in system clock ticks a task should block waiting for an item to be posted. When no wait or wait forever options are wanted the MessageQueueP_NO_WAIT and MessageQueueP_WAIT_FOREVER defines can be used. |
Status | of the function
|
size_t MessageQueueP_getPendingCount | ( | MessageQueueP_Handle | handle | ) |
Get the number of messages stored in a message queue.
Returns the number of messages in the specified message queue.
handle | A MessageQueueP_Handle returned from MessageQueueP_create() or MessageQueueP_construct() |
Number | of stored messages in the specified message queue |
size_t MessageQueueP_getFreeCount | ( | MessageQueueP_Handle | handle | ) |
Get the number of free spaces in a message queue.
Returns the number of free spaces in the specified message queue.
handle | A MessageQueueP_Handle returned from MessageQueueP_create() or MessageQueueP_construct() |
Number | of free spaces in the specified message queue |