<p>A mutex is a threads synchronization object that can be in two distinct states:</p>
<ul>
<li>Not owned.</li>
<li>Owned by a thread.</li>
</ul>
<p>Operations defined for mutexes:</p>
<ul>
<li><b>Lock</b>: The mutex is checked, if the mutex is not owned by some other thread then it is associated to the locking thread else the thread is queued on the mutex in a list ordered by priority.</li>
<li><b>Unlock</b>: The mutex is released by the owner and the highest priority thread waiting in the queue, if any, is resumed and made owner of the mutex.</li>
</ul>
<p>In order to use the Mutexes APIs the <code>CH_USE_MUTEXES</code> option must be enabled in <code><aclass="el"href="chconf_8h.html"title="Configuration file template.">chconf.h</a></code>. </p>
<h2>Constraints</h2>
<p>In ChibiOS/RT the Unlock operations are always performed in lock-reverse order. The unlock API does not even have a parameter, the mutex to unlock is selected from an internal, per-thread, stack of owned mutexes. This both improves the performance and is required for an efficient implementation of the priority inheritance mechanism.</p>
<h2>The priority inversion problem</h2>
<p>The mutexes in ChibiOS/RT implements the <b>full</b> priority inheritance mechanism in order handle the priority inversion problem.<br/>
When a thread is queued on a mutex, any thread, directly or indirectly, holding the mutex gains the same priority of the waiting thread (if their priority was not already equal or higher). The mechanism works with any number of nested mutexes and any number of involved threads. The algorithm complexity (worst case) is N with N equal to the number of nested mutexes. </p>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Data part of a static mutex initializer. <ahref="#ga01a9ed719f222e64589413d6eda7396e"></a><br/></td></tr>
<tr><tdclass="memItemLeft"align="right"valign="top">#define </td><tdclass="memItemRight"valign="bottom"><aclass="el"href="group__mutexes.html#ga0461d963db5d730f1829eb783f6fdf94">MUTEX_DECL</a>(name) <aclass="el"href="struct_mutex.html">Mutex</a> name = _MUTEX_DATA(name)</td></tr>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns <code>TRUE</code> if the mutex queue contains at least a waiting thread. <ahref="#ga322ebcfba68cf5b66b9c315638e3ae63"></a><br/></td></tr>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Unlocks the next owned mutex in reverse lock order. <ahref="#gae9ae07165126c9f6c0ce0b17bdb53669"></a><br/></td></tr>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Unlocks the next owned mutex in reverse lock order. <ahref="#ga705fa60fb8aa28a6632f693e83f78c96"></a><br/></td></tr>
<tr><tdclass="mdescLeft"> </td><tdclass="mdescRight">Unlocks all the mutexes owned by the invoking thread. <ahref="#ga853b4ced43d22fb5d82678dd2f0aba75"></a><br/></td></tr>
<td> <aclass="el"href="struct_mutex.html">Mutex</a> name = _MUTEX_DATA(name)</td>
</tr>
</table>
</div>
<divclass="memdoc">
<p>Static mutex initializer. </p>
<p>Statically initialized mutexes require no explicit initialization using <code><aclass="el"href="group__mutexes.html#gac55fe4d05aa6bbeb31594193d2e4d2b6"title="Initializes s Mutex structure.">chMtxInit()</a></code>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<tableborder="0"cellspacing="2"cellpadding="0">
<tr><tdvalign="top"><tt>[in]</tt> </td><tdvalign="top"><em>name</em> </td><td>the name of the mutex variable </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <aclass="el"href="chmtx_8h_source.html#l00083">83</a> of file <aclass="el"href="chmtx_8h_source.html">chmtx.h</a>.</p>
<p>Returns <code>TRUE</code> if the mutex queue contains at least a waiting thread. </p>
<p>Definition at line <aclass="el"href="chmtx_8h_source.html#l00089">89</a> of file <aclass="el"href="chmtx_8h_source.html">chmtx.h</a>.</p>
<p>Referenced by <aclass="el"href="group__mutexes.html#gae9ae07165126c9f6c0ce0b17bdb53669">chMtxUnlock()</a>, <aclass="el"href="group__mutexes.html#ga853b4ced43d22fb5d82678dd2f0aba75">chMtxUnlockAll()</a>, and <aclass="el"href="group__mutexes.html#ga705fa60fb8aa28a6632f693e83f78c96">chMtxUnlockS()</a>.</p>
<p>Initializes s <code><aclass="el"href="struct_mutex.html"title="Mutex structure.">Mutex</a></code> structure. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<tableborder="0"cellspacing="2"cellpadding="0">
<tr><tdvalign="top"><tt>[out]</tt> </td><tdvalign="top"><em>mp</em> </td><td>pointer to a <code><aclass="el"href="struct_mutex.html"title="Mutex structure.">Mutex</a></code> structure </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <aclass="el"href="chmtx_8c_source.html#l00081">81</a> of file <aclass="el"href="chmtx_8c_source.html">chmtx.c</a>.</p>
<p>References <aclass="el"href="group__debug.html#ga6bb6c0f97caab3a66332c8bfbf7a3844">chDbgCheck</a>, <aclass="el"href="struct_mutex.html#ad83ff6b7d8b483f91a080ae8c53a4941">Mutex::m_owner</a>, <aclass="el"href="struct_mutex.html#ad3efd6941b40b1415b5fe40e804d4b6f">Mutex::m_queue</a>, and <aclass="el"href="group__internals.html#ga6d19d0f3ff1fa599b6d9783dec180451">queue_init</a>.</p>
<p>Referenced by <aclass="el"href="group__heaps.html#ga7135c9ddbd1402a4a36ce44df948f4e4">chHeapInit()</a>, <aclass="el"href="group__heaps.html#ga7e7a6625a49b6a560a47ae7575575264">heap_init()</a>, <aclass="el"href="classchibios__rt_1_1_mutex.html#a00b2ff557451955a905ecdca2855389b">chibios_rt::Mutex::Mutex()</a>, and <aclass="el"href="group___s_p_i.html#ga87a7bdc554b8e8fdfc77064e67689fcf">spiObjectInit()</a>.</p>
<tr><tdvalign="top"><tt>[in]</tt> </td><tdvalign="top"><em>mp</em> </td><td>pointer to the <code><aclass="el"href="struct_mutex.html"title="Mutex structure.">Mutex</a></code> structure </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <aclass="el"href="chmtx_8c_source.html#l00094">94</a> of file <aclass="el"href="chmtx_8c_source.html">chmtx.c</a>.</p>
<p>References <aclass="el"href="group__mutexes.html#ga2d6350c2d147d1165c359f30798205f5">chMtxLockS()</a>, <aclass="el"href="group__system.html#ga9f6573c0763d1e4e97c63c62edad6e42">chSysLock</a>, and <aclass="el"href="group__system.html#ga5a257fa58a09815eb64a45e2dfbdc22e">chSysUnlock</a>.</p>
<p>Referenced by <aclass="el"href="classchibios__rt_1_1_mutex.html#a1726d7244983f7be74fcfa9cfb63745f">chibios_rt::Mutex::Lock()</a>, and <aclass="el"href="group___s_p_i.html#ga803cec73f6dd8d3d1f18fb6a61b8255a">spiAcquireBus()</a>.</p>
<areashape="rect"id="node3"href="group__mutexes.html#ga2d6350c2d147d1165c359f30798205f5"title="Locks the specified mutex."alt=""coords="129,81,209,108"/><areashape="rect"id="node5"href="group__scheduler.html#ga97c1c514b755a1e71caf2f19c1ccf986"title="Puts the current thread to sleep into the specified state."alt=""coords="259,5,360,32"/><areashape="rect"id="node7"href="group__scheduler.html#ga535d58cfb3436c8d4e4586c31c062298"title="Inserts a thread in the Ready List."alt=""coords="267,56,352,83"/><areashape="rect"id="node9"href="group__internals.html#gafff11bcd31d7dc3d1a0a6c66f3fc6ec9"title="Removes a Thread from a queue and returns it."alt=""coords="277,107,341,133"/><areashape="rect"id="node11"href="group__internals.html#ga02226b866ae704435baf2ffe259ba0b2"title="Inserts a thread into a priority ordered queue."alt=""coords="273,157,345,184"/></map>
<tr><tdvalign="top"><tt>[in]</tt> </td><tdvalign="top"><em>mp</em> </td><td>pointer to the <code><aclass="el"href="struct_mutex.html"title="Mutex structure.">Mutex</a></code> structure </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <aclass="el"href="chmtx_8c_source.html#l00108">108</a> of file <aclass="el"href="chmtx_8c_source.html">chmtx.c</a>.</p>
<p>Referenced by <aclass="el"href="group__condvars.html#gab6357d80b01ed8d225ef1e30a66248f9">chCondWaitS()</a>, <aclass="el"href="group__condvars.html#ga9cf6ebe4c9f28cb206fab14984a18d29">chCondWaitTimeoutS()</a>, and <aclass="el"href="group__mutexes.html#gafa06b82e3496c44eb7bf31d9f1b655ba">chMtxLock()</a>.</p>
<areashape="rect"id="node3"href="group__scheduler.html#ga97c1c514b755a1e71caf2f19c1ccf986"title="Puts the current thread to sleep into the specified state."alt=""coords="136,31,237,57"/><areashape="rect"id="node9"href="group__scheduler.html#ga535d58cfb3436c8d4e4586c31c062298"title="Inserts a thread in the Ready List."alt=""coords="144,81,229,108"/><areashape="rect"id="node11"href="group__internals.html#gafff11bcd31d7dc3d1a0a6c66f3fc6ec9"title="Removes a Thread from a queue and returns it."alt=""coords="155,132,219,159"/><areashape="rect"id="node13"href="group__internals.html#ga02226b866ae704435baf2ffe259ba0b2"title="Inserts a thread into a priority ordered queue."alt=""coords="151,183,223,209"/><areashape="rect"id="node5"href="group__debug.html#gac7f8f0653faf2e3a93108ff5333821b7"title="Inserts in the circular debug trace buffer a context switch record."alt=""coords="287,5,367,32"/><areashape="rect"id="node7"href="group__internals.html#ga042479f09357fc59befebf4dfe0e9f4a"title="Removes the first-out Thread from a queue and returns it."alt=""coords="287,56,367,83"/></map>
<p>This function does not have any overhead related to the priority inheritance mechanism because it does not try to enter a sleep state on the mutex.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<tableborder="0"cellspacing="2"cellpadding="0">
<tr><tdvalign="top"><tt>[in]</tt> </td><tdvalign="top"><em>mp</em> </td><td>pointer to the <code><aclass="el"href="struct_mutex.html"title="Mutex structure.">Mutex</a></code> structure </td></tr>
</table>
</dd>
</dl>
<dl><dt><b>Return values:</b></dt><dd>
<tableborder="0"cellspacing="2"cellpadding="0">
<tr><tdvalign="top"></td><tdvalign="top"><em>TRUE</em> </td><td>if the mutex was successfully acquired </td></tr>
<tr><tdvalign="top"></td><tdvalign="top"><em>FALSE</em> </td><td>if the lock attempt failed. </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <aclass="el"href="chmtx_8c_source.html#l00178">178</a> of file <aclass="el"href="chmtx_8c_source.html">chmtx.c</a>.</p>
<p>References <aclass="el"href="group__mutexes.html#gadbf0bd4a36b1f7e33ee41939df32ab78">chMtxTryLockS()</a>, <aclass="el"href="group__system.html#ga9f6573c0763d1e4e97c63c62edad6e42">chSysLock</a>, and <aclass="el"href="group__system.html#ga5a257fa58a09815eb64a45e2dfbdc22e">chSysUnlock</a>.</p>
<p>Referenced by <aclass="el"href="classchibios__rt_1_1_mutex.html#a787ecfd207fd25760a3c07517b69c148">chibios_rt::Mutex::TryLock()</a>.</p>
<areashape="rect"id="node3"href="group__mutexes.html#gadbf0bd4a36b1f7e33ee41939df32ab78"title="Tries to lock a mutex."alt=""coords="145,5,241,32"/></map>
<p>This function does not have any overhead related to the priority inheritance mechanism because it does not try to enter a sleep state on the mutex.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<tableborder="0"cellspacing="2"cellpadding="0">
<tr><tdvalign="top"><tt>[in]</tt> </td><tdvalign="top"><em>mp</em> </td><td>pointer to the <code><aclass="el"href="struct_mutex.html"title="Mutex structure.">Mutex</a></code> structure </td></tr>
</table>
</dd>
</dl>
<dl><dt><b>Return values:</b></dt><dd>
<tableborder="0"cellspacing="2"cellpadding="0">
<tr><tdvalign="top"></td><tdvalign="top"><em>TRUE</em> </td><td>if the mutex was successfully acquired </td></tr>
<tr><tdvalign="top"></td><tdvalign="top"><em>FALSE</em> </td><td>if the lock attempt failed. </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <aclass="el"href="chmtx_8c_source.html#l00199">199</a> of file <aclass="el"href="chmtx_8c_source.html">chmtx.c</a>.</p>
<p>References <aclass="el"href="group__debug.html#ga6bb6c0f97caab3a66332c8bfbf7a3844">chDbgCheck</a>, <aclass="el"href="group__scheduler.html#ga1a5fddde56420e8accd0c09c1abb32a7">currp</a>, <aclass="el"href="struct_mutex.html#aa2113b554e5f0deefbc20dbadfd3d1dd">Mutex::m_next</a>, and <aclass="el"href="struct_mutex.html#ad83ff6b7d8b483f91a080ae8c53a4941">Mutex::m_owner</a>.</p>
<p>Referenced by <aclass="el"href="group__mutexes.html#gaada14e216460dc55e1816234168cf95c">chMtxTryLock()</a>.</p>
<p>Referenced by <aclass="el"href="group___s_p_i.html#ga1b04a2410ef4323ee4e37c63f320c18f">spiReleaseBus()</a>, and <aclass="el"href="classchibios__rt_1_1_mutex.html#a03150e8fa423f7e042661d350d238b84">chibios_rt::Mutex::Unlock()</a>.</p>
<areashape="rect"id="node3"href="group__scheduler.html#gae47a8819a21ef2d521124e76bfb37c95"title="Wakes up a thread."alt=""coords="136,31,235,57"/><areashape="rect"id="node9"href="group__internals.html#ga042479f09357fc59befebf4dfe0e9f4a"title="Removes the first-out Thread from a queue and returns it."alt=""coords="145,81,225,108"/><areashape="rect"id="node5"href="group__debug.html#gac7f8f0653faf2e3a93108ff5333821b7"title="Inserts in the circular debug trace buffer a context switch record."alt=""coords="287,5,367,32"/><areashape="rect"id="node7"href="group__scheduler.html#ga535d58cfb3436c8d4e4586c31c062298"title="Inserts a thread in the Ready List."alt=""coords="284,56,369,83"/></map>
<p>Referenced by <aclass="el"href="group__condvars.html#gab6357d80b01ed8d225ef1e30a66248f9">chCondWaitS()</a>, and <aclass="el"href="group__condvars.html#ga9cf6ebe4c9f28cb206fab14984a18d29">chCondWaitTimeoutS()</a>.</p>
<areashape="rect"id="node3"href="group__scheduler.html#ga535d58cfb3436c8d4e4586c31c062298"title="Inserts a thread in the Ready List."alt=""coords="145,5,231,32"/><areashape="rect"id="node5"href="group__internals.html#ga042479f09357fc59befebf4dfe0e9f4a"title="Removes the first-out Thread from a queue and returns it."alt=""coords="148,56,228,83"/></map>
<p>Unlocks all the mutexes owned by the invoking thread. </p>
<p>This function is <b>MUCH MORE</b> efficient than releasing the mutexes one by one and not just because the call overhead, this function does not have any overhead related to the priority inheritance mechanism. </p>
<p>Definition at line <aclass="el"href="chmtx_8c_source.html#l00322">322</a> of file <aclass="el"href="chmtx_8c_source.html">chmtx.c</a>.</p>
<areashape="rect"id="node3"href="group__scheduler.html#ga535d58cfb3436c8d4e4586c31c062298"title="Inserts a thread in the Ready List."alt=""coords="489,5,575,32"/><areashape="rect"id="node5"href="group__scheduler.html#ga4e38b4bee3d2330f6a0f1cdb7660af20"title="Performs a reschedule if a higher priority thread is runnable."alt=""coords="149,31,267,57"/><areashape="rect"id="node10"href="group__internals.html#ga042479f09357fc59befebf4dfe0e9f4a"title="Removes the first-out Thread from a queue and returns it."alt=""coords="492,56,572,83"/><areashape="rect"id="node7"href="group__scheduler.html#ga0257cf203e72a766a52059750cb97e6e"title="Switches to the first thread on the runnable queue."alt=""coords="315,31,440,57"/></map>
Generated on Sun Nov 28 2010 14:09:56 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>