Message (Overview)

Introduction

This page contains a description of the messaging system. This system allows you to safely synchronize between threads at the same time operations such as sending and receiving values in the message queue are being carried out.


Message Queue Initialization

The message queue is initialized with OS_InitMessageQueue.

The message is an OSMessage type, which is defined as a void* type. Even though it considered to be 32-bit data in the Nitro SDK, doing so will have no negative effect. In OS_InitMessageQueue, there is an OSMessage array region that actually stores the message.

The message queue is laid out internally according to the following structure:

The "message array" in the figure is the OSMessage array and is the message region. The user specifies this size during initialization. This region is used as the FIFO queue. Internally, it is actually the ring buffer, and there are variables that exist to control it. However, the explanation on this page has been left out.

The "number of messages" in the figure is the number of valid messages inside the message region. Immediately after initialization, this number is 0.

The "thread queue to send messages" and "thread queue to receive messages" are the thread queues used to send and receive messages. These queues are explained later.


Sending Messages

OS_SendMessage is a function for sending messages.

The figure below shows thread1 sending a message twice.



When sending, designate either BLOCK mode or NOBLOCK mode. They work the same as long as the message queue is not full. As shown in the figure above, the message is only registered in the queue. However, their behavior is different when trying to send the message to a message queue that is already full.

BLOCK Mode

Until the message can be sent—until other threads receive the message for this message queue with OS_ReceiveMessage and the message queue is emptied, the thread pauses and waits. At that time, a thread rescheduling must take place, and another thread must enter the executable state.

NOBLOCK Mode

Returns immediately even if the message could not be sent. This mode can determine whether or not the message was able to be sent with the return value from the function.

Receiving Messages

OS_ReceiveMessage is a function for receiving messages.

The figure below shows thread2 receiving a message twice. The message reception order is same as the order sent in this message queue. In other words, whatever was sent first and still remains in the message queue is what is received.




When receiving, designate either BLOCK mode or NOBLOCK mode. They work the same as long as the message queue is not full. As shown in the figure above, the message is only loaded from the queue. However, their behavior is different when trying to receive the message from a message queue that is empty.

BLOCK Mode

Until the message can be sent—until other threads receive the message for this message queue with OS_SendMessage and the message queue is emptied, the thread thread pauses and waits. At that time, a thread rescheduling must take place, and another thread must enter the executable state.

NOBLOCK Mode

Returns immediately even if the message could not be received. This mode can determine whether or not the message was able to be received based on the return value from the function.

The Rescheduling Mechanism when Sending and Receiving

In the figure below, thread1 has attempted to send a message to the message queue in BLOCK mode, but since the message queue is full, thread1 goes into a sleep state. Be aware that thread1 has been registered in the send thread queue.

In this next figure, thread2 receives the message.

When using OS_ReceiveMessage, the message queue checks to see if the thread has been registered in the send thread queue. If there are registered threads, they are all put into an executable state. Since thread1 is currently registered, it is put into an executable state.

Thread rescheduling is carried out in this state. The thread with the highest priority, between the current thread (the thread attempting to receive the message) and the thread that is executable, is put into an executable state. In the next figure, if the priority of thread1 is higher than that of thread2, the message is sent and thread1 goes into an executable state.

Conversely, when using OS_SendMessage, the threads registered in the receive thread queue are all put in an executable state and re-scheduled.

There are times when multiple threads have been registered in the message queue. In this case as well, use the thread queue mechanism to put the registered threads into an executable state and to re-schedule them all at once.


Send Message Interrupts

When sending a message to the message queue with OS_SendMessage, it will be received in the order that it was sent when using OS_ReceiveMessage. However, when sending OS_JamMessage interrupts the process at the top of the message queue. The mode for when the queue is full can also be designated with this function.

If OS_JamMessage is successful, that message is received next in this message queue.


Message Queue Reference

To simply reference the top of the message queue (the next message to be received), OS_ReadMessage allows the message to remain in the queue. There is no thread switching caused by this function, and the internal state of the message queue does not change.

See Also

An Overview of OS Functions ( Message )

Revision History

12/15/2004 Corrected typos
11/10/2004 Initial version