<divclass="title">Mail Queue<divclass="ingroups"><aclass="el"href="group__CMSIS__RTOS__InterThread.html">Inter-Thread Communication and Resource Sharing</a></div></div></div>
<trclass="memdesc:ga58d712b16c0c6668059f509386d1e55b"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Create a Mail Queue Definition. <ahref="#ga58d712b16c0c6668059f509386d1e55b">More...</a><br/></td></tr>
<trclass="memdesc:gad2deeb66d51ade54e63d8f87ff2ec9d2"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Access a Mail Queue Definition. <ahref="#gad2deeb66d51ade54e63d8f87ff2ec9d2">More...</a><br/></td></tr>
<trclass="memdesc:gaa177e7fe5820dd70d8c9e46ded131174"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Create and Initialize mail queue. <ahref="#gaa177e7fe5820dd70d8c9e46ded131174">More...</a><br/></td></tr>
<trclass="memdesc:gadf5ce811bd6a56e617e902a1db6c2194"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Allocate a memory block from a mail. <ahref="#gadf5ce811bd6a56e617e902a1db6c2194">More...</a><br/></td></tr>
<trclass="memdesc:ga8fde74f6fe5b9e88f75cc5eb8f2124fd"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Allocate a memory block from a mail and set memory block to zero. <ahref="#ga8fde74f6fe5b9e88f75cc5eb8f2124fd">More...</a><br/></td></tr>
<trclass="memdesc:ga485ef6f81854ebda8ffbce4832181e02"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Put a mail to a queue. <ahref="#ga485ef6f81854ebda8ffbce4832181e02">More...</a><br/></td></tr>
<trclass="memdesc:gac6ad7e6e7d6c4a80e60da22c57a42ccd"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Get a mail from a queue. <ahref="#gac6ad7e6e7d6c4a80e60da22c57a42ccd">More...</a><br/></td></tr>
<trclass="memdesc:ga27c1060cf21393f96b4fd1ed1c0167cc"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Free a memory block from a mail. <ahref="#ga27c1060cf21393f96b4fd1ed1c0167cc">More...</a><br/></td></tr>
<p>A <b>mail</b><b>queue</b> resembles a <aclass="el"href="group__CMSIS__RTOS__Message.html">Message Queue</a>, but the data that is being transferred consists of memory blocks that need to be allocated (before putting data in) and freed (after taking data out). The mail queue uses a <aclass="el"href="group__CMSIS__RTOS__PoolMgmt.html">Memory Pool</a> to create formatted memory blocks and passes pointers to these blocks in a message queue. This allows the data to stay in an allocated memory block while only a pointer is moved between the separate threads. This is an advantage over <aclass="el"href="group__CMSIS__RTOS__Message.html">messages</a> that can transfer only a 32-bit value or a pointer. Using the mail queue functions, you can control, send, receive, or wait for mail.</p>
<p>Follow these steps to create and use a mail queue:</p>
<oltype="1">
<li>Declare a data structure that combines a number of elements: <divclass="fragment"><divclass="line"><spanclass="keyword">typedef</span><spanclass="keyword">struct </span>{</div>
<li>Declare a mail queue made up of these objects: <divclass="fragment"><divclass="line"><aclass="code"href="group__CMSIS__RTOS__Mail.html#ga58d712b16c0c6668059f509386d1e55b">osMailQDef</a> (object_pool_q, 10, properties_t); <spanclass="comment">// Declare mail queue</span></div>
<divclass="line"><aclass="code"href="cmsis__os_8h.html#a1dac049fb7725a8af8b26c71cbb373b5">osMailQId</a> (object_pool_q_id); <spanclass="comment">// Mail queue ID</span></div>
<li>Then, create the mail pool in a thread: <divclass="fragment"><divclass="line">object_pool_q_id = <aclass="code"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>(<aclass="code"href="group__CMSIS__RTOS__Mail.html#gad2deeb66d51ade54e63d8f87ff2ec9d2">osMailQ</a>(object_pool_q), NULL);</div>
<li>Pass the pointer to the mail queue to another thread: <divclass="fragment"><divclass="line"><aclass="code"href="group__CMSIS__RTOS__Mail.html#ga485ef6f81854ebda8ffbce4832181e02">osMailPut</a>(object_pool_q_id, object_data);</div>
<li>Access the data in another thread: <divclass="fragment"><divclass="line"><aclass="code"href="group__CMSIS__RTOS__Definitions.html#structosEvent">osEvent</a><spanclass="keyword">event</span> = <aclass="code"href="group__CMSIS__RTOS__Mail.html#gac6ad7e6e7d6c4a80e60da22c57a42ccd">osMailGet</a>(properties_q_id, <aclass="code"href="cmsis__os_8h.html#a9eb9a7a797a42e4b55eb171ecc609ddb">osWaitForever</a>);</div>
<divclass="line">properties_t *received = (properties_t *)event.value.p; <spanclass="comment">// ".p" indicates that the message is a pointer</span></div>
<li>Once the data has been used, the memory block must be freed so that the memory pool can be reused <divclass="fragment"><divclass="line"><aclass="code"href="group__CMSIS__RTOS__Mail.html#ga27c1060cf21393f96b4fd1ed1c0167cc">osMailFree</a>(object_pool_q_id, received);</div>
<li>When <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaceb2e0071ce160d153047f2eac1aca8e">osFeature_MailQ</a> is 1 mail queues are supported.</li>
<li>When <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaceb2e0071ce160d153047f2eac1aca8e">osFeature_MailQ</a> is 0 no mail queues are supported.</li>
<p>Access to the mail queue definition for the function <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>.</p>
<tr><tdclass="paramname">name</td><td>name of the queue </td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>CAN BE CHANGED: The parameter to <b>osMailQ</b> shall be consistent but the macro body is implementation specific in every CMSIS-RTOS. </dd></dl>
<p>Define the attributes of a mail queue that can by the function <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a> using <aclass="el"href="group__CMSIS__RTOS__Mail.html#gad2deeb66d51ade54e63d8f87ff2ec9d2">osMailQ</a>.</p>
<dlclass="section note"><dt>Note</dt><dd>The parameter <em>thread</em> registers the receiving thread for a mail and is needed for the general <aclass="el"href="technicalData.html#osWait">osWait</a> function to deliver the mail.</dd></dl>
<tr><tdclass="paramname">name</td><td>name of the queue </td></tr>
<tr><tdclass="paramname">queue_sz</td><td>maximum number of messages in queue </td></tr>
<tr><tdclass="paramname">type</td><td>data type of a single message element </td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>CAN BE CHANGED: The parameter to <b>osMailQDef</b> shall be consistent but the macro body is implementation specific in every CMSIS-RTOS. </dd></dl>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">queue_id</td><td>mail queue ID obtained with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>. </td></tr>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">millisec</td><td><aclass="el"href="functionOverview.html#CMSIS_RTOS_TimeOutValue">Timout Value</a> or 0 in case of no time-out </td></tr>
<p>The argument <em>queue_id</em> specifies a mail queue identifier that is obtain with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>.</p>
<p>The argument <em>millisec</em> specifies how long the system waits for a mail slot to become available. While the system waits the thread calling this function is put into the state <b>WAITING</b>. The <em>millisec</em> timeout can have the following values:</p>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">queue_id</td><td>mail queue ID obtained with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>. </td></tr>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">millisec</td><td><aclass="el"href="functionOverview.html#CMSIS_RTOS_TimeOutValue">Timout Value</a> or 0 in case of no time-out </td></tr>
<p>The argument <em>queue_id</em> specifies a mail queue identifier that is obtain with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>.</p>
<p>The argument <em>millisec</em> specifies how long the system waits for a mail slot to become available. While the system waits the thread that is calling this function is put into the state <b>WAITING</b>. The <em>millisec</em> timeout can have the following values:</p>
<ul>
<li>when <em>millisec</em> is 0, the function returns instantly.</li>
<li>when <em>millisec</em> is set to <b>osWaitForever</b> the function will wait for an infinite time until a mail slot can be allocated.</li>
<li>all other values specify a time in millisecond for a timeout.</li>
</ul>
<dlclass="section note"><dt>Note</dt><dd>The parameter <em>millisec</em> must be 0 for using this function in an ISR. </dd>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">queue_def</td><td>reference to the mail queue definition obtain with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gad2deeb66d51ade54e63d8f87ff2ec9d2">osMailQ</a></td></tr>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">thread_id</td><td>thread ID (obtained by <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gac59b5713cb083702dce759c73fd90dff">osThreadCreate</a> or <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gab1df2a28925862ef8f9cf4e1c995c5a7">osThreadGetId</a>) or NULL. </td></tr>
<dlclass="section note"><dt>Note</dt><dd>Cannot be called from <aclass="el"href="functionOverview.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a>.</dd></dl>
<divclass="line"><aclass="code"href="cmsis__os_8h.html#adfeb153a84a81309e2d958268197617f">osThreadId</a> tid_thread1; <spanclass="comment">// ID for thread 1</span></div>
<divclass="line"><aclass="code"href="cmsis__os_8h.html#adfeb153a84a81309e2d958268197617f">osThreadId</a> tid_thread2; <spanclass="comment">// ID for thread 2</span></div>
<divclass="line"> mail = <aclass="code"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>(<aclass="code"href="group__CMSIS__RTOS__Mail.html#gad2deeb66d51ade54e63d8f87ff2ec9d2">osMailQ</a>(mail), NULL); <spanclass="comment">// create mail queue</span></div>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">queue_id</td><td>mail queue ID obtained with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>. </td></tr>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">mail</td><td>pointer to the memory block that was obtained with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gac6ad7e6e7d6c4a80e60da22c57a42ccd">osMailGet</a>. </td></tr>
<dlclass="section note"><dt>Note</dt><dd><aclass="el"href="functionOverview.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a> can call this function.</dd></dl>
<p><b><aclass="el"href="group__CMSIS__RTOS__Status.html">Status and Error Codes</a></b><br/>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">queue_id</td><td>mail queue ID obtained with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>. </td></tr>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">millisec</td><td><aclass="el"href="functionOverview.html#CMSIS_RTOS_TimeOutValue">Timout Value</a> or 0 in case of no time-out </td></tr>
<dlclass="section return"><dt>Returns</dt><dd>event that contains mail information or error code. </dd></dl>
<dlclass="section note"><dt>Note</dt><dd>MUST REMAIN UNCHANGED: <b>osMailGet</b> shall be consistent in every CMSIS-RTOS.</dd></dl>
<p>Suspend the execution of the current <b>RUNNING</b> thread until a mail arrives. When a mail is already in the queue, the function returns instantly with the mail information.</p>
<p>The argument <em>millisec</em> specifies how long the system waits for a mail to arrive. While the system waits the thread that is calling this function is put into the state <b>WAITING</b>. The <em>millisec</em> timeout can have the following values:</p>
<ul>
<li>when <em>millisec</em> is 0, the function returns instantly.</li>
<li>when <em>millisec</em> is set to <b>osWaitForever</b> the function will wait for an infinite time until a mail arrives.</li>
<li>all other values specify a time in millisecond for a timeout.</li>
</ul>
<dlclass="section note"><dt>Note</dt><dd>The parameter <em>millisec</em> must be 0 for using this function in an ISR. </dd>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">queue_id</td><td>mail queue ID obtained with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gaa177e7fe5820dd70d8c9e46ded131174">osMailCreate</a>. </td></tr>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">mail</td><td>memory block previously allocated with <aclass="el"href="group__CMSIS__RTOS__Mail.html#gadf5ce811bd6a56e617e902a1db6c2194">osMailAlloc</a> or <aclass="el"href="group__CMSIS__RTOS__Mail.html#ga8fde74f6fe5b9e88f75cc5eb8f2124fd">osMailCAlloc</a>. </td></tr>
<dlclass="section note"><dt>Note</dt><dd><aclass="el"href="functionOverview.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a> can call this function. </dd></dl>
