<p>Synchronous inter-thread messages APIs and services. </p>
<h2>Operation Mode</h2>
<p>Synchronous messages are an easy to use and fast IPC mechanism, threads can both act as message servers and/or message clients, the mechanism allows data to be carried in both directions. Note that messages are not copied between the client and server threads but just a pointer passed so the exchange is very time efficient.<br/>
Messages are usually processed in FIFO order but it is possible to process them in priority order by enabling the <code>CH_USE_MESSAGES_PRIORITY</code> option in <code><aclass="el"href="chconf_8h.html"title="Configuration file template.">chconf.h</a></code>.<br/>
Applications do not need to allocate buffers for synchronous message queues, the mechanism just requires two extra pointers in the <code><aclass="el"href="struct_thread.html"title="Structure representing a thread.">Thread</a></code> structure (the message queue header).<br/>
In order to use the Messages APIs the <code>CH_USE_MESSAGES</code> option must be enabled in <code><aclass="el"href="chconf_8h.html"title="Configuration file template.">chconf.h</a></code>. </p>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Evaluates to TRUE if the thread has pending messages. <ahref="#ga4e0eafdfd51c042d765e2949e6171093"></a><br/></td></tr>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the first message in the queue. <ahref="#ga3ed579be01280d265d0a7c02e0c7c1d8"></a><br/></td></tr>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Sends a message to the specified thread. <ahref="#ga29a48a438e97dc47cb798a84e13764cb"></a><br/></td></tr>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Suspends the thread and waits for an incoming message. <ahref="#gae68fefbf9d0404bbf56ae354961fae41"></a><br/></td></tr>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the next message in the queue. <ahref="#ga65dda189b03b238412301ce5d80bfcf4"></a><br/></td></tr>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Releases the thread waiting on top of the messages queue. <ahref="#ga19a54b3b4b0e3677c47d650a3be3c7aa"></a><br/></td></tr>
<p>Evaluates to TRUE if the thread has pending messages. </p>
<p>Definition at line <aclass="el"href="chmsg_8h_source.html#l00043">43</a> of file <aclass="el"href="chmsg_8h_source.html">chmsg.h</a>.</p>
<p>Referenced by <aclass="el"href="group__messages.html#ga65dda189b03b238412301ce5d80bfcf4">chMsgGet()</a>, <aclass="el"href="group__messages.html#ga19a54b3b4b0e3677c47d650a3be3c7aa">chMsgRelease()</a>, <aclass="el"href="group__messages.html#gae68fefbf9d0404bbf56ae354961fae41">chMsgWait()</a>, and <aclass="el"href="classchibios__rt_1_1_base_thread.html#a4477cb3ed6fc3250638bb21d8199f573">chibios_rt::BaseThread::IsPendingMessage()</a>.</p>
<p>Definition at line <aclass="el"href="chmsg_8h_source.html#l00049">49</a> of file <aclass="el"href="chmsg_8h_source.html">chmsg.h</a>.</p>
<p>Referenced by <aclass="el"href="group__messages.html#ga65dda189b03b238412301ce5d80bfcf4">chMsgGet()</a>, and <aclass="el"href="group__messages.html#gae68fefbf9d0404bbf56ae354961fae41">chMsgWait()</a>.</p>
<p>The sender is stopped until the receiver executes a <code><aclass="el"href="group__messages.html#ga19a54b3b4b0e3677c47d650a3be3c7aa"title="Releases the thread waiting on top of the messages queue.">chMsgRelease()</a>after</code> receiving the message.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<tableborder="0"cellspacing="2"cellpadding="0">
<tr><tdvalign="top"><tt>[in]</tt> </td><tdvalign="top"><em>tp</em> </td><td>the pointer to the thread </td></tr>
<dlclass="return"><dt><b>Returns:</b></dt><dd>The answer message from <code><aclass="el"href="group__messages.html#ga19a54b3b4b0e3677c47d650a3be3c7aa"title="Releases the thread waiting on top of the messages queue.">chMsgRelease()</a></code>. </dd></dl>
<p>Definition at line <aclass="el"href="chmsg_8c_source.html#l00070">70</a> of file <aclass="el"href="chmsg_8c_source.html">chmsg.c</a>.</p>
<p>Referenced by <aclass="el"href="classchibios__rt_1_1_base_thread.html#a1557c9e6e0b61a7eb848ce928115973d">chibios_rt::BaseThread::SendMessage()</a>.</p>
<areashape="rect"id="node3"href="group__scheduler.html#ga97c1c514b755a1e71caf2f19c1ccf986"title="Puts the current thread to sleep into the specified state."alt=""coords="133,31,235,57"/><areashape="rect"id="node9"href="group__scheduler.html#ga535d58cfb3436c8d4e4586c31c062298"title="Inserts a thread in the Ready List."alt=""coords="141,81,227,108"/><areashape="rect"id="node5"href="group__debug.html#gac7f8f0653faf2e3a93108ff5333821b7"title="Inserts in the circular debug trace buffer a context switch record."alt=""coords="284,5,364,32"/><areashape="rect"id="node7"href="group__internals.html#ga042479f09357fc59befebf4dfe0e9f4a"title="Removes the first-out Thread from a queue and returns it."alt=""coords="284,56,364,83"/></map>
<p>Suspends the thread and waits for an incoming message. </p>
<dlclass="note"><dt><b>Note:</b></dt><dd>You can assume that the data contained in the message is stable until you invoke <code><aclass="el"href="group__messages.html#ga19a54b3b4b0e3677c47d650a3be3c7aa"title="Releases the thread waiting on top of the messages queue.">chMsgRelease()</a></code> because the sending thread is suspended until then.</dd></dl>
<dlclass="return"><dt><b>Returns:</b></dt><dd>The pointer to the message structure. Note, it is always the message associated to the thread on the top of the messages queue. </dd></dl>
<p>Definition at line <aclass="el"href="chmsg_8c_source.html#l00097">97</a> of file <aclass="el"href="chmsg_8c_source.html">chmsg.c</a>.</p>
<p>References <aclass="el"href="group__messages.html#ga3ed579be01280d265d0a7c02e0c7c1d8">chMsgGetI</a>, <aclass="el"href="group__messages.html#ga4e0eafdfd51c042d765e2949e6171093">chMsgIsPendingI</a>, <aclass="el"href="group__scheduler.html#ga97c1c514b755a1e71caf2f19c1ccf986">chSchGoSleepS()</a>, <aclass="el"href="group__system.html#ga9f6573c0763d1e4e97c63c62edad6e42">chSysLock</a>, <aclass="el"href="group__system.html#ga5a257fa58a09815eb64a45e2dfbdc22e">chSysUnlock</a>, <aclass="el"href="group__scheduler.html#ga1a5fddde56420e8accd0c09c1abb32a7">currp</a>, and <aclass="el"href="group__threads.html#gaf46c55b4468f0dad5cd0b3ef73e1be26">THD_STATE_WTMSG</a>.</p>
<p>Referenced by <aclass="el"href="classchibios__rt_1_1_base_thread.html#ae960dbec72042a9072e35984523694b8">chibios_rt::BaseThread::WaitMessage()</a>.</p>
<areashape="rect"id="node3"href="group__scheduler.html#ga97c1c514b755a1e71caf2f19c1ccf986"title="Puts the current thread to sleep into the specified state."alt=""coords="128,31,229,57"/><areashape="rect"id="node5"href="group__debug.html#gac7f8f0653faf2e3a93108ff5333821b7"title="Inserts in the circular debug trace buffer a context switch record."alt=""coords="279,5,359,32"/><areashape="rect"id="node7"href="group__internals.html#ga042479f09357fc59befebf4dfe0e9f4a"title="Removes the first-out Thread from a queue and returns it."alt=""coords="279,56,359,83"/></map>
<dlclass="note"><dt><b>Note:</b></dt><dd>You can assume that the data pointed by the message is stable until you invoke <code><aclass="el"href="group__messages.html#ga19a54b3b4b0e3677c47d650a3be3c7aa"title="Releases the thread waiting on top of the messages queue.">chMsgRelease()</a></code> because the sending thread is suspended until then. Always remember that the message data is not copied between the sender and the receiver, just a pointer is passed.</dd></dl>
<dlclass="return"><dt><b>Returns:</b></dt><dd>The pointer to the message structure. Note, it is always the message associated to the thread on the top of the messages queue. </dd></dl>
<dl><dt><b>Return values:</b></dt><dd>
<tableborder="0"cellspacing="2"cellpadding="0">
<tr><tdvalign="top"></td><tdvalign="top"><em>NULL</em> </td><td>if the queue is empty. </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <aclass="el"href="chmsg_8c_source.html#l00125">125</a> of file <aclass="el"href="chmsg_8c_source.html">chmsg.c</a>.</p>
<p>References <aclass="el"href="group__messages.html#ga3ed579be01280d265d0a7c02e0c7c1d8">chMsgGetI</a>, <aclass="el"href="group__messages.html#ga4e0eafdfd51c042d765e2949e6171093">chMsgIsPendingI</a>, <aclass="el"href="group__system.html#ga9f6573c0763d1e4e97c63c62edad6e42">chSysLock</a>, <aclass="el"href="group__system.html#ga5a257fa58a09815eb64a45e2dfbdc22e">chSysUnlock</a>, and <aclass="el"href="group__scheduler.html#ga1a5fddde56420e8accd0c09c1abb32a7">currp</a>.</p>
<p>Referenced by <aclass="el"href="classchibios__rt_1_1_base_thread.html#ab8e737914200f075bf02ade85876764d">chibios_rt::BaseThread::GetMessage()</a>.</p>
<p>Releases the thread waiting on top of the messages queue. </p>
<dlclass="note"><dt><b>Note:</b></dt><dd>You can call this function only if there is a message already in the queue else the result will be unpredictable (a crash most likely). Exiting from the <code><aclass="el"href="group__messages.html#gae68fefbf9d0404bbf56ae354961fae41"title="Suspends the thread and waits for an incoming message.">chMsgWait()</a></code> ensures you have at least one message in the queue so it is not a big deal.<br/>
The condition is only tested in debug mode in order to make this code as fast as possible.</dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<tableborder="0"cellspacing="2"cellpadding="0">
<tr><tdvalign="top"><tt>[in]</tt> </td><tdvalign="top"><em>msg</em> </td><td>the message returned to the message sender </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <aclass="el"href="chmsg_8c_source.html#l00145">145</a> of file <aclass="el"href="chmsg_8c_source.html">chmsg.c</a>.</p>
<p>References <aclass="el"href="group__debug.html#ga43d50c69eb730d0f024eb832d61f30c9">chDbgAssert</a>, <aclass="el"href="group__messages.html#ga4e0eafdfd51c042d765e2949e6171093">chMsgIsPendingI</a>, <aclass="el"href="group__scheduler.html#gae47a8819a21ef2d521124e76bfb37c95">chSchWakeupS()</a>, <aclass="el"href="group__system.html#ga9f6573c0763d1e4e97c63c62edad6e42">chSysLock</a>, <aclass="el"href="group__system.html#ga5a257fa58a09815eb64a45e2dfbdc22e">chSysUnlock</a>, <aclass="el"href="group__scheduler.html#ga1a5fddde56420e8accd0c09c1abb32a7">currp</a>, and <aclass="el"href="group__internals.html#ga042479f09357fc59befebf4dfe0e9f4a">fifo_remove()</a>.</p>
<p>Referenced by <aclass="el"href="classchibios__rt_1_1_base_thread.html#a4ecedb2d2b646ea4a9261c0e62f16945">chibios_rt::BaseThread::ReleaseMessage()</a>.</p>
<areashape="rect"id="node3"href="group__scheduler.html#gae47a8819a21ef2d521124e76bfb37c95"title="Wakes up a thread."alt=""coords="147,31,245,57"/><areashape="rect"id="node9"href="group__internals.html#ga042479f09357fc59befebf4dfe0e9f4a"title="Removes the first-out Thread from a queue and returns it."alt=""coords="156,81,236,108"/><areashape="rect"id="node5"href="group__debug.html#gac7f8f0653faf2e3a93108ff5333821b7"title="Inserts in the circular debug trace buffer a context switch record."alt=""coords="297,5,377,32"/><areashape="rect"id="node7"href="group__scheduler.html#ga535d58cfb3436c8d4e4586c31c062298"title="Inserts a thread in the Ready List."alt=""coords="295,56,380,83"/></map>
Generated on Sun Oct 24 2010 09:40:46 for ChibiOS/RT by <ahref="http://www.doxygen.org/index.html"><imgsrc="doxygen.png"alt="doxygen"align="middle"border="0"></a> 1.7.1</small></address>