OS21 Message handling
message_claim
Claim a message buffer
Definition:
#include <os21.h> void* message_claim(
message_queue_t* queue);
Arguments:
message_queue_t* queue
Returns:
Errors:
Context:
Description:
See also:
The message queue from which the message is claimed
The next available message buffer.
None
Callable from task only.
message_claim()
claims the next available message buffer from the message queue, and returns its address. If no message buffers are currently available then the task blocks until one becomes available (by another task calling message_release()
).
This function is not callable from an interrupt handler, and is equivalent to: message_claim_timeout(queue, TIMEOUT_INFINITY) message_receive
, message_release, message_send
7358306 133/226
Message handling OS21
message_claim_timeout
Claim a message buffer or timeout
Definition:
#include <os21.h> void* message_claim_timeout(
message_queue_t* queue
const osclock_t* time);
Arguments:
message_queue_t* queue const osclock_t* time
The message queue from which the message is claimed
The maximum time to wait for a message
Returns:
Errors:
Context:
The next available message buffer, or NULL if a timeout occurs.
None
Callable from task or system context. Only valid from system context if time is
TIMEOUT_IMMEDIATE
.
Description:
message_claim_timeout()
claims the next available message buffer from the message queue, and returns its address. If no message buffers are currently available then the task blocks until one becomes available (by another task calling message_release()
), or the time specified by time is reached.
Note:
time
is an absolute not a relative value, so if a relative timeout is required this needs to be made explicit, as shown in the following example.
Example:
See also:
time
is specified in ticks. A tick is an implementation dependent quantity.
Two special time values may also be specified for time. TIMEOUT_IMMEDIATE causes the message queue to be polled, that is, the function always returns immediately. If a message is available then it is returned, otherwise the function returns immediately with a result of NULL. A timeout of TIMEOUT_INFINITY behaves exactly as message_claim().
message_claim_timeout()
can be used from an interrupt handler, as long as time
is TIMEOUT_IMMEDIATE.
osclock_t time; time = time_plus(time_now(), time_ticks_per_sec()); message_claim_timeout(message_queue, &time); message_receive_timeout
, message_send, message_release
134/226 7358306
OS21 Message handling
message_create_queue
Create a fixed size message queue
Definition:
#include <os21.h> message_queue_t* message_create_queue(
size_t max_message_size,
unsigned int max_messages);
Arguments:
size_t max_message_size unsigned int max_messages
The maximum size of a message, in bytes
The maximum number of messages
Returns:
Errors:
Context:
Description:
See also:
The message queue identifier, or NULL on failure.
Returns NULL if there is insufficient memory for the message queue.
Callable from task only.
message_create_queue()
creates a message queue with buffering for a fixed number of fixed size messages. Buffer space for the messages and the message_queue_t
structure, is created automatically by the function from the system heap.
memory_allocate
, message_claim, message_send, message_delete_queue
, message_receive, message_release
7358306 135/226
Message handling OS21
message_create_queue_p
Create a fixed size message queue
Definition:
#include <os21.h> message_queue_t* message_create_queue_p(
partition_t* partition,
partition_t* message_partition,
size_t max_message_size,
unsigned int max_messages);
Arguments:
partition_t* partition
Where to allocate the control structures partition_t* message_partition size_t max_message_size unsigned int max_messages
Where to allocate the message buffers
The maximum size of a message, in bytes
The maximum number of messages
Returns:
Errors:
Context:
The message queue identifier, or NULL on failure.
Returns NULL if there is insufficient memory for the message queue.
Callable from task only.
Description:
message_create_queue_p()
creates a message queue with buffering for a fixed number of fixed size messages. Buffer space for the messages and the message_queue_t
structure, is created automatically by the function calling memory_allocate()
on the specified memory partitions.
Note: If a null pointer is specified for
partition
or
memory_partition
, instead of a valid partition pointer, the C runtime heap is used.
See also:
memory_allocate
, message_claim, message_send, message_delete_queue
, message_receive, message_release, message_create_queue
136/226 7358306
OS21 Message handling
message_delete_queue
Delete a message queue
Definition:
#include <os21.h> int message_delete_queue(
message_queue_t* message_queue);
Arguments:
message_queue_t* message_queue
The message queue to be deleted
Returns:
Errors:
Context:
OS21_SUCCESS
or OS21_FAILURE.
Fails if message_queue is NULL.
Callable from task only.
Description:
message_delete_queue()
deletes the message queue, message_queue, and frees the memory allocated for it.
Note: The results are undefined if a task attempts to use a message queue after it has been deleted.
Tasks using
message_claim_timeout()
or
message_receive_timeout()
to wait on the message queue are protected from this possibility by a timeout period, which enables the task to continue.
See also:
message_create_queue
, message_create_queue_p, message_create_queue_timeout
message_receive
Receive the next available message from a queue
Definition:
#include <os21.h> void* message_receive(
message_queue_t* queue);
Arguments:
message_queue_t* queue
The message queue that delivers the message
Returns:
Errors:
Context:
Description:
See also:
The next available message from the queue.
None
Callable from task only.
message_receive()
receives the next available message from the message queue, and returns its address. If no messages are currently available then the task blocks until one becomes available (by another task calling message_send()).
message_claim
, message_receive_timeout, message_release, message_send
7358306 137/226
Message handling OS21
message_receive_timeout
Receive the next available message from a queue or timeout
Definition:
#include <os21.h> void* message_receive_timeout(
message_queue_t* queue
const osclock_t* time);
Arguments:
message_queue_t* queue const osclock_t* time
The message queue that delivers the message
The maximum time to wait for a message
Returns:
Errors:
Context:
The next available message from the queue, or NULL if a timeout occurs.
None
Callable from task or system context. Only valid from system context if time is
TIMEOUT_IMMEDIATE
.
Description:
message_receive_timeout()
receives the next available message from the message queue, and returns its address. If no messages are currently available then the task blocks until one becomes available (by another task calling message_send()
), or the time specified by time is reached.
Note:
time
is an absolute not a relative value, so if a relative timeout is required this needs to be made explicit, as shown in the example.
Example:
See also:
time
is specified in ticks. A tick is an implementation dependent quantity.
Two special time values may also be specified for time. TIMEOUT_IMMEDIATE causes the message queue to be polled, that is, the function always returns immediately. If a message is available then it is returned, otherwise the function returns immediately with a result of NULL. A timeout of TIMEOUT_INFINITY behaves exactly as message_receive().
This function can only be used from an interrupt handler if TIMEOUT_IMMEDIATE is specified for time.
osclock_t time; time = time_plus(time_now(), time_ticks_per_sec()); message_receive_timeout(message_queue, &time); message_claim
, message_receive, message_release, message_send
138/226 7358306
OS21 Message handling
message_release
Release a message buffer
Definition:
#include <os21.h> void message_release(
message_queue_t* queue,
void* message);
Arguments:
message_queue_t* queue
Returns:
Errors:
Context:
Description:
See also:
void* message
The message queue to which the message is released
The message buffer
None
None
Callable from task or system context.
message_release()
returns a message buffer to the message queue’s free list.
This function should be called when a message buffer (received by message_receive()
) is no longer required. If a task is waiting for a free message buffer (by calling message_claim()) this causes the task to be restarted and the message buffer returned.
message_claim
, message_receive, message_send
message_send
Send a message to a queue
Definition:
#include <os21.h> void message_send(
message_queue_t* queue,
void* message);
Arguments:
message_queue_t* queue
Returns:
Errors:
Context:
Description:
See also:
void* message
The message queue to which the message is sent
The message to send
None
None
Callable from task or system context.
message_send()
sends the specified message to the message queue. This adds the message to the end of the queue of sent messages, and if any tasks are waiting for a message they are rescheduled and the message returned.
message_claim
, message_receive, message_release
7358306 139/226
