group__mailbox.html

yavrtos,一款用于广泛用于AVR单片机的RTOS,文件里是这款OS的源码

          <td>)</td>
          <td></td><td></td><td width="100%"></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Wait for a mailbox to reach at least a certain version, and then start reading from it. 
<p>
<dl class="attention" compact><dt><b>Attention:</b></dt><dd>It is <b>vital</b> that <a class="el" href="group__mailbox.html#g31b8ee5f4cd547c128143d99ea1c4a96" title="Function to call when finished reading from a mailbox.">release_mbox_read()</a> be called to release the mailbox for other tasks to write to it when the calling task has finished reading the mailbox data</dd></dl>
The arguments are <ul>
<li><code>mbox</code> - the mailbox to read from </li>
<li><code>version</code> - the minimum version of the mailbox that we require. Note that the version of the mailbox actually read will be written to this address</li>
</ul>
The return value is a pointer to the mailbox data. Note that a zero return value does not mean that the mailbox read failed - it means that the mailbox was empty - and hence <a class="el" href="group__mailbox.html#g31b8ee5f4cd547c128143d99ea1c4a96" title="Function to call when finished reading from a mailbox.">release_mbox_read()</a> must still be called.<p>
Since this function can cause a suspension (i.e. if the mailbox hasn't reached the specified version), it can only be called from a task with a non-zero priority 
</div>
</div><p>
<a class="anchor" name="g31b8ee5f4cd547c128143d99ea1c4a96"></a><!-- doxytag: member="task.h::release_mbox_read" ref="g31b8ee5f4cd547c128143d99ea1c4a96" args="()" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="structmailbox__t.html">mailbox_t</a>* release_mbox_read           </td>
          <td>(</td>
          <td class="paramname">          </td>
          <td>&nbsp;)&nbsp;</td>
          <td width="100%"></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Function to call when finished reading from a mailbox. 
<p>
Since tasks are not allowed to write to a mailbox while there are other tasks reading from it, this function <b>must</b> be called when a task has finished reading from a mailbox - i.e. it must be called after every call to <a class="el" href="group__mailbox.html#g86030bb5345670ca374ddd20ef8e4ff6" title="Read a mailbox.">read_mbox()</a> or <a class="el" href="group__mailbox.html#g5dbb6937f6f93f6a1c14dec5b1c197c3" title="Wait for a mailbox to reach at least a certain version, and then start reading from...">read_mbox_min_version()</a><p>
Since a task can only read one mailbox at a time, there are no arguments to this function. The return value is the mailbox that the task was reading from, or zero if it was not reading from any mailbox.<p>
Note that calling this function may cause a higher-prioroty task that is waiting to write to the mailbox to be scheduled. 
</div>
</div><p>
<a class="anchor" name="gf670250659f0942849aa85f0f94af9f0"></a><!-- doxytag: member="task.h::wait_for_receiver" ref="gf670250659f0942849aa85f0f94af9f0" args="(mailbox_t *mbox)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void wait_for_receiver           </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="structmailbox__t.html">mailbox_t</a> *&nbsp;</td>
          <td class="paramname"> <em>mbox</em>          </td>
          <td>&nbsp;)&nbsp;</td>
          <td width="100%"></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Wait for a task to be suspended while trying to read from a mailbox. 
<p>
This function will suspend the caller until another task is suspended while calling <a class="el" href="group__mailbox.html#g5dbb6937f6f93f6a1c14dec5b1c197c3" title="Wait for a mailbox to reach at least a certain version, and then start reading from...">read_mbox_min_version()</a>. This could be used to give a task that needs to read the mailbox a chance to initialise. 
</div>
</div><p>
<a class="anchor" name="gc75646248d03b1413198765b07ba54ad"></a><!-- doxytag: member="task.h::write_mbox" ref="gc75646248d03b1413198765b07ba54ad" args="(mailbox_t *mbox, void *data, uint8_t wait_for_receivers, uint8_t wait_for_empty_nullify)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void write_mbox           </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="structmailbox__t.html">mailbox_t</a> *&nbsp;</td>
          <td class="paramname"> <em>mbox</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void *&nbsp;</td>
          <td class="paramname"> <em>data</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">uint8_t&nbsp;</td>
          <td class="paramname"> <em>wait_for_receivers</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">uint8_t&nbsp;</td>
          <td class="paramname"> <em>wait_for_empty_nullify</em></td><td>&nbsp;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td><td width="100%"></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Write to a mailbox. 
<p>
A write to a mailbox will <ul>
<li>wait for all tasks that are reading the mailbox to call <a class="el" href="group__mailbox.html#g31b8ee5f4cd547c128143d99ea1c4a96" title="Function to call when finished reading from a mailbox.">release_mbox_read()</a> </li>
<li>if <code>wait_for_receivers</code> is not zero, it will wait until there are at least that many tasks that have suspended themselves on <a class="el" href="group__mailbox.html#g5dbb6937f6f93f6a1c14dec5b1c197c3" title="Wait for a mailbox to reach at least a certain version, and then start reading from...">read_mbox_min_version()</a> while waiting for fresh data to be put into this mailbox. Otherwise, the data that is put into the mailbox might end up not being picked up by any task (e.g. if another write is made to the mailbox before any task attempts to read from it, that second write will over-write what is put into the mailbox by this function call) </li>
<li>then, the mailbox data will be updated, and the version will be incremented by one </li>
<li>if there are any higher-priority tasks suspended on <a class="el" href="group__mailbox.html#g5dbb6937f6f93f6a1c14dec5b1c197c3" title="Wait for a mailbox to reach at least a certain version, and then start reading from...">read_mbox_min_version()</a>, they will start executing </li>
<li>if <code>wait_for_empty_nullify</code> is not zero, the function will not return until all tasks that had been suspended on <a class="el" href="group__mailbox.html#g5dbb6937f6f93f6a1c14dec5b1c197c3" title="Wait for a mailbox to reach at least a certain version, and then start reading from...">read_mbox_min_version()</a> have called <a class="el" href="group__mailbox.html#g31b8ee5f4cd547c128143d99ea1c4a96" title="Function to call when finished reading from a mailbox.">release_mbox_read()</a>. </li>
<li>if <code>wait_for_empty_nullify</code> is greater than one, a new version of the mailbox data, containing a null pointer, will be published</li>
</ul>
If the task that writes to the mailbox can be stopped with <a class="el" href="group__task.html#ge1337adc1d63d7cd874a376d6513c04a" title="Stop a task.">stop_task()</a>, then you could end up in a situation where the memory location of the task data goes out of scope while the mailbox is being read. If this is a possibility, then it is recommended that a <a class="el" href="group__mutex.html">mutex</a> be created for the mailbox, that it be locked on to while the mailbox is being written to, that the task only ever be stopped with the <code>wait_for_mutexes</code> parameter of <a class="el" href="group__task.html#ge1337adc1d63d7cd874a376d6513c04a" title="Stop a task.">stop_task()</a> set, and that <code>wait_for_empty_nullify</code> be set to at least one (it would need to be set at two if there are more than one tasks that could read from the mailbox).<p>
The arguments are <ul>
<li>
<code>mbox</code> - the mailbox to write to </li>
<li>
<code>data</code> - the pointer to the mailbox data. This is the value that will be returned by <a class="el" href="group__mailbox.html#g86030bb5345670ca374ddd20ef8e4ff6" title="Read a mailbox.">read_mbox()</a> and <a class="el" href="group__mailbox.html#g5dbb6937f6f93f6a1c14dec5b1c197c3" title="Wait for a mailbox to reach at least a certain version, and then start reading from...">read_mbox_min_version()</a>, so it is vital that it points to valid data for the lifetime of this particular version of the mailbox. </li>
<li>
<code>wait_for_receivers</code> - if non-zero, the write to the mailbox will not occur until there are at least <code>wait_for_receivers</code> task(s) waiting to read data from the mailbox. This could be used if it is vital that at least a specified number of receiving task(s) receive the information - it would give the receiving task(s) a chance to initialise </li>
<li>
<code>wait_for_empty_nullify</code> <ul>
<li>
if greater than zero, the function will not return until all tasks that were waiting to read the mailbox have done so. This could be used if it is vital that the sender knows that all messages have been received by the receiving task(s). </li>
<li>
if greater than one, the mailbox data will be set to null when all the tasks that were waiting to read the mailbox have done so (which means that subsequent reads of the mailbox will return a null pointer), so the data in the mailbox data buffer can safely be changed </li>
</ul>
</li>
</ul>
<p>
Since this function can cause a task suspension, it can only be called from a task with a non-zero priority 
</div>
</div><p>
<a class="anchor" name="g87f02ab5b46654ae26b06851b2390132"></a><!-- doxytag: member="task.h::write_mbox_now" ref="g87f02ab5b46654ae26b06851b2390132" args="(mailbox_t *mbox, void *data)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">int8_t write_mbox_now           </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="structmailbox__t.html">mailbox_t</a> *&nbsp;</td>
          <td class="paramname"> <em>mbox</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void *&nbsp;</td>
          <td class="paramname"> <em>data</em></td><td>&nbsp;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td><td width="100%"></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Attempt to write to a mailbox. 
<p>
This function will attempt to write to a mailbox - if the mailbox is being read, and is therefore unavailable for writing to as per the rules of mailboxes, this function will return immediately without having written anything to the mailbox.<p>
The arguments are - <ul>
<li><code>mbox</code> - the mailbox to write to </li>
<li><code>data</code> - the pointer to the mailbox data. This is the value that will be returned by <a class="el" href="group__mailbox.html#g86030bb5345670ca374ddd20ef8e4ff6" title="Read a mailbox.">read_mbox()</a> and <a class="el" href="group__mailbox.html#g5dbb6937f6f93f6a1c14dec5b1c197c3" title="Wait for a mailbox to reach at least a certain version, and then start reading from...">read_mbox_min_version()</a>.</li>
</ul>
The return value is zero on success<p>
Since this function will never cause a task suspension, it can be called from an ISR, from the idle task, or from anywhere else in the application. Also, if this function is called from within a task, and if the task is potentially stoppable by another task using <a class="el" href="group__task.html#ge1337adc1d63d7cd874a376d6513c04a" title="Stop a task.">stop_task()</a> on it, then it is important that the memory location pointed to by <code>data</code> doesn't go out of scope when the task is stopped. 
</div>
</div><p>
<hr>
<p align="center"><font size="-1">YAVRTOS and YAVRTOS documentation Copyright &copy; 2007-2008 Chris O'Byrne. Email - chris &lt;at&gt; obyrne &lt;dot&gt; com</font></p>
</body></html>