1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.1.0 for Windows"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<TITLE>Messages: Overview</TITLE> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">Message: Overview <IMG src="../../image/NTR.gif" align="middle"><IMG src="../../image/TWL.gif" align="middle"></H1> 12<P>This page contains a description of the messaging system. This system allows you to safely synchronize between threads at the same time information is being exchanged in the message queue.</P> 13<H2>Message Queue Initialization</H2> 14<P>The message queue is initialized with <code><a href="OS_InitMessageQueue.html">OS_InitMessageQueue</a></code>.</P> 15<P>The message is an <code>OSMessage</code> type, which is defined as a <nobr><code>void*</code></nobr> type. In the TWL-SDK, there is no problem to consider it to be 32-bit data. In <nobr><code><a href="OS_InitMessageQueue.html">OS_InitMessageQueue</a></code></nobr>, there is an <code>OSMessage</code> array region that actually stores the message.</P> 16<P> The message queue is laid out internally according to the following structure:</P> 17<P><IMG src="image_messageStruct.gif" border="0"></P> 18<P>The "message array" in the figure is the <code>OSMessage</code> 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.</P> 19<P>The "number of messages" in the figure is the number of valid messages inside the message region. Immediately after initialization, this number is <code>0</code>.</P> 20<P>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.</P> 21<H2>Sending Messages</H2> 22<P><nobr><code><a href="OS_SendMessage.html">OS_SendMessage</a></code></nobr> is a function for sending messages.</P> 23<P>The figure below shows <code>thread1</code> sending a message twice.</P> 24<BLOCKQUOTE><IMG src="image_messageSend1.gif" border="0"><BR> <BR> 25</BLOCKQUOTE> 26<BLOCKQUOTE><IMG src="image_messageSend2.gif" border="0"></BLOCKQUOTE> 27<P>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.</P> 28<P>BLOCK Mode</P> 29<BLOCKQUOTE>Until the message can be sent—until other threads receive the message for this message queue with <nobr><code><a href="OS_ReceiveMessage.html">OS_ReceiveMessage</a></code></nobr> 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.</BLOCKQUOTE> 30<BLOCKQUOTE><IMG src="image_messageSend_block.gif" border="0"></BLOCKQUOTE> 31<P>NOBLOCK Mode</P> 32<BLOCKQUOTE>Returns immediately even if the message could not be sent. This mode can determine whether the message was able to be sent with the return value from the function.</BLOCKQUOTE> 33<BLOCKQUOTE><IMG src="image_messageSend_noblock.gif" border="0"></BLOCKQUOTE> 34<H2>Receiving Messages</H2> 35<P><code><a href="OS_ReceiveMessage.html">OS_ReceiveMessage</a></code> is a function for receiving messages.</P> 36<P>The figure below shows <code>thread2</code> receiving a message twice. The message reception order is same as the order sent in this message queue. </font> In other words, whatever was sent first and still remains in the message queue is what is received.</P> 37<BLOCKQUOTE><IMG src="image_messageRecv1.gif" border="0"><BR> <BR> <BR> 38</BLOCKQUOTE> 39<BLOCKQUOTE><IMG src="image_messageRecv2.gif" border="0"></BLOCKQUOTE> 40<P>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.</P> 41<P>BLOCK Mode</P> 42<BLOCKQUOTE>Until the message can be sent—until other threads receive the message for this message queue with <nobr><code><a href="OS_SendMessage.html">OS_SendMessage</a></code></nobr> 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.</BLOCKQUOTE> 43<BLOCKQUOTE><IMG src="image_messageRecv_block.gif" border="0"></BLOCKQUOTE> 44<P>NOBLOCK Mode</P> 45<BLOCKQUOTE>Returns immediately even if the message could not be received. This mode can determine whether the message was able to be received based on the return value from the function.</BLOCKQUOTE> 46<BLOCKQUOTE><IMG src="image_messageRecv_noblock.gif" border="0"></BLOCKQUOTE> 47<H2>The Rescheduling Mechanism When Sending and Receiving</H2> 48<P>In the figure below, <code>thread1</code> has attempted to send a message to the message queue in BLOCK mode, but since the message queue is full, <code>thread1</code> goes into a sleep state. Be aware that <code>thread1</code> has been registered in the send thread queue.</P> 49<BLOCKQUOTE><IMG src="image_messageSwitchThread1.gif" border="0"></BLOCKQUOTE> 50<P>In this next figure, <code>thread2</code> receives the message.</P> 51<BLOCKQUOTE><IMG src="image_messageSwitchThread2.gif" border="0"></BLOCKQUOTE> 52<P>When using <nobr><code><a href="OS_ReceiveMessage.html">OS_ReceiveMessage</a></code></nobr>, 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 <code>thread1</code> is currently registered, it is put into an executable state.</P> 53<BLOCKQUOTE> <IMG src="image_messageSwitchThread.gif" border="0"></BLOCKQUOTE> 54<P>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 <code>thread1</code> is higher than that of <code>thread2</code>, the message is sent and <code>thread1</code> goes into an executable state. </P> 55<P>Conversely, when using <nobr><code><a href="OS_SendMessage.html">OS_SendMessage</a></code></nobr>, the threads registered in the receive thread queue are all put in an executable state and re-scheduled.</P> 56<P>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.</P> 57<BLOCKQUOTE><IMG src="image_messageThreadslocked.gif" border="0"></BLOCKQUOTE> 58<H2>Send Message Interrupts</H2> 59<P>When sending a message to the message queue with <nobr><a href="OS_SendMessage.html"><code>OS_SendMessage</code></a></nobr>, it will be received in the order that it was sent when using <nobr><code><a href="OS_ReceiveMessage.html">OS_ReceiveMessage</a></code></nobr>. However, when sending <nobr><code><a href="OS_JamMessage.html">OS_JamMessage</a></code></nobr> 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.</P> 60<P>If <CODE><A href="OS_JamMessage.html">OS_JamMessage()</A></CODE> is successful, the message that was sent will become the next message recieved from this message queue.</P> 61<BLOCKQUOTE><IMG src="image_messageJam.gif" border="0"></BLOCKQUOTE> 62<H2>Message Queue Reference</H2> 63<P>To simply reference the top of the message queue (the next message to be received), <nobr><code><a href="OS_ReadMessage.html">OS_ReadMessage</a></code></nobr> allows the message to remain in the queue. The system will not switch threads as a result of this function. Neither will the internal status of the message queue change.</P> 64 65<H2>See Also</H2> 66<P><CODE><A href="../list_os.html#Message">An Overview of OS Functions ( Message )</A><BR></CODE></P> 67<H2>Revision History</H2> 68<P>2004/12/15 Corrected typos.<br />2004/11/10 Initial version.</P> 69<hr><p>CONFIDENTIAL</p></body> 70</HTML>
