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 gu_queue_create 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:
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 gu_queue_subscribe 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:
Name Description 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.
Printing formatted messages to a Message queue resource #
A producer task sends formatted messages with the following function:
int gu_queue_printf(G_RCB *prcb, char *format, ...);The gu_queue_printf function serves to print a message to a message queue resource. This function operates in a manner where it will return once the message has been successfully delivered to all subscribed consumers or when a timeout occurs. During this period, the task invoking the gu_queue_printf function remains suspended. The primary purpose of this function is to transmit a formatted message to the designated queue resource, facilitating communication within a GeMRTOS-based system.
gu_queue_printf
A message is printed with the following parameters:
Name Description 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. It serves as a reference to the specific message queue where the formatted message will be sent using gu_queue_printf. format It is the formatted message to be sent. The valid format of this message is similar to the original printf function, allowing it to contain embedded format tags. These format tags are replaced by the values specified in subsequent additional arguments and formatted as specified. This allows for flexible and customized message formatting within the gu_queue_printf function, akin to how the printf function operates.
Sending messages to a Message queue resource #
A producer task sends messages with the following function:
int gu_queue_send(G_RCB *prcb, char *pmsg, int 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.
gu_queue_send
A message is sent with the following parameters:
Name Description 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.
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, G_INT32 buffer_length);The gu_queue_receive 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:
Name Description 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.
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 #
| Type | Field | Description |
|---|---|---|
G_INT32 | MQ_priority_send | Priority for the next ECB to send (to put last) |
G_INT32 | MQ_msg_seq | Number of sequence of the current message
|
