Detailed Description
For detailed information about using message boxes please see detailed description of message boxes
Function Documentation
| NANOEXT void* POSCALL nosMessageAlloc |
( |
UINT_t |
msgSize | ) |
|
Message box function. Allocates a new message buffer. To increase the execution speed, it is recommended to set POSCFG_MSG_MEMORY to 1. Otherwise, nosMessageAlloc will need to call nosMemAlloc to allocate memory (and this is possibly slower than the pico]OS internal message allocator).
Usually the sending task would allocate a new message buffer, fill in its data and send it via nosMessageSend to the receiving task. The receiving task is responsible for freeing the message buffer again.
- Parameters:
-
| msgSize | size of the requested message buffer in bytes. |
- Returns:
- the pointer to the new buffer. NULL is returned if the system is low on memory or the requested msgSize is larger than POSCFG_MSG_BUFSIZE (only if POSCFG_MSG_MEMORY is set to 1).
- Note:
- NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in.
If POSCFG_MSG_MEMORY is set to 0, you also need to enable the nano layer memory manager by setting NOSCFG_FEATURE_MEMALLOC to 1.
- See also:
- nosMessageSend, nosMessageGet, nosMessageFree
| NANOEXT VAR_t POSCALL nosMessageAvailable |
( |
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:
- NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in.
Dependent of your configuration, this function can be defined as macro to decrease code size.
- See also:
- nosMessageGet, nosMessageWait
| NANOEXT void POSCALL nosMessageFree |
( |
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:
- NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in.
- See also:
- nosMessageGet, nosMessageSend, nosMessageAlloc
| NANOEXT void* POSCALL nosMessageGet |
( |
void |
| ) |
|
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.
- Returns:
- Pointer to the received message. Note that the message memory must be freed again with nosMessageFree when the message buffer is no more used.
- Note:
- NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in.
Dependent of your configuration, this function can be defined as macro to decrease code size.
- See also:
- nosMessageFree, nosMessageAvailable, nosMessageWait, nosMessageSend
| NANOEXT VAR_t POSCALL nosMessageSend |
( |
void * |
buf, |
|
|
NOSTASK_t |
taskhandle |
|
) |
| |
Message box function. Sends a message to a task.
- Parameters:
-
| buf | Pointer to the message to send. The message buffer must have been allocated by calling nosMessageAlloc before. |
| taskhandle | handle to the task to send the message to. |
- Returns:
- zero on success. When an error condition exist, a negative value is returned and the message buffer is freed.
- Note:
- NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in.
- See also:
- nosMessageAlloc, nosMessageGet
| NANOEXT void* POSCALL nosMessageWait |
( |
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 nosMessageFree when the message buffer is no more used. NULL is returned when no message was received within the specified time (=timeout).
- Note:
- NOSCFG_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.
Dependent of your configuration, this function can be defined as macro to decrease code size.
- See also:
- nosMessageFree, nosMessageGet, nosMessageAvailable, nosMessageSend, HZ, MS
