<divclass="title">Mutexes<divclass="ingroups"><aclass="el"href="group__CMSIS__RTOS__InterThread.html">Inter-Thread Communication and Resource Sharing</a></div></div></div>
<trclass="memdesc:ga9b522438489d7c402c95332b58bc94f3"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Define a Mutex. <ahref="#ga9b522438489d7c402c95332b58bc94f3">More...</a><br/></td></tr>
<trclass="memdesc:ga1122a86faa64b4a0880c76cf68d0c934"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Access a Mutex definition. <ahref="#ga1122a86faa64b4a0880c76cf68d0c934">More...</a><br/></td></tr>
<trclass="memdesc:ga5c9de56e717016e39e788064e9a291cc"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Create and Initialize a Mutex object. <ahref="#ga5c9de56e717016e39e788064e9a291cc">More...</a><br/></td></tr>
<trclass="memdesc:ga5e1752b73f573ee015dbd9ef1edaba13"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Wait until a Mutex becomes available. <ahref="#ga5e1752b73f573ee015dbd9ef1edaba13">More...</a><br/></td></tr>
<trclass="memdesc:ga006e4744d741e8e132c3d5bbc295afe1"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Release a Mutex that was obtained by <aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga5e1752b73f573ee015dbd9ef1edaba13">osMutexWait</a>. <ahref="#ga006e4744d741e8e132c3d5bbc295afe1">More...</a><br/></td></tr>
<trclass="memdesc:gac27e24135185d51d18f3dabc20910219"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Delete a Mutex that was created by <aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga5c9de56e717016e39e788064e9a291cc">osMutexCreate</a>. <ahref="#gac27e24135185d51d18f3dabc20910219">More...</a><br/></td></tr>
<p><b>Mutual exclusion</b> (widely known as <b>Mutex</b>) is used in various operating systems for resource management. Many resources in a microcontroller device can be used repeatedly, but only by one thread at a time (for example communication channels, memory, and files). Mutexes are used to protect access to a shared resource. A mutex is created and then passed between the threads (they can acquire and release the mutex).</p>
<p> A mutex is a special version of a <aclass="el"href="group__CMSIS__RTOS__SemaphoreMgmt.html">semaphore</a>. Like the semaphore, it is a container for tokens. But instead of being able to have multiple tokens, a mutex can only carry one (representing the resource). Thus, a mutex token is binary and bounded. The advantage of a mutex is that it introduces thread ownership. When a thread acquires a mutex and becomes its owner, subsequent mutex acquires from that thread will succeed immediately without any latency. Thus, mutex acquires/releases can be nested.</p>
<li>Mutex management functions cannot be called from interrupt service routines (ISR), unlike a binary semaphore that can be released from an ISR.</li>
<li>Declare the mutex container and initialize the mutex: <divclass="fragment"><divclass="line"><aclass="code"href="group__CMSIS__RTOS__MutexMgmt.html#ga9b522438489d7c402c95332b58bc94f3">osMutexDef</a> (uart_mutex); <spanclass="comment">// Declare mutex</span></div>
<li>Create the mutex in a thread: <divclass="fragment"><divclass="line">uart_mutex_id = <aclass="code"href="group__CMSIS__RTOS__MutexMgmt.html#ga5c9de56e717016e39e788064e9a291cc">osMutexCreate</a>(<aclass="code"href="group__CMSIS__RTOS__MutexMgmt.html#ga1122a86faa64b4a0880c76cf68d0c934">osMutex</a>(uart_mutex));</div>
<li>Acquire the mutex when peripheral access is required: <divclass="fragment"><divclass="line"><aclass="code"href="group__CMSIS__RTOS__MutexMgmt.html#ga5e1752b73f573ee015dbd9ef1edaba13">osMutexWait</a>(uart_mutex_id, <aclass="code"href="cmsis__os_8h.html#a9eb9a7a797a42e4b55eb171ecc609ddb">osWaitForever</a>);</div>
<li>When finished with the peripheral access, release the mutex: <divclass="fragment"><divclass="line"><aclass="code"href="group__CMSIS__RTOS__MutexMgmt.html#ga006e4744d741e8e132c3d5bbc295afe1">osMutexRelease</a>(uart_mutex_id);</div>
<p>Access to mutex object for the functions <aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga5c9de56e717016e39e788064e9a291cc">osMutexCreate</a>.</p>
<tr><tdclass="paramname">name</td><td>name of the mutex object. </td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>CAN BE CHANGED: The parameter to <b>osMutex</b> shall be consistent but the macro body is implementation specific in every CMSIS-RTOS. </dd></dl>
<p>Define a mutex object that is referenced by <aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga1122a86faa64b4a0880c76cf68d0c934">osMutex</a>.</p>
<tr><tdclass="paramname">name</td><td>name of the mutex object. </td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>CAN BE CHANGED: The parameter to <b>osMutexDef</b> shall be consistent but the macro body is implementation specific in every CMSIS-RTOS. </dd></dl>
<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>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">mutex_id</td><td>mutex ID obtained by <aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga5c9de56e717016e39e788064e9a291cc">osMutexCreate</a>. </td></tr>
<p>Delete a Mutex object. The function releases internal memory obtained for Mutex handling. After this call the <em>mutex_id</em> is no longer valid and cannot be used. The Mutex may be created again using the function <aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga5c9de56e717016e39e788064e9a291cc">osMutexCreate</a>.</p>
<p><b><aclass="el"href="group__CMSIS__RTOS__Status.html">Status and Error Codes</a></b><br/>
<li><em>osErrorISR:</em><aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#gac27e24135185d51d18f3dabc20910219">osMutexDelete</a> cannot be called from interrupt service routines.</li>
<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="group__CMSIS__RTOS__MutexMgmt.html#ga9b522438489d7c402c95332b58bc94f3">osMutexDef</a> (MutexIsr); <spanclass="comment">// Mutex name definition </span></div>
<divclass="line"><aclass="code"href="cmsis__os_8h.html#a3263c1ad9fd79b84f908d65e8da44ac2">osMutexId</a> mutex_id; <spanclass="comment">// Mutex id populated by the function CreateMutex()</span></div>
<divclass="line"><aclass="code"href="cmsis__os_8h.html#a3263c1ad9fd79b84f908d65e8da44ac2">osMutexId</a> CreateMutex (<spanclass="keywordtype">void</span>); <spanclass="comment">// function prototype that creates the Mutex</span></div>
<divclass="line"> status = <aclass="code"href="group__CMSIS__RTOS__MutexMgmt.html#gac27e24135185d51d18f3dabc20910219">osMutexDelete</a>(mutex_id);</div>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">mutex_id</td><td>mutex ID obtained by <aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga5c9de56e717016e39e788064e9a291cc">osMutexCreate</a>. </td></tr>
<p>Release a Mutex that was obtained with <aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga5e1752b73f573ee015dbd9ef1edaba13">osMutexWait</a>. Other threads that currently wait for the same mutex will be now put into the state <b>READY</b>.</p>
<p><b><aclass="el"href="group__CMSIS__RTOS__Status.html">Status and Error Codes</a></b><br/>
<li><em>osErrorISR:</em><aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga006e4744d741e8e132c3d5bbc295afe1">osMutexRelease</a> cannot be called from interrupt service routines.</li>
<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="group__CMSIS__RTOS__MutexMgmt.html#ga9b522438489d7c402c95332b58bc94f3">osMutexDef</a> (MutexIsr); <spanclass="comment">// Mutex name definition </span></div>
<divclass="line"><aclass="code"href="cmsis__os_8h.html#a3263c1ad9fd79b84f908d65e8da44ac2">osMutexId</a> mutex_id; <spanclass="comment">// Mutex id populated by the function CreateMutex()</span></div>
<divclass="line"><aclass="code"href="cmsis__os_8h.html#a3263c1ad9fd79b84f908d65e8da44ac2">osMutexId</a> CreateMutex (<spanclass="keywordtype">void</span>); <spanclass="comment">// function prototype that creates the Mutex</span></div>
<divclass="line"> status = <aclass="code"href="group__CMSIS__RTOS__MutexMgmt.html#ga006e4744d741e8e132c3d5bbc295afe1">osMutexRelease</a>(mutex_id);</div>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">mutex_id</td><td>mutex ID obtained by <aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga5c9de56e717016e39e788064e9a291cc">osMutexCreate</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>status code that indicates the execution status of the function. </dd></dl>
<dlclass="section note"><dt>Note</dt><dd>MUST REMAIN UNCHANGED: <b>osMutexWait</b> shall be consistent in every CMSIS-RTOS.</dd></dl>
<p>Wait until a Mutex becomes available. If no other thread has obtained the Mutex, the function instantly returns and blocks the mutex object.</p>
<p>The argument <em>millisec</em> specifies how long the system waits for a mutex. 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 the mutex becomes available.</li>
<li>all other values specify a time in millisecond for a timeout.</li>
<li><em>osErrorISR:</em><aclass="el"href="group__CMSIS__RTOS__MutexMgmt.html#ga5e1752b73f573ee015dbd9ef1edaba13">osMutexWait</a> cannot be called from interrupt service routines.</li>
<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>
