diff --git a/README.html b/README.html index 5d2917f824fd87b763268965c367c44a7649e4b1..880a6bec543de0d4eacaa347645033ac6de0059f 100644 --- a/README.html +++ b/README.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> -<!-- 2020-09-30 Mi 11:54 --> +<!-- 2020-09-30 Mi 12:05 --> <meta http-equiv="Content-Type" content="text/html;charset=utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title><code>defer</code> reference implementation for C</title> @@ -235,82 +235,82 @@ for the JavaScript code in this tag. <h2>Table of Contents</h2> <div id="text-table-of-contents"> <ul> -<li><a href="#orgc76741f">1. Description</a> +<li><a href="#org3f3c69c">1. Description</a> <ul> -<li><a href="#org49288c5">1.1. An example for static cleanup handling</a></li> -<li><a href="#org9df350d">1.2. Dynamic versus static control flow for deferred statements</a></li> -<li><a href="#orgfc01729">1.3. Guarded blocks for function bodies</a></li> -<li><a href="#org77765b1">1.4. Triggering the execution of deferred statements</a></li> -<li><a href="#org0c3f94e">1.5. Execution of deferred statements and panic recovery</a></li> -<li><a href="#org2c0657b">1.6. Improved usage of certain C library features</a> +<li><a href="#orgdd83544">1.1. An example for static cleanup handling</a></li> +<li><a href="#orgd578d73">1.2. Dynamic versus static control flow for deferred statements</a></li> +<li><a href="#org928056f">1.3. Guarded blocks for function bodies</a></li> +<li><a href="#org0e872fe">1.4. Triggering the execution of deferred statements</a></li> +<li><a href="#org36720af">1.5. Execution of deferred statements and panic recovery</a></li> +<li><a href="#orga3bf14b">1.6. Improved usage of certain C library features</a> <ul> -<li><a href="#orgbf63516">1.6.1. Advantages of <code>defer</code> for error handling</a></li> +<li><a href="#orgf85ed48">1.6.1. Advantages of <code>defer</code> for error handling</a></li> </ul> </li> -<li><a href="#org5afeb57">1.7. Provided interfaces</a></li> -<li><a href="#orga890eed">1.8. Error codes</a></li> -<li><a href="#org9fbbc6a">1.9. Interoperability with C++</a></li> -<li><a href="#org9b1dca6">1.10. Implementation specifics</a> +<li><a href="#orgdedd146">1.7. Provided interfaces</a></li> +<li><a href="#org8faa70f">1.8. Error codes</a></li> +<li><a href="#org1c3d495">1.9. Interoperability with C++</a></li> +<li><a href="#org63858b8">1.10. Implementation specifics</a> <ul> -<li><a href="#org1dfca5c">1.10.1. Extension: using computed <code>goto</code></a></li> -<li><a href="#orge3f7e7b">1.10.2. Extension: Captured values for <code>defer</code></a></li> -<li><a href="#org678717e">1.10.3. Omission of <code>guard</code> for function body</a></li> -<li><a href="#org964dcb1">1.10.4. Synchronization of local variables</a></li> -<li><a href="#orgcb0fd98">1.10.5. Caveats</a></li> +<li><a href="#orgf1997e5">1.10.1. Extension: using computed <b><code>goto</code></b></a></li> +<li><a href="#orgf9be3d6">1.10.2. Extension: Captured values for <code>defer</code></a></li> +<li><a href="#org97d843e">1.10.3. Omission of <code>guard</code> for function body</a></li> +<li><a href="#orgc101b01">1.10.4. Synchronization of local variables</a></li> +<li><a href="#orgcada0c0">1.10.5. Caveats</a></li> </ul> </li> </ul> </li> -<li><a href="#orgd7800b3">2. Reference manual</a> +<li><a href="#orgabe268d">2. Reference manual</a> <ul> -<li><a href="#orgd674893">2.1. <code>defer</code>: ensure the execution of the deferred statement at the end of the guarded block</a> +<li><a href="#orgf117b3c">2.1. *=defer=: ensure the execution of the deferred statement at the end of the guarded block</a> <ul> -<li><a href="#orgb93c1b9">2.1.1. <code>defer_capture</code>: capture some variables and defer the execution of the depending statement</a></li> +<li><a href="#org81d6122">2.1.1. <code>defer_capture</code>: capture some variables and defer the execution of the depending statement</a></li> </ul> </li> -<li><a href="#org071cfc0">2.2. <code>guard</code>: mark a whole block as "guarded" and as using the defer mechanism.</a></li> -<li><a href="#org578f326">2.3. <code>panic</code>: Unwind the whole call stack and execute the deferred statements on the way down</a> +<li><a href="#org0441242">2.2. *=guard=: mark a whole block as "guarded" and as using the defer mechanism.</a></li> +<li><a href="#org1e0d12e">2.3. *=panic=: Unwind the whole call stack and execute the deferred statements on the way down</a> <ul> -<li><a href="#orgb5669e0">2.3.1. <code>defer_assert</code>: assert a runtime condition or <code>panic</code></a></li> +<li><a href="#org8bdf3fc">2.3.1. <code>defer_assert</code>: assert a runtime condition or <code>panic</code></a></li> </ul> </li> -<li><a href="#org95d66b5">2.4. Termination functions</a> +<li><a href="#org78dd25a">2.4. Termination functions</a> <ul> -<li><a href="#orgcdc21a2">2.4.1. <code>DEFER_NO_WRAP</code>: force the usage of the unwrapped termination functions</a></li> +<li><a href="#orga60bf93">2.4.1. <code>DEFER_NO_WRAP</code>: force the usage of the unwrapped termination functions</a></li> </ul> </li> -<li><a href="#org914b48c">2.5. <code>recover</code>: stop a panic and/or return such the error code</a> +<li><a href="#org8dc3e9b">2.5. *=recover=: stop a panic and/or return such the error code</a> <ul> -<li><a href="#org8174aea">2.5.1. <code>defer_if</code></a></li> -<li><a href="#orga988278">2.5.2. <code>defer_show</code>: show information about the latest <code>panic</code> on <code>stderr</code></a></li> -<li><a href="#org811d0b1">2.5.3. <code>recover_signal</code>: stop an unwind originating from a signal and/or return the signal number</a></li> +<li><a href="#org4ae1e19">2.5.1. <code>defer_if</code></a></li> +<li><a href="#orge604a6a">2.5.2. <code>defer_show</code>: show information about the latest <code>panic</code> on <code>stderr</code></a></li> +<li><a href="#org7e3e7a1">2.5.3. <code>recover_signal</code>: stop an unwind originating from a signal and/or return the signal number</a></li> </ul> </li> -<li><a href="#org5a25513">2.6. Signal handlers</a> +<li><a href="#org8e07f8d">2.6. Signal handlers</a> <ul> -<li><a href="#org3de478f">2.6.1. <code>defer_sig_flag</code>: a signal handler that flags the execution of a thread.</a></li> -<li><a href="#orgedbd637">2.6.2. <code>defer_sig_jump</code>: a signal handler that flags the execution of a thread and jumps to the first defer clause</a></li> +<li><a href="#org300945b">2.6.1. <code>defer_sig_flag</code>: a signal handler that flags the execution of a thread.</a></li> +<li><a href="#org9e27c11">2.6.2. <code>defer_sig_jump</code>: a signal handler that flags the execution of a thread and jumps to the first defer clause</a></li> </ul> </li> -<li><a href="#org1344ab8">2.7. Encapsulated storage management functions</a> +<li><a href="#orge3f2a1d">2.7. Encapsulated storage management functions</a> <ul> -<li><a href="#org82e7b1f">2.7.1. <code>DEFER_MALLOC_WRAP</code>: force the usage of the wrapped allocation functions</a></li> +<li><a href="#org59c1f6f">2.7.1. <code>DEFER_MALLOC_WRAP</code>: force the usage of the wrapped allocation functions</a></li> </ul> </li> </ul> </li> -<li><a href="#org659e7af">3. Terms</a> +<li><a href="#org19ff7bb">3. Terms</a> <ul> -<li><a href="#orgfda3cd8">3.1. Copyright and license</a></li> -<li><a href="#org79608cf">3.2. Distribution</a></li> +<li><a href="#org713bd54">3.1. Copyright and license</a></li> +<li><a href="#org06cea68">3.2. Distribution</a></li> </ul> </li> </ul> </div> </div> -<div id="outline-container-orgc76741f" class="outline-2"> -<h2 id="orgc76741f"><span class="section-number-2">1</span> Description</h2> +<div id="outline-container-org3f3c69c" class="outline-2"> +<h2 id="org3f3c69c"><span class="section-number-2">1</span> Description</h2> <div class="outline-text-2" id="text-1"> <p> This is a reference implementation of a <code>C</code> language mechanism @@ -343,8 +343,8 @@ Seacord, Martin Uecker, Freek Wiedijk. <i>Defer Mechanism for </ul> </div> -<div id="outline-container-org49288c5" class="outline-3"> -<h3 id="org49288c5"><span class="section-number-3">1.1</span> An example for static cleanup handling</h3> +<div id="outline-container-orgdd83544" class="outline-3"> +<h3 id="orgdd83544"><span class="section-number-3">1.1</span> An example for static cleanup handling</h3> <div class="outline-text-3" id="text-1-1"> <p> In the following code snippet we @@ -372,8 +372,8 @@ guard { </div> <p> -The idea is that we indicate with a <code>defer</code> keyword that the -statement, e.g a call to <code>free</code>, is only to be executed at the end of +The idea is that we indicate with a <b><code>defer</code></b> keyword that the +statement, e.g a call to <b><code>free</code></b>, is only to be executed at the end of the guarded block, and, that we want this action to happen unconditionally in which way ever the guarded block is left. For the three deferred statements together it says that they should be @@ -410,7 +410,7 @@ constructor/destructor pairs (<code>C++</code>)</dd> <p> -For normal control flow (without intermediate <code>return</code>, <code>exit</code>, …) +For normal control flow (without intermediate <b><code>return</code></b>, <code>exit</code>, …) code with similar properties can be coded with existing tools. The above is equivalent to something like the following </p> @@ -453,8 +453,8 @@ above is equivalent to something like the following </div> <p> -Here, the <code>if(false)</code> clauses guarantee that the deferred statements -are jumped over when they are first met, and the labels and <code>goto</code> +Here, the <b><code>if(false)</code></b> clauses guarantee that the deferred statements +are jumped over when they are first met, and the labels and <b><code>goto</code></b> statements implement the hops from back to front to execute the deferred statements eventually. </p> @@ -492,7 +492,7 @@ quite common idiom for cleanup handling in <code>C</code>: <p> This has the advantage of only making the circumstantial control flow -explicit (with three <code>goto</code>) but it does that for the price of +explicit (with three *=goto=) but it does that for the price of proximity; the cleanup code is far from the place where its need arises. </p> @@ -501,21 +501,21 @@ arises. Nevertheless, even this linearization needs some form of naming convention for the labels. For more complicated code the maintenance of these jumps can be tricky and prone to errors. This shows another -advantage of the <a href="#orga946010"><code>defer</code></a> approach: +advantage of the <a href="#org63e5a5c"><code>defer</code></a> approach: </p> <dl class="org-dl"> <dt>maintainability</dt><dd>The cleanup specification is not dependent on arbitrary naming such as labels (<code>C</code>) or RAII classes -(<code>C++</code>) and does not change when <a href="#orga946010"><code>defer</code></a> or <code>break</code> +(<code>C++</code>) and does not change when <a href="#org63e5a5c"><code>defer</code></a> or <b><code>break</code></b> statements are added or removed.</dd> </dl> <p> Another important property that is much more difficult to implement in -<code>C</code> (and that needs <code>try/catch</code> blocks in <code>C++</code>) is that <b>all</b> exits -from the guarded block are detected and acted upon: <code>break</code>, <code>return</code>, -<a href="#org9df3c5d"><code>thrd_exit</code></a>, <a href="#org0e5cd13"><code>exit</code></a>, <a href="#org410910b"><code>panic</code></a>, or +<code>C</code> (and that needs <b><code>try/catch</code></b> blocks in <code>C++</code>) is that <b>all</b> exits +from the guarded block are detected and acted upon: <b><code>break</code></b>, <b><code>return</code></b>, +<a href="#org18b8cc4"><code>thrd_exit</code></a>, <a href="#org9db677d"><code>exit</code></a>, <a href="#org7f6c106"><code>panic</code></a>, or an interruption by a signal. That is, unless there are nasal deamons flying around, we have a forth important property </p> @@ -528,7 +528,7 @@ eventually.</dd> <p> This is different from <code>C++</code>'s handling of destructors, which are only -guaranteed to be executed if there is a <code>try/catch</code> block underneath. +guaranteed to be executed if there is a <b><code>try/catch</code></b> block underneath. </p> <p> @@ -539,14 +539,14 @@ different function calls. </div> </div> -<div id="outline-container-org9df350d" class="outline-3"> -<h3 id="org9df350d"><span class="section-number-3">1.2</span> Dynamic versus static control flow for deferred statements</h3> +<div id="outline-container-orgd578d73" class="outline-3"> +<h3 id="orgd578d73"><span class="section-number-3">1.2</span> Dynamic versus static control flow for deferred statements</h3> <div class="outline-text-3" id="text-1-2"> <p> In the example above the control flow that was the result of deferring -statements was <i>static</i>, that is the <code>defer</code> statements themselves +statements was <i>static</i>, that is the <b><code>defer</code></b> statements themselves were not placed into conditionals or loops. Being able to place them -inside an <code>if</code>, for example, gives the programmer more flexibility, in +inside an <b><code>if</code></b>, for example, gives the programmer more flexibility, in particular it allows to only defer a statement if the corresponding resource has really been needed. </p> @@ -566,7 +566,7 @@ resource has really been needed. <p> Here, the deferred statement will only be evaluated at the termination -of the guarded block only in cases where the buffer referenced by p= +of the guarded block only in cases where the buffer referenced by <code>p</code> is dynamically allocated. To support such constructs, our implementation determines the order and number of times each deferred statement is executed at run-time. This approach requires allocating @@ -581,18 +581,18 @@ deferred statement is executed to release the resource. If the call succeeds (so a resource is allocated) but the <b><code>defer</code></b> mechanism fails, the call to <b><code>free</code></b> is evaluated immediately and the execution of the enclosing guarded block is terminated by a panic with -an error code of <code>DEFER_ENOMEM</code>. +an error code of <b><code>DEFER_ENOMEM</code></b>. </p> </div> </div> -<div id="outline-container-orgfc01729" class="outline-3"> -<h3 id="orgfc01729"><span class="section-number-3">1.3</span> Guarded blocks for function bodies</h3> +<div id="outline-container-org928056f" class="outline-3"> +<h3 id="org928056f"><span class="section-number-3">1.3</span> Guarded blocks for function bodies</h3> <div class="outline-text-3" id="text-1-3"> <p> The current idea in our proposal to the C standardization is to have each function body to implement a guarded block, such that an explicit -<a href="#orgd368dca"><code>guard</code></a> statement is not necessary for many common use +<a href="#orgfde075d"><code>guard</code></a> statement is not necessary for many common use cases. Generally, this can not be done by macro wonders but needs compiler magic. </p> @@ -600,22 +600,22 @@ compiler magic. <p> The reference implementation achieves that for the <code>gcc</code> family of compilers by some internal magic by keeping track of the stack -pointer. This has some caveats, <a href="#orgde99313">see below</a>. Nevertheless +pointer. This has some caveats, <a href="#org5623baa">see below</a>. Nevertheless in this documentation we will always speak about a guarded block, -regardless if a <a href="#orgd368dca"><code>guard</code></a> statement is given explicitly or if +regardless if a <a href="#orgfde075d"><code>guard</code></a> statement is given explicitly or if the function body acts as such. </p> </div> </div> -<div id="outline-container-org77765b1" class="outline-3"> -<h3 id="org77765b1"><span class="section-number-3">1.4</span> Triggering the execution of deferred statements</h3> +<div id="outline-container-org0e872fe" class="outline-3"> +<h3 id="org0e872fe"><span class="section-number-3">1.4</span> Triggering the execution of deferred statements</h3> <div class="outline-text-3" id="text-1-4"> <p> There are three "severity" levels for termination of a guarded block, -<code>break</code> or similar just terminates the guarded block, <code>return</code> +<b><code>break</code></b> or similar just terminates the guarded block, <b><code>return</code></b> terminates all guarded blocks of the same function and -<a href="#org0e5cd13"><code>exit</code></a> or <a href="#org410910b"><code>panic</code></a> of the same thread across all +<a href="#org9db677d"><code>exit</code></a> or <a href="#org7f6c106"><code>panic</code></a> of the same thread across all function calls. </p> @@ -625,7 +625,7 @@ A deferred statement can be triggered in two ways. <ul class="org-ul"> <li>explicitly: by leaving a guarded block when coming to the end of -it or by using <code>break</code>, <code>defer_break</code>, <code>exit</code> +it or by using <b><code>break</code></b>, <b><code>defer_break</code></b>, <b><code>exit</code></b> … from within.</li> <li><p> @@ -636,7 +636,7 @@ user code then typically investigates that flag and acts accordingly. This would typically be used for a signal like <code>SIGINT</code> where the user interrupts the program execution. The second handler jumps to the first defer clause on the defer -stack and triggers a <a href="#org410910b"><code>panic</code></a>. This one is more appropriate +stack and triggers a <a href="#org7f6c106"><code>panic</code></a>. This one is more appropriate for signals that are related to faulty operations that by themselves are not recoverable. </p> @@ -648,17 +648,17 @@ This implementation does not install any of these handlers by default. </div> </div> -<div id="outline-container-org0c3f94e" class="outline-3"> -<h3 id="org0c3f94e"><span class="section-number-3">1.5</span> Execution of deferred statements and panic recovery</h3> +<div id="outline-container-org36720af" class="outline-3"> +<h3 id="org36720af"><span class="section-number-3">1.5</span> Execution of deferred statements and panic recovery</h3> <div class="outline-text-3" id="text-1-5"> <p> Once execution starts inside a deferred statement, the condition that -lead there can be investigated by means of <a href="#org21e7d51"><code>recover</code></a>. This returns +lead there can be investigated by means of <a href="#org66c8e11"><code>recover</code></a>. This returns an integer error code that indicates what happened. If it is <code>0</code>, this execution of the defer clause is just "normal" retreat as of -<code>break</code>, <code>return</code> or <code>exit</code>. If it is any other value +<b><code>break</code></b>, <b><code>return</code></b> or <code>exit</code>. If it is any other value something "remarkable" might have happened, generally a -<a href="#org410910b"><code>panic</code></a> is on its way down in the call stack. +<a href="#org7f6c106"><code>panic</code></a> is on its way down in the call stack. </p> <p> @@ -671,8 +671,8 @@ that they may re-issue the panic by calling `panic(code, </div> </div> -<div id="outline-container-org2c0657b" class="outline-3"> -<h3 id="org2c0657b"><span class="section-number-3">1.6</span> Improved usage of certain C library features</h3> +<div id="outline-container-orga3bf14b" class="outline-3"> +<h3 id="orga3bf14b"><span class="section-number-3">1.6</span> Improved usage of certain C library features</h3> <div class="outline-text-3" id="text-1-6"> <p> As examples how this could be used by the C library, there are @@ -689,14 +689,14 @@ repeated at every call site.</li> will be called, e.g to close files or to free large allocations.</li> <li>User code may establish a recovery mechanism through -<a href="#org21e7d51"><code>recover</code></a> or alike. This will probably be rarely used by +<a href="#org66c8e11"><code>recover</code></a> or alike. This will probably be rarely used by "normal" applications, but security critical applications would get a handle to avoid catastrophes, here.</li> </ul> </div> -<div id="outline-container-orgbf63516" class="outline-4"> -<h4 id="orgbf63516"><span class="section-number-4">1.6.1</span> Advantages of <a href="#orga946010"><code>defer</code></a> for error handling</h4> +<div id="outline-container-orgf85ed48" class="outline-4"> +<h4 id="orgf85ed48"><span class="section-number-4">1.6.1</span> Advantages of <a href="#org63e5a5c"><code>defer</code></a> for error handling</h4> <div class="outline-text-4" id="text-1-6-1"> <p> Inspection of the assembler that is created for these functions @@ -715,21 +715,21 @@ Annex K, but in a way that </div> </div> -<div id="outline-container-org5afeb57" class="outline-3"> -<h3 id="org5afeb57"><span class="section-number-3">1.7</span> Provided interfaces</h3> +<div id="outline-container-orgdedd146" class="outline-3"> +<h3 id="orgdedd146"><span class="section-number-3">1.7</span> Provided interfaces</h3> <div class="outline-text-3" id="text-1-7"> <p> The important interfaces of this tool are: </p> <ul class="org-ul"> -<li><a href="#orgd368dca"><code>guard</code></a> prefixes a guarded block</li> -<li><a href="#orga946010"><code>defer</code></a> prefixes a defer clause</li> -<li><code>break</code> ends a guarded block and executes all its defer clauses</li> -<li><code>return</code> unwinds all guarded blocks of the current function and returns to the caller</li> +<li><a href="#orgfde075d"><code>guard</code></a> prefixes a guarded block</li> +<li><a href="#org63e5a5c"><code>defer</code></a> prefixes a defer clause</li> +<li><b><code>break</code></b> ends a guarded block and executes all its defer clauses</li> +<li><b><code>return</code></b> unwinds all guarded blocks of the current function and returns to the caller</li> <li><code>exit</code> unwinds all defer clauses of all active function calls of the thread and exits normally</li> -<li><a href="#org410910b"><code>panic</code></a> starts global unwinding of all guarded blocks</li> -<li><a href="#org21e7d51"><code>recover</code></a> inside a defer clause stops a panic and provides an error code</li> +<li><a href="#org7f6c106"><b><code>panic</code></b></a> starts global unwinding of all guarded blocks</li> +<li><a href="#org66c8e11"><code>recover</code></a> inside a defer clause stops a panic and provides an error code</li> </ul> <p> @@ -740,39 +740,39 @@ compiled differently, you should wrap the system calls. This can usually be done by providing `-wrap=exit` etc arguments to the linker. (You'd have to check your local manual for that.) This feature may (but shouldn't) be switched off by providing the environment -variable <a href="#orga2c4509"><code>DEFER_NO_WRAP</code></a> to the build. +variable <a href="#org6b7a6b1"><code>DEFER_NO_WRAP</code></a> to the build. </p> <p> In a similar way, this implementation also offers to wrap the allocation functions of the C library, but the default here is the other way around: per default <code>malloc</code> and Co are not wrapped. You -may enable this by setting <a href="#org57a9bcb"><code>DEFER_MALLOC_WRAP</code></a>. Otherwise, you may -use functions <a href="#orgc0da804"><code>defer_malloc</code></a> and similar to catch allocation +may enable this by setting <a href="#org0072322"><code>DEFER_MALLOC_WRAP</code></a>. Otherwise, you may +use functions <a href="#org19dfe66"><code>defer_malloc</code></a> and similar to catch allocation errors. </p> </div> </div> -<div id="outline-container-orga890eed" class="outline-3"> -<h3 id="orga890eed"><span class="section-number-3">1.8</span> Error codes</h3> +<div id="outline-container-org8faa70f" class="outline-3"> +<h3 id="org8faa70f"><span class="section-number-3">1.8</span> Error codes</h3> <div class="outline-text-3" id="text-1-8"> <p> -<a id="org619ee29"></a> -<a id="org32f31e3"></a> -<a id="orgac7326c"></a> -<a id="org2502078"></a> -<a id="org50c58f3"></a> -<a id="org730827a"></a> -<a id="org913a7bc"></a> -<a id="orgb70f39a"></a> -<a id="org7f3dbfa"></a> -<a id="org3bacaac"></a> -<a id="orge46cad0"></a> -<a id="org9a30494"></a> -<a id="org0e2b9b7"></a> -<a id="org7291c90"></a> -send with <a href="#org410910b"><code>panic</code></a>) are always positive, and that "system" error codes +<a id="org2836ec1"></a> +<a id="orga5ebd8d"></a> +<a id="orgdaec287"></a> +<a id="orgb02554a"></a> +<a id="orga35b8ec"></a> +<a id="org94f76d9"></a> +<a id="org64f99c6"></a> +<a id="org8fc5422"></a> +<a id="org2b5ab88"></a> +<a id="org2dfa8e5"></a> +<a id="org9232bbb"></a> +<a id="org87fe171"></a> +<a id="orgb2c58e3"></a> +<a id="orgc48f6fa"></a> +send with <a href="#org7f6c106"><code>panic</code></a>) are always positive, and that "system" error codes are generally negated <code>errno</code> numbers. To deal with such error codes in a portable way, for all POSIX error codes we provide an equivalent prefixed with <code>DEFER_</code>. E.g there is <code>DEFER_ENOMEM</code> that is the same @@ -800,12 +800,12 @@ recover just signals and do nothing if there was none. </div> -<div id="outline-container-org9fbbc6a" class="outline-3"> -<h3 id="org9fbbc6a"><span class="section-number-3">1.9</span> Interoperability with C++</h3> +<div id="outline-container-org1c3d495" class="outline-3"> +<h3 id="org1c3d495"><span class="section-number-3">1.9</span> Interoperability with C++</h3> <div class="outline-text-3" id="text-1-9"> <p> C++ has similar features for out-of-order code execution, namely -destructors and <code>catch</code> clauses. The <a href="#orga946010"><code>defer</code></a> statement combines those +destructors and <b><code>catch</code></b> clauses. The <a href="#org63e5a5c"><code>defer</code></a> statement combines those two features into one. </p> @@ -826,7 +826,7 @@ Nevertheless, to really ensure that resources are released by such a C++ programm it is a good idea to have all exceptions caught. This will ensure that all destructors down to and including in <code>main</code> are called when unwound. An easy way to achieve this is to establish -<code>main</code> as a <code>try-catch</code> block: +<code>main</code> as a <b><code>try-catch</code></b> block: </p> <div class="org-src-container"> @@ -877,10 +877,10 @@ That is, we need <li>a local variable of type <code>std::defer_boundary</code> for which the constructor memorizes the state prior to the call,</li> -<li>a <code>try/catch</code> clause that guarantees that exceptions are caught +<li>a <b><code>try/catch</code></b> clause that guarantees that exceptions are caught and that all the destructors are called when unwound</li> -<li>a call to the method <code>panic()</code> that either propagates any +<li>a call to the method <b><code>panic()</code></b> that either propagates any exception that was caught (if the caller is also <code>C++</code>) or that translates an exception to a panic (if the caller is <code>C</code>).</li> </ul> @@ -891,8 +891,8 @@ For the moment there is no automatization of such a wrapper feature. <p> When used consistently like that, arbitray back and forth translation -between C <a href="#orga946010"><code>defer</code></a> and C++ exceptions is performed but has its limits -in the expressiveness of the <a href="#orga946010"><code>defer</code></a> error codes. We translate some of +between C <a href="#org63e5a5c"><code>defer</code></a> and C++ exceptions is performed but has its limits +in the expressiveness of the <a href="#org63e5a5c"><code>defer</code></a> error codes. We translate some of the standard codes and exceptions: </p> @@ -980,8 +980,8 @@ Support for other codes might come in the future. </div> </div> -<div id="outline-container-org9b1dca6" class="outline-3"> -<h3 id="org9b1dca6"><span class="section-number-3">1.10</span> Implementation specifics</h3> +<div id="outline-container-org63858b8" class="outline-3"> +<h3 id="org63858b8"><span class="section-number-3">1.10</span> Implementation specifics</h3> <div class="outline-text-3" id="text-1-10"> <p> This implementation uses <code>setjmp/longjmp</code> as a main feature to jump to @@ -990,14 +990,14 @@ stack. We distinguishes "jumps" that are known to target the same function (<code>_Defer_shrtjmp</code>) and those that are known to jump to another function on the call stack (<code>_Defer_longjmp</code>). The -unwind for a <code>return</code> will usually be all short jumps, whereas +unwind for a <b><code>return</code></b> will usually be all short jumps, whereas <code>exit</code> and other unwinding of the call stack always initiates a long jump. </p> <p> -This implementation is quite hackerish because it uses nested <code>for</code> -loops to implement the principal macros <a href="#orga946010"><code>defer</code></a> and <a href="#orgd368dca"><code>guard</code></a>. It does +This implementation is quite hackerish because it uses nested <b><code>for</code></b> +loops to implement the principal macros <a href="#org63e5a5c"><code>defer</code></a> and <a href="#orgfde075d"><code>guard</code></a>. It does so to ensure a mostly library only iplementation through macros, that could in principle work with any C compiler. This technique leads to code that is difficult to read and can therefore not be recommended. @@ -1005,15 +1005,15 @@ code that is difficult to read and can therefore not be recommended. <p> Also, we use a intermediate processor for the production of the C (and -C++) code called <a href="https://gustedt.gitlabpages.inria.fr/shnell/">shnell</a>. This uses <code>#pragma</code> annotations for the +C++) code called <a href="https://gustedt.gitlabpages.inria.fr/shnell/">shnell</a>. This uses <b><code>#pragma</code></b> annotations for the definition of complicated macros and for "code unrolling". So if you'd want to modify this implementation, you'd have to download shnell and modify the "real" sources. </p> </div> -<div id="outline-container-org1dfca5c" class="outline-4"> -<h4 id="org1dfca5c"><span class="section-number-4">1.10.1</span> Extension: using computed <code>goto</code></h4> +<div id="outline-container-orgf1997e5" class="outline-4"> +<h4 id="orgf1997e5"><span class="section-number-4">1.10.1</span> Extension: using computed <b><code>goto</code></b></h4> <div class="outline-text-4" id="text-1-10-1"> <p> The implementation can distinguish cases where basically all jumps @@ -1021,18 +1021,18 @@ are finally implemented as being long, or platforms where some shortcut for a short jump can be taken. Currently this is only implemented for gcc and friends that implement so-called "computed <code>goto</code>", that is labels for which addresses can be taken, and -where these addresses then can be used in an extended <code>goto</code> +where these addresses then can be used in an extended <b><code>goto</code></b> feature. Such a specialized implementation can gain a lot on the unwind side (these then are mostly simple jumps), but they still have to keep track of all the guarded blocks and defer clauses -with <code>setjmp</code> because these could be jumped to from other +with <b><code>setjmp</code></b> because these could be jumped to from other functions or from signal handlers. </p> </div> </div> -<div id="outline-container-orge3f7e7b" class="outline-4"> -<h4 id="orge3f7e7b"><span class="section-number-4">1.10.2</span> Extension: Captured values for <a href="#orga946010"><code>defer</code></a></h4> +<div id="outline-container-orgf9be3d6" class="outline-4"> +<h4 id="orgf9be3d6"><span class="section-number-4">1.10.2</span> Extension: Captured values for <a href="#org63e5a5c"><code>defer</code></a></h4> <div class="outline-text-4" id="text-1-10-2"> <p> Local variables that are used inside a deferred statement must be @@ -1068,13 +1068,13 @@ could be rewritten to default to something like <p> that is we could say that defer receives a lambda with no parameters -and executes it when leaving the <a href="#orgd368dca"><code>guard</code></a>. And the default for captures +and executes it when leaving the <a href="#orgfde075d"><code>guard</code></a>. And the default for captures would then just be <code>&</code>, that is all variables are captured "by reference". </p> <p> -In some cases it makes sense for <a href="#orga946010"><code>defer</code></a> to capture a local variable +In some cases it makes sense for <a href="#org63e5a5c"><code>defer</code></a> to capture a local variable by value. In lambda notation this would be someting like </p> @@ -1087,9 +1087,9 @@ by value. In lambda notation this would be someting like <p> where the variable <code>toto</code> would be frozen to the value it has at the -point of the <a href="#orga946010"><code>defer</code></a> statement, and that particular value of <code>toto</code> +point of the <a href="#org63e5a5c"><code>defer</code></a> statement, and that particular value of <code>toto</code> would then be provided when the deferred statement is executed at the -end of the <a href="#orgd368dca"><code>guard</code></a>. In the reference implementation the same can be +end of the <a href="#orgfde075d"><code>guard</code></a>. In the reference implementation the same can be achieved by using the alternative macro <code>defer_capture</code> </p> @@ -1103,21 +1103,21 @@ achieved by using the alternative macro <code>defer_capture</code> </div> -<div id="outline-container-org678717e" class="outline-4"> -<h4 id="org678717e"><span class="section-number-4">1.10.3</span> Omission of <a href="#orgd368dca"><code>guard</code></a> for function body</h4> +<div id="outline-container-org97d843e" class="outline-4"> +<h4 id="org97d843e"><span class="section-number-4">1.10.3</span> Omission of <a href="#orgfde075d"><code>guard</code></a> for function body</h4> <div class="outline-text-4" id="text-1-10-3"> <p> For <code>gcc</code> and friends the implementation is able to detect the -boundaries between different function calls. For a <a href="#orga946010"><code>defer</code></a> that is not -placed inside a <a href="#orgd368dca"><code>guard</code></a> this is important such that we do not -accidentally attach it to a <a href="#orgd368dca"><code>guard</code></a> in another function. This only +boundaries between different function calls. For a <a href="#org63e5a5c"><code>defer</code></a> that is not +placed inside a <a href="#orgfde075d"><code>guard</code></a> this is important such that we do not +accidentally attach it to a <a href="#orgfde075d"><code>guard</code></a> in another function. This only works with compiler magic that keeps track of the "stack pointer". </p> </div> </div> -<div id="outline-container-org964dcb1" class="outline-4"> -<h4 id="org964dcb1"><span class="section-number-4">1.10.4</span> Synchronization of local variables</h4> +<div id="outline-container-orgc101b01" class="outline-4"> +<h4 id="orgc101b01"><span class="section-number-4">1.10.4</span> Synchronization of local variables</h4> <div class="outline-text-4" id="text-1-10-4"> <p> The guarantees for the state of local variables that <code>setjmp/longjmp</code> @@ -1125,17 +1125,17 @@ provides are weaker than those needed in our context. Therefore we use some other synchronization features that guarantee up-to-date values, namely atomic variables and fences. If these are not available, this implementation will still work, but precautions as described for -<a href="#orga946010"><code>defer</code></a> have to be made. +<a href="#org63e5a5c"><code>defer</code></a> have to be made. </p> </div> </div> -<div id="outline-container-orgcb0fd98" class="outline-4"> -<h4 id="orgcb0fd98"><span class="section-number-4">1.10.5</span> <a id="orgde99313"></a> Caveats</h4> +<div id="outline-container-orgcada0c0" class="outline-4"> +<h4 id="orgcada0c0"><span class="section-number-4">1.10.5</span> <a id="org5623baa"></a> Caveats</h4> <div class="outline-text-4" id="text-1-10-5"> <p> This implementation is special, because it is almost a "header only" -implementation that overloads <code>return</code> (plus some others) with a +implementation that overloads <b><code>return</code></b> (plus some others) with a macro. This is not ideal and can have some performance issues or even compilation failures with system-provided inline functions. As a rule of thumb, try to include the <code><stddefer.h></code> header as late as @@ -1146,15 +1146,15 @@ possible, such that there are as few interactions as possible. </div> </div> -<div id="outline-container-orgd7800b3" class="outline-2"> -<h2 id="orgd7800b3"><span class="section-number-2">2</span> Reference manual</h2> +<div id="outline-container-orgabe268d" class="outline-2"> +<h2 id="orgabe268d"><span class="section-number-2">2</span> Reference manual</h2> <div class="outline-text-2" id="text-2"> <p> -<a id="orga946010"></a> +<a id="org63e5a5c"></a> </p> </div> -<div id="outline-container-orgd674893" class="outline-3"> -<h3 id="orgd674893"><span class="section-number-3">2.1</span> <code>defer</code>: ensure the execution of the deferred statement at the end of the guarded block</h3> +<div id="outline-container-orgf117b3c" class="outline-3"> +<h3 id="orgf117b3c"><span class="section-number-3">2.1</span> *=defer=: ensure the execution of the deferred statement at the end of the guarded block</h3> <div class="outline-text-3" id="text-2-1"> <div class="org-src-container"> <pre class="src src-C"><span style="color: #9290ff;">defer</span> <span style="color: #006400;">statement</span> @@ -1164,15 +1164,15 @@ possible, such that there are as few interactions as possible. <p> Deferred statements may not themselves contain guarded blocks or other defer clauses, and shall not call functions that may result in a -termination of the the execution other than <a href="#org410910b"><code>panic</code></a>. Additionally, -such a call to <a href="#org410910b"><code>panic</code></a> must only occur <b>after</b> the current panic state -had been tested with <a href="#org21e7d51"><code>recover</code></a>. +termination of the the execution other than <a href="#org7f6c106"><code>panic</code></a>. Additionally, +such a call to <a href="#org7f6c106"><code>panic</code></a> must only occur <b>after</b> the current panic state +had been tested with <a href="#org66c8e11"><code>recover</code></a>. </p> <p> The deferred statement may use any local variable that is visible -where the <code>defer</code> is placed and that is still alive when the deferred -statement is executed, that is at the end of the surrounding <a href="#orgd368dca"><code>guard</code></a> +where the <b><code>defer</code></b> is placed and that is still alive when the deferred +statement is executed, that is at the end of the surrounding <a href="#orgfde075d"><code>guard</code></a> or function body. This property is checkable at compile time, and a violation usually results in an abortion of the compilation. This implementation here puts everything in place, such that a deferred @@ -1183,12 +1183,12 @@ feautures. <p> If such synchronization features are not available, local variables -that may change between the <code>defer</code> itself and the execution of the +that may change between the <b><code>defer</code></b> itself and the execution of the deferred statement and that are used in the deferred statement must be -declared <code>volatile</code> such that the latest value is taken into +declared <b><code>volatile</code></b> such that the latest value is taken into account. So as a rule of thumb, variables that you use inside a -deferred statement should be qualified: <code>const</code> qualified for those -where the defer clause should use the original value, and <code>volatile</code> +deferred statement should be qualified: <b><code>const</code></b> qualified for those +where the defer clause should use the original value, and <b><code>volatile</code></b> qualified for those that should be used with their latest changes. </p> @@ -1196,16 +1196,16 @@ qualified for those that should be used with their latest changes. The implementation uses allocation as of <code>calloc</code> and <code>free</code> to maintain the list of defer clauses. In case that <code>calloc</code> fails, the defer clause is executed and then the whole execution is -unwound by means of <a href="#org410910b"><code>panic</code></a> and an error argument of +unwound by means of <a href="#org7f6c106"><code>panic</code></a> and an error argument of <code>-DEFER_ENOMEM</code>. </p> <p> -<a id="org0231480"></a> +<a id="orgfde30fb"></a> </p> </div> -<div id="outline-container-orgb93c1b9" class="outline-4"> -<h4 id="orgb93c1b9"><span class="section-number-4">2.1.1</span> <code>defer_capture</code>: capture some variables and defer the execution of the depending statement</h4> +<div id="outline-container-org81d6122" class="outline-4"> +<h4 id="org81d6122"><span class="section-number-4">2.1.1</span> <code>defer_capture</code>: capture some variables and defer the execution of the depending statement</h4> <div class="outline-text-4" id="text-2-1-1"> <div class="org-src-container"> <pre class="src src-C">defer_capture([id0 [, id1 [, id2 ...]]]) statement @@ -1223,13 +1223,13 @@ are initialized with these frozen values. </p> <p> -<a id="orgd368dca"></a> +<a id="orgfde075d"></a> </p> </div> </div> </div> -<div id="outline-container-org071cfc0" class="outline-3"> -<h3 id="org071cfc0"><span class="section-number-3">2.2</span> <code>guard</code>: mark a whole block as "guarded" and as using the defer mechanism.</h3> +<div id="outline-container-org0441242" class="outline-3"> +<h3 id="org0441242"><span class="section-number-3">2.2</span> *=guard=: mark a whole block as "guarded" and as using the defer mechanism.</h3> <div class="outline-text-3" id="text-2-2"> <div class="org-src-container"> <pre class="src src-C"><span style="color: #9290ff;">guard</span> <span style="color: #006400;">compound</span>-statement @@ -1237,19 +1237,19 @@ are initialized with these frozen values. </div> <p> -If such a block is terminated normally or with a <code>break</code> or <code>continue</code> -statement, all deferred statements that have been registered a <a href="#orga946010"><code>defer</code></a> +If such a block is terminated normally or with a <b><code>break</code></b> or <b><code>continue</code></b> +statement, all deferred statements that have been registered a <a href="#org63e5a5c"><code>defer</code></a> statement are executed in reverse order of their registration. There -is also a macro <code>defer_break</code> that can be used in contexts where -<code>break</code> or <code>continue</code> statements would refer to an inner loop or -<code>switch</code> statement. Also, <code>return</code>, <code>exit</code>, <code>quick_exit</code> and +is also a macro <b><code>defer_break</code></b> that can be used in contexts where +<b><code>break</code></b> or <b><code>continue</code></b> statements would refer to an inner loop or +<b><code>switch</code></b> statement. Also, <b><code>return</code></b>, <code>exit</code>, <code>quick_exit</code> and <code>thrd_exit</code> all trigger the execution of deferred statements, up to their respective levels of nestedness of guarded blocks. </p> <p> Other standard means of non-linear control flow out of or into the -block (<code>goto</code>, <code>longjmp</code>, <code>_Exit</code>, <code>abort</code>), do not invoke that +block (<b><code>goto</code></b>, <code>longjmp</code>, <code>_Exit</code>, <code>abort</code>), do not invoke that mechanism and may result in memory leaks or other damage when used within such a guarded block. </p> @@ -1261,12 +1261,12 @@ For some of these constructs, there are replacements <code>defer_goto</code>, <p> -<a id="org410910b"></a> +<a id="org7f6c106"></a> </p> </div> </div> -<div id="outline-container-org578f326" class="outline-3"> -<h3 id="org578f326"><span class="section-number-3">2.3</span> <code>panic</code>: Unwind the whole call stack and execute the deferred statements on the way down</h3> +<div id="outline-container-org1e0d12e" class="outline-3"> +<h3 id="org1e0d12e"><span class="section-number-3">2.3</span> *=panic=: Unwind the whole call stack and execute the deferred statements on the way down</h3> <div class="outline-text-3" id="text-2-3"> <div class="org-src-container"> <pre class="src src-C">noreturn <span style="color: #9290ff;">void</span> <span style="color: #0000ee;">panic</span>(<span style="color: #9290ff;">int</span> <span style="color: #006400;">C</span>); @@ -1277,8 +1277,8 @@ noreturn <span style="color: #9290ff;">void</span> <span style="color: #0000ee;" <p> After all deferred statement of the current thread are executed in -reverse order in which the <a href="#orga946010"><code>defer</code></a> statements have been encountered, -in the last stack frame that has a <a href="#orga946010"><code>defer</code></a> or <a href="#orgd368dca"><code>guard</code></a> statement, +reverse order in which the <a href="#org63e5a5c"><code>defer</code></a> statements have been encountered, +in the last stack frame that has a <a href="#org63e5a5c"><code>defer</code></a> or <a href="#orgfde075d"><code>guard</code></a> statement, <code>F(C)</code> is executed. Here <code>F</code> is a <code>defer_handler</code> and <code>C</code> is an error code. If omitted, <code>F</code> defaults to an implementation specific <code>defer_handler</code>. @@ -1292,7 +1292,7 @@ execution. Prominent candidates from the C library are <code>exit</code> and </p> <p> -This unwind chain can be stopped with a <a href="#org21e7d51"><code>recover</code></a> call within one of +This unwind chain can be stopped with a <a href="#org66c8e11"><code>recover</code></a> call within one of the executed deferred statements (or if a <code>defer_if</code> clause is used). </p> @@ -1305,11 +1305,11 @@ error code will always be negative. </p> <p> -<a id="org0e712d1"></a> +<a id="org4ef8b87"></a> </p> </div> -<div id="outline-container-orgb5669e0" class="outline-4"> -<h4 id="orgb5669e0"><span class="section-number-4">2.3.1</span> <code>defer_assert</code>: assert a runtime condition or <a href="#org410910b"><code>panic</code></a></h4> +<div id="outline-container-org8bdf3fc" class="outline-4"> +<h4 id="org8bdf3fc"><span class="section-number-4">2.3.1</span> <code>defer_assert</code>: assert a runtime condition or <a href="#org7f6c106"><code>panic</code></a></h4> <div class="outline-text-4" id="text-2-3-1"> <div class="org-src-container"> <pre class="src src-C"><span style="color: #9290ff;">void</span> <span style="color: #0000ee;">defer_assert</span>(condition, code, string-literal); @@ -1337,18 +1337,18 @@ otherwise triggers a <code>ENOMEM</code> panic. </div> </div> -<div id="outline-container-org95d66b5" class="outline-3"> -<h3 id="org95d66b5"><span class="section-number-3">2.4</span> Termination functions</h3> +<div id="outline-container-org78dd25a" class="outline-3"> +<h3 id="org78dd25a"><span class="section-number-3">2.4</span> Termination functions</h3> <div class="outline-text-3" id="text-2-4"> <p> -<a id="org0e5cd13"></a> -<a id="org9df3c5d"></a> -<a id="orgee1bcaf"></a> -<a id="org8287d65"></a> -<a id="org1a5b889"></a> -<a id="org50d4a7e"></a> -<a id="org6a74ad1"></a> -<a id="org1aac287"></a> +<a id="org9db677d"></a> +<a id="org18b8cc4"></a> +<a id="org12e13b6"></a> +<a id="orgba782cf"></a> +<a id="orge6aa58b"></a> +<a id="orga43fdc9"></a> +<a id="org7be0fab"></a> +<a id="orge9216c1"></a> </p> <div class="org-src-container"> <pre class="src src-C">noreturn <span style="color: #9290ff;">void</span> <span style="color: #0000ee;">defer_exit</span>(<span style="color: #9290ff;">int</span>); @@ -1391,11 +1391,11 @@ ones. <p> -<a id="orga2c4509"></a> +<a id="org6b7a6b1"></a> </p> </div> -<div id="outline-container-orgcdc21a2" class="outline-4"> -<h4 id="orgcdc21a2"><span class="section-number-4">2.4.1</span> <code>DEFER_NO_WRAP</code>: force the usage of the unwrapped termination functions</h4> +<div id="outline-container-orga60bf93" class="outline-4"> +<h4 id="orga60bf93"><span class="section-number-4">2.4.1</span> <code>DEFER_NO_WRAP</code>: force the usage of the unwrapped termination functions</h4> <div class="outline-text-4" id="text-2-4-1"> <p> Code compiled with this macro set, will not replace all usage of the C @@ -1405,13 +1405,13 @@ above. The use of this macro is not recommended. <p> -<a id="org21e7d51"></a> +<a id="org66c8e11"></a> </p> </div> </div> </div> -<div id="outline-container-org914b48c" class="outline-3"> -<h3 id="org914b48c"><span class="section-number-3">2.5</span> <code>recover</code>: stop a panic and/or return such the error code</h3> +<div id="outline-container-org8dc3e9b" class="outline-3"> +<h3 id="org8dc3e9b"><span class="section-number-3">2.5</span> *=recover=: stop a panic and/or return such the error code</h3> <div class="outline-text-3" id="text-2-5"> <div class="org-src-container"> <pre class="src src-C"><span style="color: #9290ff;">int</span> <span style="color: #0000ee;">recover</span>(<span style="color: #9290ff;">void</span>); @@ -1424,7 +1424,7 @@ A call to this function must reside within a deferred statement. <p> This will only stop unwinding of the panic if the error code had not -been <code>0</code>. Normal <code>break</code>, <code>return</code>, <code>thrd_exit</code>, <code>exit</code> etc will not +been <code>0</code>. Normal <b><code>break</code></b>, <b><code>return</code></b>, <b><code>thrd_exit</code></b>, <code>exit</code> etc will not be be stopped and the guarded block, function, thread or program will finish when all the associated deferred statements have been executed. </p> @@ -1432,7 +1432,7 @@ finish when all the associated deferred statements have been executed. <p> If the error code is non-zero, execution of the defer clause then continues as if the nearest guarded block had been broken by -<code>break</code>. That is, the execution of the defer clauses of +<b><code>break</code></b>. That is, the execution of the defer clauses of that particular guarded block are continued and then execution resumes at the end of that guarded block. </p> @@ -1445,11 +1445,11 @@ error originated from a caught signal to <code>DEFER_SIGNO(SIGTERM)</code>. </p> <p> -<a id="orga9808fa"></a> +<a id="orgf1610d7"></a> </p> </div> -<div id="outline-container-org8174aea" class="outline-4"> -<h4 id="org8174aea"><span class="section-number-4">2.5.1</span> <code>defer_if</code></h4> +<div id="outline-container-org4ae1e19" class="outline-4"> +<h4 id="org4ae1e19"><span class="section-number-4">2.5.1</span> <code>defer_if</code></h4> <div class="outline-text-4" id="text-2-5-1"> <div class="org-src-container"> <pre class="src src-C"><span style="color: #0000ee;">defer_if</span>(err) @@ -1476,27 +1476,27 @@ would be equivalent to a defer clause <p> -This stops an unwind originating from a <code>panic</code> call or from a signal +This stops an unwind originating from a <b><code>panic</code></b> call or from a signal with non-zero error code (or similar), returns the error code in a -local <code>int</code> variable named <code>err</code>, and executes the depending statement -if the value is non-zero, or an alternative <code>else</code> clause, if any, if -the value is zero. The <code>else</code> clause is optional. +local <b><code>int</code></b> variable named <code>err</code>, and executes the depending statement +if the value is non-zero, or an alternative <b><code>else</code></b> clause, if any, if +the value is zero. The <b><code>else</code></b> clause is optional. </p> <p> -the variable <code>err</code> can then be used inside the <code>if</code> or <code>else</code> clauses, +the variable <code>err</code> can then be used inside the <b><code>if</code></b> or <b><code>else</code></b> clauses, but it is not mutable and its address cannot be taken. And it is a bit -useless within the <code>else</code> clause, because we know that it is zero, +useless within the <b><code>else</code></b> clause, because we know that it is zero, there. </p> <p> -<a id="orgb2871c7"></a> +<a id="org0328500"></a> </p> </div> </div> -<div id="outline-container-orga988278" class="outline-4"> -<h4 id="orga988278"><span class="section-number-4">2.5.2</span> <code>defer_show</code>: show information about the latest <a href="#org410910b"><code>panic</code></a> on <code>stderr</code></h4> +<div id="outline-container-orge604a6a" class="outline-4"> +<h4 id="orge604a6a"><span class="section-number-4">2.5.2</span> <code>defer_show</code>: show information about the latest <a href="#org7f6c106"><code>panic</code></a> on <code>stderr</code></h4> <div class="outline-text-4" id="text-2-5-2"> <div class="org-src-container"> <pre class="src src-C"><span style="color: #9290ff;">void</span> <span style="color: #0000ee;">defer_show</span>(<span style="color: #9290ff;">int</span> <span style="color: #006400;">a</span>); @@ -1504,17 +1504,17 @@ there. </div> <p> -This can be used as diagnosis tool after a <a href="#org21e7d51"><code>recover</code></a> to provide +This can be used as diagnosis tool after a <a href="#org66c8e11"><code>recover</code></a> to provide feedback to the user what went wrong with the execution. </p> <p> -<a id="org4477da8"></a> +<a id="org6b49c2e"></a> </p> </div> </div> -<div id="outline-container-org811d0b1" class="outline-4"> -<h4 id="org811d0b1"><span class="section-number-4">2.5.3</span> <code>recover_signal</code>: stop an unwind originating from a signal and/or return the signal number</h4> +<div id="outline-container-org7e3e7a1" class="outline-4"> +<h4 id="org7e3e7a1"><span class="section-number-4">2.5.3</span> <code>recover_signal</code>: stop an unwind originating from a signal and/or return the signal number</h4> <div class="outline-text-4" id="text-2-5-3"> <div class="org-src-container"> <pre class="src src-C"><span style="color: #9290ff;">int</span> <span style="color: #0000ee;">recover_signal</span>(<span style="color: #9290ff;">void</span>); @@ -1522,11 +1522,11 @@ feedback to the user what went wrong with the execution. </div> <p> -This differs from <a href="#org21e7d51"><code>recover</code></a> because it only reacts on signals that are +This differs from <a href="#org66c8e11"><code>recover</code></a> because it only reacts on signals that are caught by the provided signal handlers (<code>defer_sig_flag</code> and -<code>defer_sig_jump</code>), not on other <code>break</code> or <a href="#org410910b"><code>panic</code></a> events. It can be +<code>defer_sig_jump</code>), not on other <b><code>break</code></b> or <a href="#org7f6c106"><code>panic</code></a> events. It can be used in any context and does not need a surrounding guarded block or -<a href="#orga946010"><code>defer</code></a> clause. Its cost is the lookup of a thread local variable and +<a href="#org63e5a5c"><code>defer</code></a> clause. Its cost is the lookup of a thread local variable and a memory synchronization with that variable. So it should probably not be placed inside performance critical loops. </p> @@ -1565,16 +1565,16 @@ active loop: <p> Here, an <code>INT</code> event can occur at any point of the computation before -or inside the <code>while</code> loop. At the first detection of a signal, the -<code>while</code> loop then is broken, and execution continues after it. This +or inside the <b><code>while</code></b> loop. At the first detection of a signal, the +<b><code>while</code></b> loop then is broken, and execution continues after it. This guarantees that the whole loop body is always executed until its end. </p> </div> </div> </div> -<div id="outline-container-org5a25513" class="outline-3"> -<h3 id="org5a25513"><span class="section-number-3">2.6</span> Signal handlers</h3> +<div id="outline-container-org8e07f8d" class="outline-3"> +<h3 id="org8e07f8d"><span class="section-number-3">2.6</span> Signal handlers</h3> <div class="outline-text-3" id="text-2-6"> <p> The provided signal handlers use extensions that might not be @@ -1583,8 +1583,8 @@ thread-local variables can be accessed from a signal handler. </p> </div> -<div id="outline-container-org3de478f" class="outline-4"> -<h4 id="org3de478f"><span class="section-number-4">2.6.1</span> <code>defer_sig_flag</code>: a signal handler that flags the execution of a thread.</h4> +<div id="outline-container-org300945b" class="outline-4"> +<h4 id="org300945b"><span class="section-number-4">2.6.1</span> <code>defer_sig_flag</code>: a signal handler that flags the execution of a thread.</h4> <div class="outline-text-4" id="text-2-6-1"> <div class="org-src-container"> <pre class="src src-C"><span style="color: #9290ff;">void</span> <span style="color: #0000ee;">defer_sig_flag</span>(<span style="color: #9290ff;">int</span> <span style="color: #006400;">sig</span>); @@ -1595,7 +1595,7 @@ thread-local variables can be accessed from a signal handler. This one is not too intrusive and hands control for the signal back to the user code. Thus handling is delayed until the application code reaches the end of a guarded block and/or actively issues a -<a href="#org4477da8"><code>recover_signal</code></a> operation to receive the code. +<a href="#org6b49c2e"><code>recover_signal</code></a> operation to receive the code. </p> <p> @@ -1612,8 +1612,8 @@ as invalid arithmetic or segmentation faults. </div> -<div id="outline-container-orgedbd637" class="outline-4"> -<h4 id="orgedbd637"><span class="section-number-4">2.6.2</span> <code>defer_sig_jump</code>: a signal handler that flags the execution of a thread and jumps to the first defer clause</h4> +<div id="outline-container-org9e27c11" class="outline-4"> +<h4 id="org9e27c11"><span class="section-number-4">2.6.2</span> <code>defer_sig_jump</code>: a signal handler that flags the execution of a thread and jumps to the first defer clause</h4> <div class="outline-text-4" id="text-2-6-2"> <div class="org-src-container"> <pre class="src src-C"><span style="color: #9290ff;">void</span> <span style="color: #0000ee;">defer_sig_jump</span>(<span style="color: #9290ff;">int</span> <span style="color: #006400;">sig</span>); @@ -1645,14 +1645,14 @@ might propose a better tool than <code>signal</code> for that. Be careful. </div> -<div id="outline-container-org1344ab8" class="outline-3"> -<h3 id="org1344ab8"><span class="section-number-3">2.7</span> Encapsulated storage management functions</h3> +<div id="outline-container-orge3f2a1d" class="outline-3"> +<h3 id="orge3f2a1d"><span class="section-number-3">2.7</span> Encapsulated storage management functions</h3> <div class="outline-text-3" id="text-2-7"> <p> -<a id="orgc0da804"></a> -<a id="org1ece315"></a> -<a id="orga960ee1"></a> -<a id="org0bbad5a"></a> +<a id="org19dfe66"></a> +<a id="orgd4b6c2b"></a> +<a id="org7391516"></a> +<a id="org16c9f28"></a> </p> <div class="org-src-container"> <pre class="src src-C"><span style="color: #9290ff;">void</span>* <span style="color: #0000ee;">defer_malloc</span>(<span style="color: #9290ff;">size_t</span> <span style="color: #006400;">size</span>); @@ -1665,7 +1665,7 @@ might propose a better tool than <code>signal</code> for that. Be careful. <p> The functionality of these functions is the same as their un-prefixed C library counterparts, only that instead of returning a null pointer -on failure they will issue a <a href="#org410910b"><code>panic</code></a>. For example, <code>defer_malloc</code>, +on failure they will issue a <a href="#org7f6c106"><code>panic</code></a>. For example, <code>defer_malloc</code>, will execute <code>panic(-DEFER_EINVAL)</code> when called with a <code>size</code> of <code>0</code> and execute <code>panic(-DEFER_ENOMEM)</code> when the allocation fails. </p> @@ -1700,11 +1700,11 @@ first the second deferred statement may save values from <code>p</code> and then </p> <p> -<a id="org57a9bcb"></a> +<a id="org0072322"></a> </p> </div> -<div id="outline-container-org82e7b1f" class="outline-4"> -<h4 id="org82e7b1f"><span class="section-number-4">2.7.1</span> <code>DEFER_MALLOC_WRAP</code>: force the usage of the wrapped allocation functions</h4> +<div id="outline-container-org59c1f6f" class="outline-4"> +<h4 id="org59c1f6f"><span class="section-number-4">2.7.1</span> <code>DEFER_MALLOC_WRAP</code>: force the usage of the wrapped allocation functions</h4> <div class="outline-text-4" id="text-2-7-1"> <p> Code compiled with this macro set, will replace all usage of the C @@ -1717,12 +1717,12 @@ presented above. </div> -<div id="outline-container-org659e7af" class="outline-2"> -<h2 id="org659e7af"><span class="section-number-2">3</span> Terms</h2> +<div id="outline-container-org19ff7bb" class="outline-2"> +<h2 id="org19ff7bb"><span class="section-number-2">3</span> Terms</h2> <div class="outline-text-2" id="text-3"> </div> -<div id="outline-container-orgfda3cd8" class="outline-3"> -<h3 id="orgfda3cd8"><span class="section-number-3">3.1</span> Copyright and license</h3> +<div id="outline-container-org713bd54" class="outline-3"> +<h3 id="org713bd54"><span class="section-number-3">3.1</span> Copyright and license</h3> <div class="outline-text-3" id="text-3-1"> <div class="org-src-container"> <pre class="src src-txt">BSD 3-Clause License @@ -1761,8 +1761,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. </div> </div> -<div id="outline-container-org79608cf" class="outline-3"> -<h3 id="org79608cf"><span class="section-number-3">3.2</span> Distribution</h3> +<div id="outline-container-org06cea68" class="outline-3"> +<h3 id="org06cea68"><span class="section-number-3">3.2</span> Distribution</h3> <div class="outline-text-3" id="text-3-2"> <ul class="org-ul"> <li>This work is distributed at</li> @@ -1785,7 +1785,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. </div> <div id="postamble" class="status"> <p class="author">Author: Jens Gustedt</p> -<p class="date">Created: 2020-09-30 Mi 11:54</p> +<p class="date">Created: 2020-09-30 Mi 12:05</p> <p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p> </div> </body> diff --git a/README.org b/README.org index f38b528982b1cfc7fc0cff29fce50680a18523dc..011f16a67cac696c88e783105c1b9518b6e11266 100644 --- a/README.org +++ b/README.org @@ -87,8 +87,8 @@ guard { #+END_SRC -The idea is that we indicate with a =defer= keyword that the -statement, e.g a call to =free=, is only to be executed at the end of +The idea is that we indicate with a *=defer=* keyword that the +statement, e.g a call to *=free=*, is only to be executed at the end of the guarded block, and, that we want this action to happen unconditionally in which way ever the guarded block is left. For the three deferred statements together it says that they should be @@ -113,7 +113,7 @@ This new technique has at least two advantages to commonly used =C= or constructor/destructor pairs (=C++=) -For normal control flow (without intermediate =return=, =exit=, ...) +For normal control flow (without intermediate *=return=*, =exit=, ...) code with similar properties can be coded with existing tools. The above is equivalent to something like the following @@ -153,8 +153,8 @@ above is equivalent to something like the following #+END_SRC -Here, the =if(false)= clauses guarantee that the deferred statements -are jumped over when they are first met, and the labels and =goto= +Here, the *=if(false)=* clauses guarantee that the deferred statements +are jumped over when they are first met, and the labels and *=goto=* statements implement the hops from back to front to execute the deferred statements eventually. @@ -187,7 +187,7 @@ quite common idiom for cleanup handling in =C=: #+END_SRC This has the advantage of only making the circumstantial control flow -explicit (with three =goto=) but it does that for the price of +explicit (with three *=goto=) but it does that for the price of proximity; the cleanup code is far from the place where its need arises. @@ -198,12 +198,12 @@ advantage of the [[defer][=defer=]] approach: - maintainability :: The cleanup specification is not dependent on arbitrary naming such as labels (=C=) or RAII classes - (=C++=) and does not change when [[defer][=defer=]] or =break= + (=C++=) and does not change when [[defer][=defer=]] or *=break=* statements are added or removed. Another important property that is much more difficult to implement in -=C= (and that needs =try/catch= blocks in =C++=) is that *all* exits -from the guarded block are detected and acted upon: =break=, =return=, +=C= (and that needs *=try/catch=* blocks in =C++=) is that *all* exits +from the guarded block are detected and acted upon: *=break=*, *=return=*, [[thrd_exit][=thrd_exit=]], [[exit][=exit=]], [[panic][=panic=]], or an interruption by a signal. That is, unless there are nasal deamons flying around, we have a forth important property @@ -213,7 +213,7 @@ flying around, we have a forth important property eventually. This is different from =C++='s handling of destructors, which are only -guaranteed to be executed if there is a =try/catch= block underneath. +guaranteed to be executed if there is a *=try/catch=* block underneath. This principle of deferred execution extends to nested guarded blocks in a natural way, even if they are stacked in @@ -222,9 +222,9 @@ different function calls. ** Dynamic versus static control flow for deferred statements In the example above the control flow that was the result of deferring -statements was /static/, that is the =defer= statements themselves +statements was /static/, that is the *=defer=* statements themselves were not placed into conditionals or loops. Being able to place them -inside an =if=, for example, gives the programmer more flexibility, in +inside an *=if=*, for example, gives the programmer more flexibility, in particular it allows to only defer a statement if the corresponding resource has really been needed. @@ -241,7 +241,7 @@ resource has really been needed. #+END_SRC Here, the deferred statement will only be evaluated at the termination -of the guarded block only in cases where the buffer referenced by p= +of the guarded block only in cases where the buffer referenced by =p= is dynamically allocated. To support such constructs, our implementation determines the order and number of times each deferred statement is executed at run-time. This approach requires allocating @@ -254,7 +254,7 @@ deferred statement is executed to release the resource. If the call succeeds (so a resource is allocated) but the *=defer=* mechanism fails, the call to *=free=* is evaluated immediately and the execution of the enclosing guarded block is terminated by a panic with -an error code of =DEFER_ENOMEM=. +an error code of *=DEFER_ENOMEM=*. ** Guarded blocks for function bodies @@ -274,7 +274,7 @@ the function body acts as such. ** Triggering the execution of deferred statements There are three "severity" levels for termination of a guarded block, -=break= or similar just terminates the guarded block, =return= +*=break=* or similar just terminates the guarded block, *=return=* terminates all guarded blocks of the same function and [[exit][=exit=]] or [[panic][=panic=]] of the same thread across all function calls. @@ -282,7 +282,7 @@ function calls. A deferred statement can be triggered in two ways. - explicitly: by leaving a guarded block when coming to the end of - it or by using =break=, =defer_break=, =exit= + it or by using *=break=*, *=defer_break=*, *=exit=* ... from within. - implicitly: from a signal handler. Two signal handlers are @@ -304,7 +304,7 @@ Once execution starts inside a deferred statement, the condition that lead there can be investigated by means of [[recover][=recover=]]. This returns an integer error code that indicates what happened. If it is =0=, this execution of the defer clause is just "normal" retreat as of -=break=, =return= or =exit=. If it is any other value +*=break=*, *=return=* or =exit=. If it is any other value something "remarkable" might have happened, generally a [[panic][=panic=]] is on its way down in the call stack. @@ -350,10 +350,10 @@ The important interfaces of this tool are: - [[guard][=guard=]] prefixes a guarded block - [[defer][=defer=]] prefixes a defer clause - - =break= ends a guarded block and executes all its defer clauses - - =return= unwinds all guarded blocks of the current function and returns to the caller + - *=break=* ends a guarded block and executes all its defer clauses + - *=return=* unwinds all guarded blocks of the current function and returns to the caller - =exit= unwinds all defer clauses of all active function calls of the thread and exits normally - - [[panic][=panic=]] starts global unwinding of all guarded blocks + - [[panic][*=panic=*]] starts global unwinding of all guarded blocks - [[recover][=recover=]] inside a defer clause stops a panic and provides an error code The features =exit=, =quick_exit= and =thrd_exit= are overloaded to do @@ -412,7 +412,7 @@ recover just signals and do nothing if there was none. ** Interoperability with C++ C++ has similar features for out-of-order code execution, namely -destructors and =catch= clauses. The [[defer][=defer=]] statement combines those +destructors and *=catch=* clauses. The [[defer][=defer=]] statement combines those two features into one. This implementation provides features to translate between these @@ -429,7 +429,7 @@ Nevertheless, to really ensure that resources are released by such a C++ programm it is a good idea to have all exceptions caught. This will ensure that all destructors down to and including in =main= are called when unwound. An easy way to achieve this is to establish -=main= as a =try-catch= block: +=main= as a *=try-catch=* block: #+BEGIN_SRC C++ int main(int argc, char* argv[]) try { @@ -470,10 +470,10 @@ That is, we need - a local variable of type =std::defer_boundary= for which the constructor memorizes the state prior to the call, - - a =try/catch= clause that guarantees that exceptions are caught + - a *=try/catch=* clause that guarantees that exceptions are caught and that all the destructors are called when unwound - - a call to the method =panic()= that either propagates any + - a call to the method *=panic()=* that either propagates any exception that was caught (if the caller is also =C++=) or that translates an exception to a panic (if the caller is =C=). @@ -507,34 +507,34 @@ stack. We distinguishes "jumps" that are known to target the same function (=_Defer_shrtjmp=) and those that are known to jump to another function on the call stack (=_Defer_longjmp=). The -unwind for a =return= will usually be all short jumps, whereas +unwind for a *=return=* will usually be all short jumps, whereas =exit= and other unwinding of the call stack always initiates a long jump. -This implementation is quite hackerish because it uses nested =for= +This implementation is quite hackerish because it uses nested *=for=* loops to implement the principal macros [[defer][=defer=]] and [[guard][=guard=]]. It does so to ensure a mostly library only iplementation through macros, that could in principle work with any C compiler. This technique leads to code that is difficult to read and can therefore not be recommended. Also, we use a intermediate processor for the production of the C (and -C++) code called [[https://gustedt.gitlabpages.inria.fr/shnell/][shnell]]. This uses =#pragma= annotations for the +C++) code called [[https://gustedt.gitlabpages.inria.fr/shnell/][shnell]]. This uses *=#pragma=* annotations for the definition of complicated macros and for "code unrolling". So if you'd want to modify this implementation, you'd have to download shnell and modify the "real" sources. -*** Extension: using computed =goto= +*** Extension: using computed *=goto=* The implementation can distinguish cases where basically all jumps are finally implemented as being long, or platforms where some shortcut for a short jump can be taken. Currently this is only implemented for gcc and friends that implement so-called "computed =goto=", that is labels for which addresses can be taken, and -where these addresses then can be used in an extended =goto= +where these addresses then can be used in an extended *=goto=* feature. Such a specialized implementation can gain a lot on the unwind side (these then are mostly simple jumps), but they still have to keep track of all the guarded blocks and defer clauses -with =setjmp= because these could be jumped to from other +with *=setjmp=* because these could be jumped to from other functions or from signal handlers. *** Extension: Captured values for [[defer][=defer=]] @@ -610,7 +610,7 @@ implementation will still work, but precautions as described for *** <<caveats>> Caveats This implementation is special, because it is almost a "header only" -implementation that overloads =return= (plus some others) with a +implementation that overloads *=return=* (plus some others) with a macro. This is not ideal and can have some performance issues or even compilation failures with system-provided inline functions. As a rule of thumb, try to include the =<stddefer.h>= header as late as @@ -619,7 +619,7 @@ possible, such that there are as few interactions as possible. * Reference manual <<defer>> -** =defer=: ensure the execution of the deferred statement at the end of the guarded block +** *=defer=: ensure the execution of the deferred statement at the end of the guarded block #+BEGIN_SRC C @@ -633,7 +633,7 @@ such a call to [[panic][=panic=]] must only occur *after* the current panic stat had been tested with [[recover][=recover=]]. The deferred statement may use any local variable that is visible -where the =defer= is placed and that is still alive when the deferred +where the *=defer=* is placed and that is still alive when the deferred statement is executed, that is at the end of the surrounding [[guard][=guard=]] or function body. This property is checkable at compile time, and a violation usually results in an abortion of the compilation. This @@ -643,12 +643,12 @@ success of that depends on the presence of some synchronization feautures. If such synchronization features are not available, local variables -that may change between the =defer= itself and the execution of the +that may change between the *=defer=* itself and the execution of the deferred statement and that are used in the deferred statement must be -declared =volatile= such that the latest value is taken into +declared *=volatile=* such that the latest value is taken into account. So as a rule of thumb, variables that you use inside a -deferred statement should be qualified: =const= qualified for those -where the defer clause should use the original value, and =volatile= +deferred statement should be qualified: *=const=* qualified for those +where the defer clause should use the original value, and *=volatile=* qualified for those that should be used with their latest changes. The implementation uses allocation as of =calloc= and =free= to @@ -673,23 +673,23 @@ executed, address-less local variables with the same name and type are initialized with these frozen values. <<guard>> -** =guard=: mark a whole block as "guarded" and as using the defer mechanism. +** *=guard=: mark a whole block as "guarded" and as using the defer mechanism. #+BEGIN_SRC C guard compound-statement #+END_SRC -If such a block is terminated normally or with a =break= or =continue= +If such a block is terminated normally or with a *=break=* or *=continue=* statement, all deferred statements that have been registered a [[defer][=defer=]] statement are executed in reverse order of their registration. There -is also a macro =defer_break= that can be used in contexts where -=break= or =continue= statements would refer to an inner loop or -=switch= statement. Also, =return=, =exit=, =quick_exit= and +is also a macro *=defer_break=* that can be used in contexts where +*=break=* or *=continue=* statements would refer to an inner loop or +*=switch=* statement. Also, *=return=*, =exit=, =quick_exit= and =thrd_exit= all trigger the execution of deferred statements, up to their respective levels of nestedness of guarded blocks. Other standard means of non-linear control flow out of or into the -block (=goto=, =longjmp=, =_Exit=, =abort=), do not invoke that +block (*=goto=*, =longjmp=, =_Exit=, =abort=), do not invoke that mechanism and may result in memory leaks or other damage when used within such a guarded block. @@ -698,7 +698,7 @@ For some of these constructs, there are replacements =defer_goto=, <<panic>> -** =panic=: Unwind the whole call stack and execute the deferred statements on the way down +** *=panic=: Unwind the whole call stack and execute the deferred statements on the way down #+BEGIN_SRC C noreturn void panic(int C); @@ -796,7 +796,7 @@ above. The use of this macro is not recommended. <<recover>> -** =recover=: stop a panic and/or return such the error code +** *=recover=: stop a panic and/or return such the error code #+BEGIN_SRC C int recover(void); @@ -805,13 +805,13 @@ int recover(void); A call to this function must reside within a deferred statement. This will only stop unwinding of the panic if the error code had not -been =0=. Normal =break=, =return=, =thrd_exit=, =exit= etc will not +been =0=. Normal *=break=*, *=return=*, *=thrd_exit=*, =exit= etc will not be be stopped and the guarded block, function, thread or program will finish when all the associated deferred statements have been executed. If the error code is non-zero, execution of the defer clause then continues as if the nearest guarded block had been broken by -=break=. That is, the execution of the defer clauses of +*=break=*. That is, the execution of the defer clauses of that particular guarded block are continued and then execution resumes at the end of that guarded block. @@ -843,15 +843,15 @@ defer { #+END_SRC -This stops an unwind originating from a =panic= call or from a signal +This stops an unwind originating from a *=panic=* call or from a signal with non-zero error code (or similar), returns the error code in a -local =int= variable named =err=, and executes the depending statement -if the value is non-zero, or an alternative =else= clause, if any, if -the value is zero. The =else= clause is optional. +local *=int=* variable named =err=, and executes the depending statement +if the value is non-zero, or an alternative *=else=* clause, if any, if +the value is zero. The *=else=* clause is optional. -the variable =err= can then be used inside the =if= or =else= clauses, +the variable =err= can then be used inside the *=if=* or *=else=* clauses, but it is not mutable and its address cannot be taken. And it is a bit -useless within the =else= clause, because we know that it is zero, +useless within the *=else=* clause, because we know that it is zero, there. <<defer_show>> @@ -873,7 +873,7 @@ int recover_signal(void); This differs from [[recover][=recover=]] because it only reacts on signals that are caught by the provided signal handlers (=defer_sig_flag= and -=defer_sig_jump=), not on other =break= or [[panic][=panic=]] events. It can be +=defer_sig_jump=), not on other *=break=* or [[panic][=panic=]] events. It can be used in any context and does not need a surrounding guarded block or [[defer][=defer=]] clause. Its cost is the lookup of a thread local variable and a memory synchronization with that variable. So it should probably not @@ -905,8 +905,8 @@ int main(void) { #+END_SRC Here, an =INT= event can occur at any point of the computation before -or inside the =while= loop. At the first detection of a signal, the -=while= loop then is broken, and execution continues after it. This +or inside the *=while=* loop. At the first detection of a signal, the +*=while=* loop then is broken, and execution continues after it. This guarantees that the whole loop body is always executed until its end. ** Signal handlers