Commit 8043a4f8 authored by Jens Gustedt's avatar Jens Gustedt
Browse files

integrate html pages into repository for gforge -> gitlab transition

parent 4ea6c4d8
Pipeline #152989 passed with stage
in 27 seconds

Too many changes to show.

To preserve performance only 1000 of 1000+ files are displayed.
# This file is a template, and might need editing before it works on your project.
# Full project: https://gitlab.com/pages/plain-html
pages:
stage: deploy
script:
- mkdir .public
- cp -r gforge-p99/* .public
- cp -r p99-html .public
- mv .public public
artifacts:
paths:
- public
only:
- master
<!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.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>P99: Data Structures</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="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" />
</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="projectalign" style="padding-left: 0.5em;">
<div id="projectname">P99
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- 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">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Data Structures</div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock">Here are the data structures with brief descriptions:</div><div class="directory">
<table class="directory">
<tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__callback__el.html" target="_self">p99_callback_el</a></td><td class="desc"></td></tr>
<tr id="row_1_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__callback__stack.html" target="_self">p99_callback_stack</a></td><td class="desc">A data structure to register callbacks </td></tr>
<tr id="row_2_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__cm.html" target="_self">p99_cm</a></td><td class="desc"></td></tr>
<tr id="row_3_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__count.html" target="_self">p99_count</a></td><td class="desc">A counter that allows atomic increment and decrement and a wait for the value 0 </td></tr>
<tr id="row_4_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__event.html" target="_self">p99_event</a></td><td class="desc"></td></tr>
<tr id="row_5_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__futex.html" target="_self">p99_futex</a></td><td class="desc">A counter similar to a conditional variable that allows atomic increment and decrement and to wait for the atomic compare and exchange for a specific value </td></tr>
<tr id="row_6_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__futex__c11.html" target="_self">p99_futex_c11</a></td><td class="desc">The structure that is used in the fallback implementation of <a class="el" href="structp99__futex.html" title="A counter similar to a conditional variable that allows atomic increment and decrement and to wait fo...">p99_futex</a> on non-linux systems </td></tr>
<tr id="row_7_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__iterator.html" target="_self">p99_iterator</a></td><td class="desc">Iterate over a series events that are signaled by other threads </td></tr>
<tr id="row_8_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__notifier.html" target="_self">p99_notifier</a></td><td class="desc">Set a flag and notify other threads that an event has occurred </td></tr>
<tr id="row_9_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__once__flag.html" target="_self">p99_once_flag</a></td><td class="desc">Complete object type that holds a flag for use by <a class="el" href="p99__threads_8h_aaa550d37184f716ea697c3e13993aae1.html#aaa550d37184f716ea697c3e13993aae1" title="Call a function FUNC exactly once, optionally providing it with argument ARG.">p99_call_once</a> </td></tr>
<tr id="row_10_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__rwl.html" target="_self">p99_rwl</a></td><td class="desc">A simple rwlock implementation </td></tr>
<tr id="row_11_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__tss.html" target="_self">p99_tss</a></td><td class="desc">A stub structure to hold a thread local variable if <a class="el" href="group__C11__keywords_gad4d9b405bcbffaf0d4dae6166c18aa1e.html#gad4d9b405bcbffaf0d4dae6166c18aa1e" title="Declare a thread-local variable.">thread_local</a> is not available </td></tr>
<tr id="row_12_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structp99__uf.html" target="_self">p99_uf</a></td><td class="desc"></td></tr>
</table>
</div><!-- directory -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>
<!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.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>P99: C99 features</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="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" />
</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="projectalign" style="padding-left: 0.5em;">
<div id="projectname">P99
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- 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">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">C99 features </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>As extensions to C89, C99 offers some features that improve the possibilities of programming efficiently and portably at the same time. There are four of these new concepts that are particularly important for P99 and without them P99 wouldn't be possible.</p><ul>
<li><a class="el" href="c99.html#variadic">Variadic macros</a></li>
<li><a class="el" href="c99.html#inline">Inline functions</a></li>
<li><a class="el" href="c99.html#initializers">Designated initializers</a></li>
<li><a class="el" href="c99.html#compound">Compound literals</a></li>
<li><a class="el" href="c99.html#pragma">Pragmas inside macros</a></li>
</ul>
<h1><a class="anchor" id="variadic"></a>
Variadic macros</h1>
<p>The preprocessor now has a feature that previously only C functions had: a macro may accept an argument list that may vary in size. As with functions, such a macro is defined with &lsquo;...&rsquo; in the argument list to indicate a list following the initial, named, arguments:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define TOTO(NAME, ...) NAME[__VA_ARGS__]</span></div>
</div><!-- fragment --><p>The variable-length list is then referred to using the reserved identifier <code><b>VA_ARGS</b></code>.</p>
<p>This functionality of C99 allows us e.g to implement macros for <a class="el" href="utilities.html#defaults">Default arguments to functions</a> and to perform <a class="el" href="programming.html#unrolling">Code Unrolling</a>.</p>
<h1><a class="anchor" id="inline"></a>
Inline functions</h1>
<p>The new keyword <code>inline</code> is borrowed from C++ with some slightly changed semantics. The important part for P99 is that functions can be <em>defined</em> in a header file (and not only declared) when specified as <code>inline</code>.</p>
<p>This allows us to define small wrappers in header files using macros, without generating conflicts in different compilation units. By that we can avoid one of the major drawbacks of C macro programming: a macro cannot <em>define</em> another macro. In addition functions, when compared to macros, have other advantages</p><ul>
<li>they are typesafe</li>
<li>their arguments are evaluated exactly once</li>
</ul>
<h1><a class="anchor" id="initializers"></a>
Designated initializers</h1>
<p>In C89, initialization of structures can be tedious and error prone: </p><div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>toto toto;</div>
<div class="line"><span class="keyword">struct </span>toto {</div>
<div class="line"> <span class="keywordtype">unsigned</span> a;</div>
<div class="line"> <span class="keywordtype">double</span> b;</div>
<div class="line">};</div>
<div class="line">.</div>
<div class="line">.</div>
<div class="line">toto A = { 0, 1 };</div>
</div><!-- fragment --><p>Components are initialized in the order of the type declaration. Here the <code>0</code> in the initializer is used to initialize the component <code>A.a</code> and the <code>1</code> for A.b.</p>
<p>Whenever the structure <code>toto</code> changes during the development process, we would have to revisit <em>all</em> initializations to see whether or not they remain consistent:</p><ul>
<li>if the order of components <code>a</code> and <code>b</code> changes, the order of the expressions must be inverted</li>
<li>if we insert an element before <code>a</code> or <code>b</code>, the initialization of <code>b</code> by <code>1</code> in the example is replaced by the default initialization, namely <code>0.0</code>.</li>
</ul>
<p>Keeping track of these may be particularly difficult if the components are of similar types, such that an initializer for one is valid for the other.</p>
<p>With designated initializers this situation changes substantially: </p><div class="fragment"><div class="line">toto A = { .a = 0, .b = 1 };</div>
</div><!-- fragment --><p>By this means we avoid all of the problems mentioned above. This scheme is robust against reordering and insertion of components. In a certain sense it is also robust against the renaming of components: all initializations will then simply fail at compile time, so it is easy to identify problems.</p>
<p>For a more detailed discussion of initialization and P99 see <a class="el" href="conventions.html#variableInit">Variable initialization</a>.</p>
<h1><a class="anchor" id="compound"></a>
Compound literals</h1>
<p>A compound literal is syntactically given as a compound initializer and a cast such as </p><div class="fragment"><div class="line">(<span class="keywordtype">int</span>[2]){ 4, 5}</div>
<div class="line">(T){ .d = 1, .a = 10 }.</div>
</div><!-- fragment --><p>It is best seen as defining a temporary object of the requested type, initialized using the same rules that apply to a named variable of that type.</p>
<ul>
<li>Such unnamed temporary objects can be initialized on the fly, e.g as the arguments to functions, and they live until the end of the block in which they are defined.</li>
<li>They define an lvalue from which an address can be taken.</li>
<li>Unless the type of the cast is defined with &lsquo;const&rsquo; the content of such a variable is modifiable.</li>
</ul>
<p>Example: The following code returns the pointer to a character array that is initialized with all <code>&lsquo;a&rsquo;</code> and a terminating <code>0</code> character. The array is a valid object until the program leaves the current block. </p><div class="fragment"><div class="line"><span class="keywordtype">char</span> <span class="keyword">const</span>*<span class="keyword">const</span> hui = memset((<span class="keywordtype">char</span>[256]){0}, <span class="charliteral">&#39;a&#39;</span>, 255);</div>
</div><!-- fragment --><p>It would be equivalent to the following </p><div class="fragment"><div class="line"><span class="keywordtype">char</span> tmp[256] = { 0 };</div>
<div class="line"><span class="keywordtype">char</span> <span class="keyword">const</span>*<span class="keyword">const</span> hui = memset(tmp, <span class="charliteral">&#39;a&#39;</span>, 255);</div>
</div><!-- fragment --><p>Using the compound literal here has the advantage that no other non-const reference to the temporary is exposed.</p>
<p>The compound literal syntax is not always very easy to read; in fact it might even hurt your eyes. P99 gives you a shortcut for compound literals that are initialized from the all <code>0</code> initializer. With that the above could have been written:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> <span class="keyword">const</span>*<span class="keyword">const</span> hui = memset(<a class="code" href="group__integers_gab9cabeffe9c354f9775a53a79313d71b.html#gab9cabeffe9c354f9775a53a79313d71b">P99_LVAL</a>(<span class="keywordtype">char</span>[256]), <span class="charliteral">&#39;a&#39;</span>, 255);</div>
</div><!-- fragment --><h1><a class="anchor" id="hide"></a>
Macros that hide a function</h1>
<p>Per se, this is not a new feature of C99 but had been present before. The preprocessor has two special rules, one that applies generally to macros and the other that applies only to functional macros:</p>
<ol type="1">
<li>If during expansion of a macro XXX the token XXX is found, it is not expanded. So there is no recursion in C macros.</li>
<li>If a functional macro YYY is found without a following opening parenthesis it is not expanded.</li>
</ol>
<p>Theses features can be used to define a macro and another identifier that have the same name. It is sometimes used for a test if some functionality is present on a platform. E.g on my computer I have</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define stdin stdin</span></div>
</div><!-- fragment --><p>This can be used as follows </p><div class="fragment"><div class="line"><span class="preprocessor">#ifdef stdin</span></div>
<div class="line"> <span class="comment">// Do something for a hosted environment</span></div>
<div class="line"> <span class="comment">// Use stdin as usual</span></div>
<div class="line"><span class="preprocessor">#else</span></div>
<div class="line"> <span class="comment">// Do something for a free standing environment</span></div>
<div class="line"> <span class="comment">// We don&#39;t have stdin at all, write to a log file or so.</span></div>
<div class="line"><span class="preprocessor">#endif</span></div>
</div><!-- fragment --><p>But we may equally use this technique for a function symbol. POSIX explicitly allows this for example for the functions in <em>stdio.h</em> </p>
<center> <em> The following shall be declared as functions and may also be defined as macros.<br />
Function prototypes shall be provided. </em> </center><p>Lets have a look at a randomly selected function from stdio and suppose it would be given as follows: </p><div class="fragment"><div class="line"><span class="keywordtype">int</span> putc(<span class="keywordtype">int</span>, FILE *);</div>
<div class="line"><span class="preprocessor">#define putc(C, F) (is_it_special(C) ? do_something_clever(C, F) : putc(C, F) )</span></div>
</div><!-- fragment --><p>(Yes this evaluates <code>C</code> twice.) With that, these uses of <code>putc</code> are still valid: </p><div class="fragment"><div class="line"><span class="comment">// Use the macro and implicitly the function, relies on rule 1</span></div>
<div class="line">putc(<span class="charliteral">&#39;A&#39;</span>, stdout);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Just use the function not the macro, relies on rule 2</span></div>
<div class="line">(putc)(<span class="charliteral">&#39;A&#39;</span>, stdout);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Get the address of putc and store it in my_putc, relies on rule 2</span></div>
<div class="line">int (*my_putc)(int, FILE*) = &amp;putc;</div>
</div><!-- fragment --><p>The example above with <code>putc</code> has a particular pitfall if we have the above definitions in a header file and then include this file at the place where we define the function:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;stdio.h&gt;</span></div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> putc(<span class="keywordtype">int</span>, FILE *) {</div>
<div class="line"> <span class="comment">// do the right thing here</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>This will simply explode since the preprocessor will expand the functional reference to <code>putc</code>. This can be explicitly avoided by undefining the macro before the definition, but for this the implementor of <code>putc</code> has to know that it is also a macro.</p>
<p>With P99, we use this technique to <em>overload</em> a function to provide it with <a class="el" href="utilities.html#defaults">Default arguments to functions</a>. A macro defined in that way will avoid this pitfall: if it is called with the same number of arguments (or more) that are all non-empty, it will produce the same token sequence as if the macro had not been defined.</p>
<h2><a class="anchor" id="pragma"></a>
Pragmas inside macros</h2>
<p>The traditional approach in C had been to specify meta information for the compiler in so called pragmas: </p><div class="fragment"><div class="line"><span class="preprocessor">#pragma omp parallel for</span></div>
<div class="line"><span class="preprocessor">for (size_t i = 0; i &lt; n; ++i) c[i] += a[i] * b[i];</span></div>
</div><!-- fragment --><p>The inconvenience of such a construct is that it has always to be on a line of its own and cannot be placed in a macro. For that reason most compilers provided extensions that let the programmer place meta information more precisely at some specific point of the code, e.g gcc has an <code><b>attribute</b></code> extension for that.</p>
<p>C99 adds a keyword to overcome that difficulty and to normalize the link between macros and <code>#pragma:</code> <code>_Pragma</code>. </p><div class="fragment"><div class="line">_Pragma(<span class="stringliteral">&quot;omp parallel for&quot;</span>) <a class="code" href="group__preprocessor__blocks_gacdcdbf020344038c9fa0de0a7d8fb7ec.html#gacdcdbf020344038c9fa0de0a7d8fb7ec">for</a> (<span class="keywordtype">size_t</span> <a class="code" href="p99__getopt_8h_a57a586489a0c58f01ad0e9d31e7c2eda.html#a57a586489a0c58f01ad0e9d31e7c2eda">i</a> = 0; <a class="code" href="p99__getopt_8h_a57a586489a0c58f01ad0e9d31e7c2eda.html#a57a586489a0c58f01ad0e9d31e7c2eda">i</a> &lt; n; ++<a class="code" href="p99__getopt_8h_a57a586489a0c58f01ad0e9d31e7c2eda.html#a57a586489a0c58f01ad0e9d31e7c2eda">i</a>) c[<a class="code" href="p99__getopt_8h_a57a586489a0c58f01ad0e9d31e7c2eda.html#a57a586489a0c58f01ad0e9d31e7c2eda">i</a>] += a[<a class="code" href="p99__getopt_8h_a57a586489a0c58f01ad0e9d31e7c2eda.html#a57a586489a0c58f01ad0e9d31e7c2eda">i</a>] * b[<a class="code" href="p99__getopt_8h_a57a586489a0c58f01ad0e9d31e7c2eda.html#a57a586489a0c58f01ad0e9d31e7c2eda">i</a>];</div>
</div><!-- fragment --><p> P99 uses this feature for extensions concerning OpenMP, in particular the <a class="el" href="group__preprocessor__blocks_gaaedc09a65ee738c4902e8c1bf8e415fb.html#gaaedc09a65ee738c4902e8c1bf8e415fb" title="Declare a for loop for which all iterations can be run independently and out of order.">P99_PARALLEL_FOR</a> and <a class="el" href="group__preprocessor__blocks_gadc2bef2dceeff9802aeb2ce5254876b0.html#gadc2bef2dceeff9802aeb2ce5254876b0" title="A multi-index for loop who&#39;s dependent statement or block may be executed out of order.">P99_PARALLEL_FORALL</a> macros. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<div class="ttc" id="agroup__integers_gab9cabeffe9c354f9775a53a79313d71b_html_gab9cabeffe9c354f9775a53a79313d71b"><div class="ttname"><a href="group__integers_gab9cabeffe9c354f9775a53a79313d71b.html#gab9cabeffe9c354f9775a53a79313d71b">P99_LVAL</a></div><div class="ttdeci">#define P99_LVAL(...)</div><div class="ttdoc">Define an lvalue of type T, where T is the first parameter in the variable parameter list.</div><div class="ttdef"><b>Definition:</b> <a href="p99__int_8h_source.html#l01076">p99_int.h:1076</a></div></div>
<div class="ttc" id="agroup__preprocessor__blocks_gacdcdbf020344038c9fa0de0a7d8fb7ec_html_gacdcdbf020344038c9fa0de0a7d8fb7ec"><div class="ttname"><a href="group__preprocessor__blocks_gacdcdbf020344038c9fa0de0a7d8fb7ec.html#gacdcdbf020344038c9fa0de0a7d8fb7ec">for</a></div><div class="ttdeci">for(_Bool p00=1;p00 &amp;&amp;({ { __VA_ARGS__ } 1;});p00=0) typedef enum p00_uncase_enum</div><div class="ttdoc">Prefer the statements in the argument list over the statement or block that follows.</div><div class="ttdef"><b>Definition:</b> <a href="p99__block_8h_source.html#l00319">p99_block.h:319</a></div></div>
<div class="ttc" id="ap99__getopt_8h_a57a586489a0c58f01ad0e9d31e7c2eda_html_a57a586489a0c58f01ad0e9d31e7c2eda"><div class="ttname"><a href="p99__getopt_8h_a57a586489a0c58f01ad0e9d31e7c2eda.html#a57a586489a0c58f01ad0e9d31e7c2eda">i</a></div><div class="ttdeci">P00_CLAUSE2 i(_Pragma(&quot;weak p00_getopt_comp&quot;))(_Pragma(&quot;weak p00_getopt_comp </div></div>
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>
<!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.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>P99: Data Structure Index</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="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" />
</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="projectalign" style="padding-left: 0.5em;">
<div id="projectname">P99
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- 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">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Data Structure Index</div> </div>
</div><!--header-->
<div class="contents">
<div class="qindex"><a class="qindex" href="#letter_c">c</a>&#160;|&#160;<a class="qindex" href="#letter_e">e</a>&#160;|&#160;<a class="qindex" href="#letter_f">f</a>&#160;|&#160;<a class="qindex" href="#letter_i">i</a>&#160;|&#160;<a class="qindex" href="#letter_n">n</a>&#160;|&#160;<a class="qindex" href="#letter_o">o</a>&#160;|&#160;<a class="qindex" href="#letter_r">r</a>&#160;|&#160;<a class="qindex" href="#letter_t">t</a>&#160;|&#160;<a class="qindex" href="#letter_u">u</a></div>
<table class="classindex">
<tr><td rowspan="2" valign="bottom"><a name="letter_c"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;c&#160;&#160;</div></td></tr></table>
</td>
<td rowspan="2" valign="bottom"><a name="letter_f"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;f&#160;&#160;</div></td></tr></table>
</td>
<td rowspan="2" valign="bottom"><a name="letter_n"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;n&#160;&#160;</div></td></tr></table>
</td>
<td rowspan="2" valign="bottom"><a name="letter_t"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;t&#160;&#160;</div></td></tr></table>
</td>
</tr>
<tr><td></td></tr>
<tr><td valign="top"><a class="el" href="structp99__callback__el.html">p99_callback_el</a>&#160;&#160;&#160;</td>
<td valign="top"><a class="el" href="structp99__futex.html">p99_futex</a>&#160;&#160;&#160;</td>
<td valign="top"><a class="el" href="structp99__notifier.html">p99_notifier</a>&#160;&#160;&#160;</td>
<td valign="top"><a class="el" href="structp99__tss.html">p99_tss</a>&#160;&#160;&#160;</td>
</tr>
<tr><td valign="top"><a class="el" href="structp99__callback__stack.html">p99_callback_stack</a>&#160;&#160;&#160;</td>
<td valign="top"><a class="el" href="structp99__futex__c11.html">p99_futex_c11</a>&#160;&#160;&#160;</td>
<td rowspan="2" valign="bottom"><a name="letter_o"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;o&#160;&#160;</div></td></tr></table>
</td>
<td rowspan="2" valign="bottom"><a name="letter_u"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;u&#160;&#160;</div></td></tr></table>
</td>
</tr>
<tr><td valign="top"><a class="el" href="structp99__cm.html">p99_cm</a>&#160;&#160;&#160;</td>
<td rowspan="2" valign="bottom"><a name="letter_i"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;i&#160;&#160;</div></td></tr></table>
</td>
</tr>
<tr><td valign="top"><a class="el" href="structp99__count.html">p99_count</a>&#160;&#160;&#160;</td>
<td valign="top"><a class="el" href="structp99__once__flag.html">p99_once_flag</a>&#160;&#160;&#160;</td>
<td valign="top"><a class="el" href="structp99__uf.html">p99_uf</a>&#160;&#160;&#160;</td>
</tr>
<tr><td rowspan="2" valign="bottom"><a name="letter_e"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;e&#160;&#160;</div></td></tr></table>
</td>
<td valign="top"><a class="el" href="structp99__iterator.html">p99_iterator</a>&#160;&#160;&#160;</td>
<td rowspan="2" valign="bottom"><a name="letter_r"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;r&#160;&#160;</div></td></tr></table>
</td>
<td></td></tr>
<tr><td></td><td></td></tr>
<tr><td valign="top"><a class="el" href="structp99__event.html">p99_event</a>&#160;&#160;&#160;</td>
<td></td><td valign="top"><a class="el" href="structp99__rwl.html">p99_rwl</a>&#160;&#160;&#160;</td>
<td></td></tr>
<tr><td></td><td></td><td></td><td></td></tr>
</table>
<div class="qindex"><a class="qindex" href="#letter_c">c</a>&#160;|&#160;<a class="qindex" href="#letter_e">e</a>&#160;|&#160;<a class="qindex" href="#letter_f">f</a>&#160;|&#160;<a class="qindex" href="#letter_i">i</a>&#160;|&#160;<a class="qindex" href="#letter_n">n</a>&#160;|&#160;<a class="qindex" href="#letter_o">o</a>&#160;|&#160;<a class="qindex" href="#letter_r">r</a>&#160;|&#160;<a class="qindex" href="#letter_t">t</a>&#160;|&#160;<a class="qindex" href="#letter_u">u</a></div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>
<!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.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>P99: Programming conventions</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="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" />
</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="projectalign" style="padding-left: 0.5em;">
<div id="projectname">P99
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- 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">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Programming conventions </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>P99 uses some programming conventions that might be interesting for projects that include its header files.</p>
<ol type="1">
<li><a class="el" href="conventions.html#standardconformance">Standard conformance</a></li>
<li><a class="el" href="conventions.html#OSindependence">Operating system independence</a></li>
<li><a class="el" href="conventions.html#prefixes">Defining identifiers</a></li>
<li><a class="el" href="conventions.html#variableInit">Variable initialization</a></li>
<li><a class="el" href="conventions.html#temporaries">Use of temporary lvalues</a></li>
</ol>
<h1><a class="anchor" id="standardconformance"></a>
Standard conformance</h1>
<p>Where we can, we try to conform to the C99 standard and to mark extensions clearly, if we use them.</p>
<h2><a class="anchor" id="UB"></a>
Undefined behavior</h2>
<p>The C specification has many places where it explicitly says that under certain circumstances the behavior of the resulting code is undefined. Generally this means that a conforming C implementation is not obliged to capture such circumstances and for code that uses such undefined behavior might do anything, from do-the-right-thing or crashing to eating your hard drive.</p>
<p>P99 should not produce any such undefined behavior.</p>
<h2><a class="anchor" id="IB"></a>
Implementation specific behavior</h2>
<p>In other places the standard leaves room for C implementations to specify certain behavior.</p>
<p>P99 tries not use any special feature that might be the result of such implementation specific behavior. This concerns in particular arithmetic on integer types. Here the standard allows certain variations:</p>
<ul>
<li>padding bits: integer types may have padding bits that do not count towards their width (# of significant bits) but do count towards their size (storage requirement). So generally we have to be careful to not use expressions that use <code>sizeof</code> expressions for shifts.</li>
<li>encoding of signed types: C99 allows three different encodings for signed integers. We do not assume any of these encodings but build macros that are valid for all of them.</li>
<li>signed under- and overflow: arithmetic on signed integer types may under- or overflow and C99 leaves it to the implementation whether or not this silently wraps around or triggers a signal. All expressions that involve signed types should be such that they avoid this implementation specific behavior. E.g to compute the absolute value of a negative <code>int</code> <code>a</code> we would use <code>-</code>(unsigned)a. This expression guarantees that the result is well defined even for corner cases (here <code>a</code> being <code>INT_MIN</code> in two's complement representation) and will never trigger a range error.</li>
<li>We do not suppose the presence of the <code>typedefs</code> <code>uintptr_t</code> or <code>intptr_t</code> since they are optional in C. In particular we may not assume that there is any sensible conversion between pointers and integer types.</li>
</ul>
<h1><a class="anchor" id="prefixes"></a>
Defining identifiers</h1>
<p>Macro names that implement the functionality of P99 are generally uppercase. Exceptions from that rule are <a class="el" href="c99.html#hide">Macros that hide a function</a>. All other identifiers are lowercase.</p>
<p>P99 uses the common prefixes <code>P99_</code> and <code>p99_</code> for macros and other identifiers, respectively. Future P99 versions could define new identifiers with these prefixes. If you include any of the P99 files, avoid using these prefixes for your own identifiers.</p>
<p>The same rule holds for the prefixes <code>P00_and</code> <code>p00_</code> which are used for auxilliary identifiers that need not be documented. Such identifiers are ignored in the doxygen documentation.</p>
<h1><a class="anchor" id="OSindependence"></a>
Operating system independence</h1>
<p>The P99 macros and functions as such should be independent of the execution system and compiler. Nevertheless, for the time being they are only tested on POSIX systems, namely Linux. So if problems are discovered with other systems, please let us know.</p>
<p>In contrast to that general policy, there is <em>one</em> file that is dependent on the system, <a class="el" href="p99__posix__default_8h.html">p99_posix_default.h</a>. As the name indicates it is designed for POSIX systems and provides default arguments for some POSIX functions.</p>
<p>Also, some of the examples throughout this documentation are taken from programs that would typically run on POSIX systems. We hope that such examples are obvious and don't need explanation for programmers of other systems.</p>
<h1><a class="anchor" id="variableInit"></a>
Variable initialization</h1>
<p>Where possible, P99 uses initializers to initialize variables. For each type <code>T</code> where such an initialization is possible, there should be a macro <code>T_INITIALIZER</code> that does a standard initialization. Such a macro should use the <a class="el" href="c99.html#initializers">Designated initializers</a> scheme.</p>
<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>toto toto;</div>
<div class="line"><span class="keyword">struct </span>toto { <span class="keywordtype">double</span> a; <span class="keywordtype">unsigned</span> b; };</div>
<div class="line"><span class="preprocessor">#define TOTO_INITIALIZER { .a = 0.0; .b = 0u }</span></div>
</div><!-- fragment --><p>In case you want the default behavior of C, namely that all fields are recursively initialized with <code>0</code> then you could just use </p><div class="fragment"><div class="line"><span class="preprocessor">#define TOTO_INITIALIZER P99_INIT</span></div>
</div><!-- fragment --><p> to make this choice explicit.</p>
<p>Such initializers can easily be assembled together </p><div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>tutu tutu;</div>
<div class="line"><span class="keyword">struct </span>tutu { toto A; <span class="keywordtype">bool</span> c; };</div>
<div class="line"><span class="preprocessor">#define TUTU_INITIALIZER(VAL) { .A = TOTO_INITIALIZER, .c = (VAL) }</span></div>
</div><!-- fragment --><p>As you can see in this example, <code>INITIALIZER</code> can be a &lsquo;normal&rsquo; macro or a function like macro.</p>
<p>For dynamic initialization we assume that an &lsquo;init&rsquo; function exists that</p><ul>
<li>takes a pointer as a first argument</li>
<li>tests for the validity of that pointer, and</li>
<li>returns exactly the same pointer <div class="fragment"><div class="line">toto* toto_init(toto* t) {</div>
<div class="line"> <span class="comment">// assign from a compound literal</span></div>
<div class="line"> <span class="keywordflow">if</span> (t) *t = (toto)TOTO_INITIALIZER;</div>
<div class="line"> <span class="keywordflow">return</span> t;</div>
<div class="line">}</div>
<div class="line">tutu* tutu_init(tutu* t, <span class="keywordtype">bool</span> val) {</div>
<div class="line"> <span class="keywordflow">if</span> (t) {</div>
<div class="line"> toto_init(&amp;(t-&gt;A));</div>
<div class="line"> t-&gt;c = val;</div>
<div class="line"> }</div>
<div class="line"> <span class="keywordflow">return</span> t;</div>
<div class="line">}</div>
</div><!-- fragment --></li>