Message queues in GeMRTOS #
The message queue is a resource that enables independent tasks to exchange information. Information is sent using messages by a task (denoted producer) to the message queue. A message remains associated with the message queue resources until (1) all the tasks associated with the message queue read it (aka consume it), or (2) a timeout expires. The producer task remain suspended until the message was consumed by all the consumers or the timeout of the message expires. The tasks that want to receive the messages sent to the message queue, have to subscribe to the message queue.
If a consumer task already received all the messages sent, then it remains suspended waiting until the next message.
Message queue related functions #
Creating and initializing a Message queue #
The first step is to create a message queue resource using:
G_RCB * gu_queue_create (void )The gu_queue_create function creates a new message queue resource. The message queue resource is built using the G_RCB structure with some fields from the T_QUEUE_RESOURCE structure appended. A producer (associated with the waiting eevnt list) and a consumer (associated with the granted event list) event lists will be included in the newly constructed message queue resource. Producer tasks link a waiting event in the producer list of the message queue resource. The can be called from either the main code or a task code. However, when it is executed within a task code, it must come before the execution of a send or a receive message function, or an error will be produced.
The message queue is created and initilized with the following paramenters:
None- Returns
- The gu_queue_create function returns a pointer to the message queue resource created, or 0 if there is not more resources available. It should be used in all the functions related to the message queue resource created. The function returns a NULL pointer if there is not enough memory to implement the message queue resource.
Subscribing to a Message queue resource #
A consumer task should be subscribed to a message resource prior to receiving messages with the following function:
GS_ECB * gu_queue_subscribe (GS_TCB * ptcb, G_RCB * presource )The function subscribes the current executing task to the message queue resource specified. A consumer tasks should be previously subscribe to the message queue resource in order to be able to receive messages with the gu_queue_receive function. The Message Queue should be created with gu_queue_create.
A message queue is subscribed with the following parameters:
ptcb It is a pointer to the task's TCB to be subscribe to the queue presource It is a pointer to the message queue resource to be subscribe to.
- Returns
- The gu_queue_subscribe function returns a pointer to the GS_ECB structure associated with the message queue resource.
Sending messages to a Message queue resource #
A producer task sends messages with the following function:
INT32 gu_queue_send (G_RCB * prcb, void * pmsg, INT32 msg_length, gt_time timeout )The gu_queue_send function sends a message to a message queue resource. The function returns when the message was delivered to all the consumer subscribed or the timeout, meanwhile the task remains suspended.
A message is sent with the following parameters:
[in] prcb It is the pointer to the message queue resource. The pointer is the value returned by the gu_queue_create function when the message queue resource was created. pmsg It is the pointer to the message to be sent. msg_length It is the lenght of the message to be sent. timeout It is the timeout to send the message.
- Returns
- G_TRUE when successful, G_FALSE otherwise
Receiving messages from a Message queue resource #
A consumer task receives messages from a previously subscribed message queue resource with the following function:
int gu_queue_receive (G_RCB * prcb, void * buffer_msg, unsigned int buffer_length )The function receives the next message from the message queue resource. The task should be subscribed previously with the gu_queue_subscribe function. The new message is stored into the buffer pointed by the buffer_msg parameter. Up to buffer_length bytes are copied from the message sent. When the sent message is larger than the consumer buffer, then the message recieved is truncated in the buffer_length size.
A message is sent with the following parameters:
prcb It is the pointer to the message queue resource already subscribed to. buffer_msg It is the pointer to the message buffer where the message received will be store into. buffer_length The maximum number of bytes to be received. It should be the length of the receiving buffer.
- Returns
- The gu_queue_receive function returns the number of bytes received.
Message queue resource related structure #
T_QUEUE_RESOURCE #
The T_QUEUE_RESOURCE is defined as the field "queue" in a G_RCB resource. So, the fields of the T_QUEUE_RESOURCE structure should be addressed as: (G_RCB *)->queue.<field>
Structure fields #
| INT32 | MQ_priority_send |
| Priority for the next ECB to send (to put last) | |
| INT32 | MQ_msg_seq |
| Number of sequence of the current message | |
