alarm.html (3458B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the alarm library interface</title> 7 <meta name="Description" content="skalibs: the alarm library interface" /> 8 <meta name="Keywords" content="skalibs c unix alarm getitimer setitimer timer_create timer_gettime timer_settime library libstddjb" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>alarm</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/alarm.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>alarm</tt> is a set of primitives to provide the same functionality as 32 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/alarm.html">alarm()</a>, 33 but with sub-second precision. 34 </p> 35 36 <p> 37 Depending on the functionality the underlying system provides, 38 the precision can be 1 nanosecond (implementation via 39 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/timer_getoverrun.html">timer_settime()</a>, 40 1 microsecond (implementation via 41 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/setitimer.html">setitimer()</a>, 42 or 1 second (fallback implementation with 43 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/alarm.html">alarm()</a> 44 when nothing better can be found). 45 </p> 46 47 <h2> Functions </h2> 48 49 <p> 50 <code> int alarm_milliseconds (unsigned int n) </code> <br /> 51 Sets a fuse that will raise a SIGALRM after <em>n</em> milliseconds. 52 If <em>n</em> is 0, the SIGALRM will be raised instantly. 53 Returns 1 on success and 0 (and sets errno) on failure. 54 </p> 55 56 <p> 57 <code> int alarm_timeout (tain const *tto) </code> <br /> 58 Sets a fuse that will raise a SIGALRM after some amount 59 of time has passed. The amount of time is described in 60 *<em>tto</em>, which is a relative 61 <a href="tai.html">tain</a>, i.e. a structure containing 62 a relative TAIN64 time. 63 Returns 1 on success and 0 (and sets errno) on failure. 64 </p> 65 66 <p> 67 <code> int alarm_deadline (tain const *deadline) </code> <br /> 68 Sets a fuse that will raise a SIGALRM when the clock reaches 69 *<em>deadline</em>, which is an absolute time expressed in 70 <a href="tai.html">TAI64N</a> format. 71 Returns 1 on success and 0 (and sets errno) on failure. 72 </p> 73 74 <p> 75 <code> void alarm_disable (void) </code> <br /> 76 Cancels a previously set fuse. No SIGALRM will be raised. 77 </p> 78 79 <h2> Notes </h2> 80 81 <ul> 82 <li> Asynchronous programming via signals is bad. The best way 83 to handle situations where something happens after some time has 84 elapsed is to use an asynchronous loop primitive such as 85 <a href="iopause.html">iopause()</a>. The problem is that some 86 external libraries only provide synchronous functions (including 87 functions talking to the network!) with no obvious way to set a 88 timeout. The <tt>alarm_*</tt> set of functions is meant to work 89 around that, with hopefully better granularity than the POSIX 90 <tt>alarm()</tt> function. </li> 91 </ul> 92 93 </body> 94 </html>