224 lines
16 KiB
HTML
224 lines
16 KiB
HTML
<!-- HTML header for doxygen 1.9.1-->
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.15.0"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>L4Re Operating System Framework: Pthread Support</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
|
<script type="text/javascript" src="navtree.js"></script>
|
|
<script type="text/javascript" src="cookie.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
|
|
<link href="l4re-awesome.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectlogo"><img alt="Logo" src="L4Re_rgb_logo_quer_hg_h55.png"/></td>
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">L4Re Operating System Framework
|
|
</div>
|
|
<div id="projectbrief">Interface and Usage Documentation</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.15.0 -->
|
|
<script type="text/javascript">
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
</script>
|
|
<script type="text/javascript">
|
|
$(function() { codefold.init(); });
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search',true);
|
|
$(function() { init_search(); });
|
|
});
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
</div><!-- top -->
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
|
<div id="nav-tree">
|
|
<div id="nav-tree-contents">
|
|
<div id="nav-sync" class="sync"></div>
|
|
</div>
|
|
</div>
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
|
class="ui-resizable-handle">
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">
|
|
$(function(){initNavTree('l4re_pthreads.html','',''); });
|
|
</script>
|
|
<div id="container">
|
|
<div id="doc-content">
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div><div class="header">
|
|
<div class="headertitle"><div class="title">Pthread Support </div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> supports the standard pthread library functionality. Therefore <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> itself does not contain any documentation for pthreads itself. Please refer to the standard pthread documentation instead.</p>
|
|
<p>The <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> specific parts will be described herein.</p>
|
|
<ul>
|
|
<li>
|
|
<p class="startli">Include pthread-l4.h header file: </p><div class="fragment"><div class="line"><span class="preprocessor">#include <pthread-l4.h></span></div>
|
|
</div><!-- fragment --><p class="endli"></p>
|
|
</li>
|
|
<li>
|
|
<p class="startli">Return the local thread capability of a pthread thread:</p>
|
|
<p class="interli">Use <code>pthread_l4_cap(pthread_t t)</code> to get the capability index of the pthread t.</p>
|
|
<p class="interli">For example: </p><div class="fragment"><div class="line">pthread_l4_cap(pthread_self());</div>
|
|
</div><!-- fragment --> <p class="endli"></p>
|
|
</li>
|
|
<li>
|
|
<p class="startli">Setting the <a class="el" href="namespaceL4.html" title="L4 low-level kernel interface.">L4</a> priority of an <a class="el" href="namespaceL4.html" title="L4 low-level kernel interface.">L4</a> thread works with a special scheduling policy (other policies do not affect the <a class="el" href="namespaceL4.html" title="L4 low-level kernel interface.">L4</a> thread priority):</p>
|
|
<div class="fragment"><div class="line">pthread_t t;</div>
|
|
<div class="line">pthread_attr_t a;</div>
|
|
<div class="line"><span class="keyword">struct </span>sched_param sp;</div>
|
|
<div class="line"> </div>
|
|
<div class="line">pthread_attr_init(&a);</div>
|
|
<div class="line">sp.sched_priority = l4_priority;</div>
|
|
<div class="line">pthread_attr_setschedpolicy(&a, SCHED_L4);</div>
|
|
<div class="line">pthread_attr_setschedparam(&a, &sp);</div>
|
|
<div class="line">pthread_attr_setinheritsched(&a, PTHREAD_EXPLICIT_SCHED);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span> (pthread_create(&t, &a, pthread_func, NULL))</div>
|
|
<div class="line"> <span class="comment">// failure...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line">pthread_attr_destroy(&a);</div>
|
|
</div><!-- fragment --><p class="interli"></p>
|
|
<p class="endli"></p>
|
|
</li>
|
|
<li>
|
|
<p class="startli">You can prevent your pthread from running immediately after the call to <code>pthread_create</code>(..) by adding <code>PTHREAD_L4_ATTR_NO_START</code> to the <code>create_flags</code> of the pthread attributes. To finally start the thread you need to call <code>scheduler()->run_thread()</code> passing the capability of the pthread and scheduling parameters.</p>
|
|
<div class="fragment"><div class="line">pthread_t t;</div>
|
|
<div class="line">pthread_attr_t attr;</div>
|
|
<div class="line"> </div>
|
|
<div class="line">pthread_attr_init(&attr);</div>
|
|
<div class="line">attr.create_flags |= PTHREAD_L4_ATTR_NO_START;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span> (pthread_create(&t, &attr, pthread_func, <span class="keyword">nullptr</span>))</div>
|
|
<div class="line"> <span class="comment">// failure...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line">pthread_attr_destroy(&attr);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// do stuff</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">auto</span> ret = <a class="code hl_function" href="classL4Re_1_1Env.html#a2706ca11e70845b0a29a5646c9fd54bc">L4Re::Env::env</a>()-><a class="code hl_function" href="classL4Re_1_1Env.html#a13a538cde83236d893045d533dc7296b">scheduler</a>()->run_thread(pthread_l4_cap(t),</div>
|
|
<div class="line"> <a class="code hl_function" href="group__l4__scheduler__api.html#ga97fc9fce99006ce7011a25bb8d014c8d">l4_sched_param</a>(2));</div>
|
|
<div class="line"><span class="keywordflow">if</span> (<a class="code hl_function" href="group__l4__ipc__err__api.html#ga05c11e3e10b6c2aa941396ac2018899f">l4_error</a>(ret))</div>
|
|
<div class="line"> <span class="comment">// failure...</span></div>
|
|
<div class="ttc" id="aclassL4Re_1_1Env_html_a13a538cde83236d893045d533dc7296b"><div class="ttname"><a href="classL4Re_1_1Env.html#a13a538cde83236d893045d533dc7296b">L4Re::Env::scheduler</a></div><div class="ttdeci">L4::Cap< L4::Scheduler > scheduler() const noexcept</div><div class="ttdoc">Get the scheduler capability for the task.</div><div class="ttdef"><b>Definition</b> <a href="env_source.html#l00275">env:275</a></div></div>
|
|
<div class="ttc" id="aclassL4Re_1_1Env_html_a2706ca11e70845b0a29a5646c9fd54bc"><div class="ttname"><a href="classL4Re_1_1Env.html#a2706ca11e70845b0a29a5646c9fd54bc">L4Re::Env::env</a></div><div class="ttdeci">static Env const * env() noexcept</div><div class="ttdoc">Returns the initial environment for the current task.</div><div class="ttdef"><b>Definition</b> <a href="env_source.html#l00096">env:96</a></div></div>
|
|
<div class="ttc" id="agroup__l4__ipc__err__api_html_ga05c11e3e10b6c2aa941396ac2018899f"><div class="ttname"><a href="group__l4__ipc__err__api.html#ga05c11e3e10b6c2aa941396ac2018899f">l4_error</a></div><div class="ttdeci">long l4_error(l4_msgtag_t tag) L4_NOTHROW</div><div class="ttdoc">Get IPC error code if any or message tag label otherwise for an IPC call.</div><div class="ttdef"><b>Definition</b> <a href="l4_2sys_2ipc_8h_source.html#l00646">ipc.h:646</a></div></div>
|
|
<div class="ttc" id="agroup__l4__scheduler__api_html_ga97fc9fce99006ce7011a25bb8d014c8d"><div class="ttname"><a href="group__l4__scheduler__api.html#ga97fc9fce99006ce7011a25bb8d014c8d">l4_sched_param</a></div><div class="ttdeci">l4_sched_param_t l4_sched_param(unsigned prio, l4_umword_t quantum=0) L4_NOTHROW</div><div class="ttdoc">Construct scheduler parameter.</div><div class="ttdef"><b>Definition</b> <a href="scheduler_8h_source.html#l00289">scheduler.h:289</a></div></div>
|
|
</div><!-- fragment --><p class="endli"></p>
|
|
</li>
|
|
</ul>
|
|
<h4>Constraints on pthread_t, user-land capability slot, and kernel thread-object </h4>
|
|
<ul>
|
|
<li>
|
|
<p class="startli"><span class="tt">pthread_l4_cap()</span> is guaranteed to return the valid capability slot of the pthread (A) until <span class="tt">pthread_join()</span> or <span class="tt">pthread_detach()</span> is invoked on (A)'s <span class="tt">pthread_t</span>. </p>
|
|
<p class="endli"></p>
|
|
</li>
|
|
<li>
|
|
<p class="startli"><span class="tt">pthread_l4_cap()</span> exposes internal state of the pthread management, take the necessary precautions as you would for any shared data in concurrent environments. If you use <span class="tt">pthread_l4_cap()</span> guarding against concurrency issues is your duty. </p>
|
|
<p class="endli"></p>
|
|
</li>
|
|
<li>
|
|
<p class="startli">There is no guarantee that a valid capability slot points to a present capability. </p>
|
|
<p class="endli"></p>
|
|
</li>
|
|
<li>
|
|
<p class="startli"><b>Example</b></p>
|
|
<p class="endli">It is possible to obtain a valid thread capability slot and for <span class="tt"><a class="el" href="group__l4__task__api.html#ga829a1b5cb4d5dba33ffee57534a505af" title="Check whether a capability is present (refers to an object).">l4_task_cap_valid()</a></span> to return the capability as not present. The following example showcases a possible sequence of events. </p><div class="fragment"><div class="line"><span class="comment">// Assume: void some_func(void *)</span></div>
|
|
<div class="line">pthread_t pthread = <span class="keyword">nullptr</span>;</div>
|
|
<div class="line">pthread_create(&pthread, <span class="keyword">nullptr</span>, some_func, <span class="keyword">nullptr</span>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// pthread running some_func()</span></div>
|
|
<div class="line"><a class="code hl_typedef" href="group__l4__cap__api.html#ga1445e923ce73029130d569d6e69a4dd8">l4_cap_idx_t</a> cap_idx = pthread_l4_cap(pthread);</div>
|
|
<div class="line"><a class="code hl_function" href="group__l4__cap__api.html#ga539da15c2a1be4803ed7a3f3a5742194">l4_is_valid_cap</a>(cap_idx); <span class="comment">// ---> true</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordtype">long</span> valid = <a class="code hl_function" href="group__l4__task__api.html#ga829a1b5cb4d5dba33ffee57534a505af">l4_task_cap_valid</a>(L4RE_THIS_TASK_CAP, cap_idx).<a class="code hl_function" href="structl4__msgtag__t.html#a002076380a3f6e4f29a1f6b50ce2bde2">label</a>());</div>
|
|
<div class="line"><span class="comment">// valid == 1 --> capability object is present (refers to a kernel object).</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// some_func() exits</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line">cap_idx = pthread_l4_cap(pthread);</div>
|
|
<div class="line"><a class="code hl_function" href="group__l4__cap__api.html#ga539da15c2a1be4803ed7a3f3a5742194">l4_is_valid_cap</a>(cap_idx); <span class="comment">// ---> true</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line">valid = <a class="code hl_function" href="group__l4__task__api.html#ga829a1b5cb4d5dba33ffee57534a505af">l4_task_cap_valid</a>(L4RE_THIS_TASK_CAP, cap_idx).<a class="code hl_function" href="structl4__msgtag__t.html#a002076380a3f6e4f29a1f6b50ce2bde2">label</a>());</div>
|
|
<div class="line"><span class="comment">// valid == 0 --> capability object is not present (refers to no kernel object).</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"> </div>
|
|
<div class="line">pthread_join(pthread, <span class="keyword">nullptr</span>); <span class="comment">// invalidates the cap slot and frees</span></div>
|
|
<div class="line"> <span class="comment">// the pthread's data structures</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// using cap_idx here is undefined behavior.</span></div>
|
|
<div class="ttc" id="agroup__l4__cap__api_html_ga1445e923ce73029130d569d6e69a4dd8"><div class="ttname"><a href="group__l4__cap__api.html#ga1445e923ce73029130d569d6e69a4dd8">l4_cap_idx_t</a></div><div class="ttdeci">unsigned long l4_cap_idx_t</div><div class="ttdoc">Capability selector type.</div><div class="ttdef"><b>Definition</b> <a href="l4_2sys_2types_8h_source.html#l00336">types.h:336</a></div></div>
|
|
<div class="ttc" id="agroup__l4__cap__api_html_ga539da15c2a1be4803ed7a3f3a5742194"><div class="ttname"><a href="group__l4__cap__api.html#ga539da15c2a1be4803ed7a3f3a5742194">l4_is_valid_cap</a></div><div class="ttdeci">unsigned l4_is_valid_cap(l4_cap_idx_t c) L4_NOTHROW</div><div class="ttdoc">Test if a capability selector is a valid selector.</div><div class="ttdef"><b>Definition</b> <a href="l4_2sys_2types_8h_source.html#l00393">types.h:393</a></div></div>
|
|
<div class="ttc" id="agroup__l4__task__api_html_ga829a1b5cb4d5dba33ffee57534a505af"><div class="ttname"><a href="group__l4__task__api.html#ga829a1b5cb4d5dba33ffee57534a505af">l4_task_cap_valid</a></div><div class="ttdeci">l4_msgtag_t l4_task_cap_valid(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW</div><div class="ttdoc">Check whether a capability is present (refers to an object).</div><div class="ttdef"><b>Definition</b> <a href="l4_2sys_2task_8h_source.html#l00484">task.h:484</a></div></div>
|
|
<div class="ttc" id="astructl4__msgtag__t_html_a002076380a3f6e4f29a1f6b50ce2bde2"><div class="ttname"><a href="structl4__msgtag__t.html#a002076380a3f6e4f29a1f6b50ce2bde2">l4_msgtag_t::label</a></div><div class="ttdeci">long label() const L4_NOTHROW</div><div class="ttdoc">Get the protocol value.</div><div class="ttdef"><b>Definition</b> <a href="l4_2sys_2types_8h_source.html#l00158">types.h:158</a></div></div>
|
|
</div><!-- fragment --> </li>
|
|
</ul>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
</div><!-- doc-content -->
|
|
<div id="page-nav" class="page-nav-panel">
|
|
<div id="page-nav-resize-handle"></div>
|
|
<div id="page-nav-tree">
|
|
<div id="page-nav-contents">
|
|
</div><!-- page-nav-contents -->
|
|
</div><!-- page-nav-tree -->
|
|
</div><!-- page-nav -->
|
|
</div><!-- container -->
|
|
<!-- HTML footer for doxygen 1.9.1-->
|
|
<!-- start footer part -->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
<li class="navelem"><a href="l4re_concepts.html">Programming for L4Re</a></li>
|
|
<li class="footer">Generated on <span class="timestamp"></span> for L4Re Operating System Framework by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|