<trclass="memdesc:gaee93d929beb350f16e5cc7fa602e229f"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Create a Thread Definition with function, priority, and stack requirements. <ahref="#gaee93d929beb350f16e5cc7fa602e229f">More...</a><br/></td></tr>
<trclass="memdesc:gaf0c7c6b5e09f8be198312144b5c9e453"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Access a Thread definition. <ahref="#gaf0c7c6b5e09f8be198312144b5c9e453">More...</a><br/></td></tr>
<trclass="memdesc:ga7f2b42f1983b9107775ec2a1c69a849a"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Priority used for thread control. <ahref="group__CMSIS__RTOS__ThreadMgmt.html#ga7f2b42f1983b9107775ec2a1c69a849a">More...</a><br/></td></tr>
<trclass="memdesc:gac59b5713cb083702dce759c73fd90dff"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Create a thread and add it to Active Threads and set it to state READY. <ahref="#gac59b5713cb083702dce759c73fd90dff">More...</a><br/></td></tr>
<trclass="memdesc:gab1df2a28925862ef8f9cf4e1c995c5a7"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Return the thread ID of the current running thread. <ahref="#gab1df2a28925862ef8f9cf4e1c995c5a7">More...</a><br/></td></tr>
<trclass="memdesc:gaea135bb90eb853eff39e0800b91bbeab"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Terminate execution of a thread and remove it from Active Threads. <ahref="#gaea135bb90eb853eff39e0800b91bbeab">More...</a><br/></td></tr>
<trclass="memdesc:ga0dfb90ccf1f6e4b54b9251b12d1cbc8b"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Change priority of an active thread. <ahref="#ga0dfb90ccf1f6e4b54b9251b12d1cbc8b">More...</a><br/></td></tr>
<trclass="memdesc:ga4299d838978bc2aae5e4350754e6a4e9"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Get current priority of an active thread. <ahref="#ga4299d838978bc2aae5e4350754e6a4e9">More...</a><br/></td></tr>
<trclass="memdesc:gaf13a667493c5d629a90c13e113b99233"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Pass control to next thread that is in state <b>READY</b>. <ahref="#gaf13a667493c5d629a90c13e113b99233">More...</a><br/></td></tr>
<p>The Thread Management function group allows defining, creating, and controlling thread functions in the system. The function <b>main</b> is a special thread function that is started at system initialization and has the initial priority <em>osPriorityNormal</em>.</p>
<p><aclass="anchor"id="ThreadStates"></a>Threads can be in the following states:</p>
<ul>
<li><b>RUNNING:</b> The thread that is currently running is in the <b>RUNNING</b> state. Only one thread at a time can be in this state.</li>
<li><b>READY:</b> Threads which are ready to run are in the <b>READY</b> state. Once the <b>RUNNING</b> thread has terminated or is <b>WAITING</b>, the next <b>READY</b> thread with the highest priority becomes the <b>RUNNING</b> thread.</li>
<li><b>WAITING:</b> Threads that are waiting for an event to occur are in the <b>WAITING</b> state.</li>
<li><b>INACTIVE:</b> Threads that are not created or terminated are in the <b>INACTIVE</b> state. These threads typically consume no system resources.</li>
<p> A CMSIS-RTOS assumes that threads are scheduled as shown in the figure <b>Thread State and State Transitions</b>. The thread states change as follows:</p>
<li>A thread is created using the function <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gac59b5713cb083702dce759c73fd90dff">osThreadCreate</a>. This puts the thread into the <b>READY</b> or <b>RUNNING</b> state (depending on the thread priority).</li>
<li>CMSIS-RTOS is pre-emptive. The active thread with the highest priority becomes the <b>RUNNING</b> thread provided it does not wait for any event. The initial priority of a thread is defined with the <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gaee93d929beb350f16e5cc7fa602e229f">osThreadDef</a> but may be changed during execution using the function <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#ga0dfb90ccf1f6e4b54b9251b12d1cbc8b">osThreadSetPriority</a>.</li>
<li>Active threads can be terminated any time using the function <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gaea135bb90eb853eff39e0800b91bbeab">osThreadTerminate</a>. Threads can terminate also by just returning from the thread function. Threads that are terminated are in the <b>INACTIVE</b> state and typically do not consume any dynamic memory resources. </li>
<p>Access to the thread definition for the function <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gac59b5713cb083702dce759c73fd90dff">osThreadCreate</a>.</p>
<tr><tdclass="paramname">name</td><td>name of the thread definition object. </td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>CAN BE CHANGED: The parameter to <b>osThread</b> shall be consistent but the macro body is implementation specific in every CMSIS-RTOS. </dd></dl>
<p>Define the attributes of a thread functions that can be created by the function <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gac59b5713cb083702dce759c73fd90dff">osThreadCreate</a> using <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gaf0c7c6b5e09f8be198312144b5c9e453">osThread</a>. The argument <em>instances</em> defines the number of times that <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gac59b5713cb083702dce759c73fd90dff">osThreadCreate</a> can be called for the same <b>osThreadDef</b>.</p>
<divclass="line"><spanclass="keywordtype">void</span> Thread (<spanclass="keywordtype">void</span><spanclass="keyword">const</span> *arg); <spanclass="comment">// function prototype for a Thread</span></div>
<divclass="line"><aclass="code"href="group__CMSIS__RTOS__ThreadMgmt.html#gaee93d929beb350f16e5cc7fa602e229f">osThreadDef</a> (Thread, <aclass="code"href="cmsis__os_8h.html#ga7f2b42f1983b9107775ec2a1c69a849aa45a2895ad30c79fb97de18cac7cc19f1">osPriorityNormal</a>, 3, 0); <spanclass="comment">// define Thread and specify to allow three instances</span></div>
<divclass="line"><spanclass="comment">// Failed to create the thread with id3</span></div>
<divclass="line"> }</div>
<divclass="line"> :</div>
<divclass="line"><aclass="code"href="group__CMSIS__RTOS__ThreadMgmt.html#gaea135bb90eb853eff39e0800b91bbeab">osThreadTerminate</a> (id1); <spanclass="comment">// stop the thread with id1</span></div>
<divclass="line"><aclass="code"href="group__CMSIS__RTOS__ThreadMgmt.html#gaea135bb90eb853eff39e0800b91bbeab">osThreadTerminate</a> (id2); <spanclass="comment">// stop the thread with id2</span></div>
<divclass="line"><aclass="code"href="group__CMSIS__RTOS__ThreadMgmt.html#gaea135bb90eb853eff39e0800b91bbeab">osThreadTerminate</a> (id3); <spanclass="comment">// stop the thread with id3</span></div>
<divclass="line">}</div>
</div><!-- fragment --><dlclass="params"><dt>Parameters</dt><dd>
<tr><tdclass="paramname">name</td><td>name of the thread function. </td></tr>
<tr><tdclass="paramname">priority</td><td>initial priority of the thread function. </td></tr>
<tr><tdclass="paramname">instances</td><td>number of possible thread instances. </td></tr>
<tr><tdclass="paramname">stacksz</td><td>stack size (in bytes) requirements for the thread function. </td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>CAN BE CHANGED: The parameters to <b>osThreadDef</b> shall be consistent but the macro body is implementation specific in every CMSIS-RTOS. </dd></dl>
</div>
</div>
<h2class="groupheader">Enumeration Type Documentation</h2>
Cannot be called from <aclass="el"href="functionOverview.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a>.</dd></dl>
<p>The <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#ga7f2b42f1983b9107775ec2a1c69a849a">osPriority</a> value specifies the priority for a thread. The default thread priority should be <em>osPriorityNormal</em>. If a Thread is active that has a higher priority than the currently executing thread, then a thread switch occurs immediately to execute the new task.</p>
<p>To prevent from a priority inversion, a CMSIS-RTOS compliant OS may optionally implement a <b>priority inheritance</b> method. A priority inversion occurs when a high priority thread is waiting for a resource or event that is controlled by a thread with a lower priority. </p>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">argument</td><td>pointer that is passed to the thread function as start argument. </td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>thread ID for reference by other functions or NULL in case of error. </dd></dl>
<dlclass="section note"><dt>Note</dt><dd>MUST REMAIN UNCHANGED: <b>osThreadCreate</b> shall be consistent in every CMSIS-RTOS.</dd></dl>
<p>Start a thread function by adding it to the Active Threads list and set it to state <b>READY</b>. The thread function receives the <em>argument</em> pointer as function argument when the function is started. When the priority of the created thread function is higher than the current <b>RUNNING</b> thread, the created thread function starts instantly and becomes the new <b>RUNNING</b> thread.</p>
<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"><spanclass="keywordtype">void</span> Thread_1 (<spanclass="keywordtype">void</span><spanclass="keyword">const</span> *arg); <spanclass="comment">// function prototype for Thread_1</span></div>
<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>
<dd>
Must not be used inside the idle daemon. This would lead to undefined behavior.</dd></dl>
<divclass="line"><aclass="code"href="cmsis__os_8h.html#adfeb153a84a81309e2d958268197617f">osThreadId</a> id; <spanclass="comment">// id for the currently running thread</span></div>
<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>. </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> id; <spanclass="comment">// id for the currently running thread</span></div>
<divclass="line"><spanclass="keywordtype">id</span> = <aclass="code"href="group__CMSIS__RTOS__ThreadMgmt.html#gab1df2a28925862ef8f9cf4e1c995c5a7">osThreadGetId</a> (); <spanclass="comment">// Obtain ID of current running thread</span></div>
<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>. </td></tr>
<li><em>osErrorISR:</em><aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#ga0dfb90ccf1f6e4b54b9251b12d1cbc8b">osThreadSetPriority</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="cmsis__os_8h.html#adfeb153a84a81309e2d958268197617f">osThreadId</a> id; <spanclass="comment">// id for the currently running thread</span></div>
<divclass="line"><aclass="code"href="group__CMSIS__RTOS__Status.html#gae2e091fefc4c767117727bd5aba4d99e">osStatus</a> status; <spanclass="comment">// status of the executed function</span></div>
<divclass="line"><spanclass="keywordtype">id</span> = <aclass="code"href="group__CMSIS__RTOS__ThreadMgmt.html#gab1df2a28925862ef8f9cf4e1c995c5a7">osThreadGetId</a> (); <spanclass="comment">// Obtain ID of current running thread</span></div>
<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>. </td></tr>
<dlclass="section note"><dt>Note</dt><dd>In case that <aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gaea135bb90eb853eff39e0800b91bbeab">osThreadTerminate</a> terminates the currently running task, the function never returns and other threads that are in the READY state are started.</dd></dl>
<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__ThreadMgmt.html#gaea135bb90eb853eff39e0800b91bbeab">osThreadTerminate</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>
<dd>
Avoid calling the function with a <em>thread_id</em> that does not exist or has been terminated already.</dd></dl>
<divclass="line"><spanclass="keywordtype">void</span> Thread_1 (<spanclass="keywordtype">void</span><spanclass="keyword">const</span> *arg); <spanclass="comment">// function prototype for Thread_1</span></div>
<divclass="line"> status = <aclass="code"href="group__CMSIS__RTOS__ThreadMgmt.html#gaea135bb90eb853eff39e0800b91bbeab">osThreadTerminate</a> (<spanclass="keywordtype">id</span>); <spanclass="comment">// stop the thread</span></div>
<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>osThreadYield</b> shall be consistent in every CMSIS-RTOS.</dd></dl>
<p>Pass control to the next thread that is in state <b>READY</b>. If there is no other thread in the state <b>READY</b>, the current thread continues execution and no thread switching occurs.</p>
<li><em>osErrorISR:</em><aclass="el"href="group__CMSIS__RTOS__ThreadMgmt.html#gaf13a667493c5d629a90c13e113b99233">osThreadYield</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__Status.html#gae2e091fefc4c767117727bd5aba4d99e">osStatus</a> status; <spanclass="comment">// status of the executed function</span></div>
