Detailed Description
Message boxes are a mechanism that is used for inter-process or, in the case of pico]OS, inter-task communication. All tasks can post messages to each other, and the receiving task will look into its message box and continues when it got a new message. Note that a message box in the pico]OS can hold chunk of messages, so that no message will be lost while the receiving task is still busy processing the last message.
There are two possible types of message boxes: The simple type can only hold a pointer to a user supplied buffer. The other message box type can hold whole messages with different sizes. A message buffer must be allocated with posMessageAlloc by the sending task, and the receiving task must free this buffer again with posMessageFree.
To select the simple message box type, you have to set the define POSCFG_MSG_MEMORY to 0. When you want to have the full message buffer support, you must set POSCFG_MSG_MEMORY to 1.
Function Documentation
| POSEXTERN void* POSCALL posMessageAlloc |
( |
void |
| ) |
|
| POSEXTERN VAR_t POSCALL posMessageAvailable |
( |
void |
| ) |
|
Message box function. Tests if a new message is available in the message box. This function can be used to prevent the task from blocking.
- Returns:
- 1 (=true) when a new message is available. Otherwise zero is returned. A negative value is returned on error.
- Note:
- POSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in.
- See also:
- posMessageGet, posMessageWait
| POSEXTERN void POSCALL posMessageFree |
( |
void * |
buf | ) |
|
Message box function. Frees a message buffer again. Usually the receiving task would call this function after it has processed a message to free the message buffer again.
- Parameters:
-
| buf | pointer to the message buffer that is no more used. |
- Note:
- POSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in.
POSCFG_MSG_MEMORY must be defined to 1 to have this function compiled in.
- See also:
- posMessageGet, posMessageSend, posMessageAlloc
| POSEXTERN void* POSCALL posMessageGet |
( |
void |
| ) |
|
| POSEXTERN VAR_t POSCALL posMessageSend |
( |
void * |
buf, |
|
|
POSTASK_t |
taskhandle |
|
) |
| |
Message box function. Sends a message to a task.
- Parameters:
-
- Returns:
- zero on success. When an error condition exist, a negative value is returned and the message buffer is freed.
- Note:
- POSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in.
- See also:
- posMessageAlloc, posMessageGet
| POSEXTERN void* POSCALL posMessageWait |
( |
UINT_t |
timeoutticks | ) |
|
Message box function. Gets a new message from the message box. If no message is available, the task blocks until a new message is received or the timeout has been reached.
- Parameters:
-
| timeoutticks | timeout in timer ticks (see HZ define and MS macro). If this parameter is set to zero, the function immediately returns. If this parameter is set to INFINITE, the function will never time out. |
- Returns:
- pointer to the received message. Note that the message memory must be freed again with posMessageFree when POSCFG_MSG_MEMORY is defined to 1. NULL is returned when no message was received within the specified time (=timeout).
Hint: NULL may also be returned when the system has not enough events. In this case, please increase the value for POSCFG_MAX_EVENTS in your poscfg.h .
- Note:
- POSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in.
POSCFG_FEATURE_MSGWAIT must be defined to 1 to have this function compiled in.
- See also:
- posMessageFree, posMessageGet, posMessageAvailable, posMessageSend, HZ, MS
