diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2016-10-24 02:15:36 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska-skaware@skarnet.org> | 2016-10-24 02:15:36 +0000 |
| commit | 9ef3a9f8b2704693496af12120ea3ab40389bf7b (patch) | |
| tree | 9ed582b049881f1271a6b02978f1ed6d28a4f948 /doc | |
| parent | 422d91b2b0a2b8b3a8af510cc55b1400c60be303 (diff) | |
| download | skalibs-9ef3a9f8b2704693496af12120ea3ab40389bf7b.tar.xz | |
Add the alarm library, first draft.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/libstddjb/alarm.html | 94 | ||||
| -rw-r--r-- | doc/libstddjb/index.html | 1 |
2 files changed, 95 insertions, 0 deletions
diff --git a/doc/libstddjb/alarm.html b/doc/libstddjb/alarm.html new file mode 100644 index 0000000..da14267 --- /dev/null +++ b/doc/libstddjb/alarm.html @@ -0,0 +1,94 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>skalibs: the alarm library interface</title> + <meta name="Description" content="skalibs: the alarm library interface" /> + <meta name="Keywords" content="skalibs c unix alarm getitimer setitimer timer_create timer_gettime timer_settime library libstddjb" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">libstddjb</a><br /> +<a href="../libskarnet.html">libskarnet</a><br /> +<a href="../index.html">skalibs</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>alarm</tt> library interface </h1> + +<p> + The following functions are declared in the <tt>skalibs/alarm.h</tt> header, +and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. +</p> + +<h2> General information </h2> + +<p> + <tt>alarm</tt> is a set of primitives to provide the same functionality as +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/alarm.html">alarm()</a>, +but with sub-second precision. +</p> + +<p> + Depending on the functionality the underlying system provides, +the precision can be 1 nanosecond (implementation via +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/timer_getoverrun.html">timer_settime()</a>, +1 microsecond (implementation via +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setitimer.html">setitimer()</a>, +or 1 second (fallback implementation with +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/alarm.html">alarm()</a> +when nothing better can be found). +</p> + +<h2> Functions </h2> + +<p> +<code> int alarm_milliseconds (unsigned int n) </code> <br /> +Sets a fuse that will raise a SIGALRM after <em>n</em> milliseconds. +If <em>n</em> is 0, the SIGALRM will be raised instantly. +Returns 1 on success and 0 (and sets errno) on failure. +</p> + +<p> +<code> int alarm_timeout (tain_t const *tto) </code> <br /> +Sets a fuse that will raise a SIGALRM after some amount +of time has passed. The amount of time is described in +*<em>tto</em>, which is a relative +<a href="tai.html">tain_t</a>, i.e. a structure containing +a relative TAIN64 time. +Returns 1 on success and 0 (and sets errno) on failure. +</p> + +<p> +<code> int alarm_deadline (tain_t const *deadline) </code> <br /> +Sets a fuse that will raise a SIGALRM when the clock reaches +*<em>deadline</em>, which is an absolute time expressed in +<a href="tai.html">TAI64N</a> format. +Returns 1 on success and 0 (and sets errno) on failure. +</p> + +<p> +<code> void alarm_disable (void) </code> <br /> +Cancels a previously set fuse. No SIGALRM will be raised. +</p> + +<h2> Notes </h2> + +<ul> + <li> Asynchronous programming via signals is bad. The best way +to handle situations where something happens after some time has +elapsed is to use an asynchronous loop primitive such as +<a href="iopause.html">iopause()</a>. The problem is that some +external libraries only provide synchronous functions (including +functions talking to the network!) with no obvious way to set a +timeout. The <tt>alarm_*</tt> set of functions is meant to work +around that, with hopefully better granularity than the POSIX +<tt>alarm()</tt> function. </li> +</ul> + +</body> +</html> diff --git a/doc/libstddjb/index.html b/doc/libstddjb/index.html index dfa6f94..6ecfeb2 100644 --- a/doc/libstddjb/index.html +++ b/doc/libstddjb/index.html @@ -45,6 +45,7 @@ including them directly. </li> <h2> Programming </h2> <ul> + <li> <a href="alarm.html">skalibs/alarm.h</a>: sub-second precision <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/alarm.html">alarm()</a> </li> <li> <a href="alloc.html">skalibs/alloc.h</a>: basic heap memory allocation primitives </li> <li> <a href="allreadwrite.html">skalibs/allreadwrite.h</a>: <a href="safewrappers.html">safe wrappers</a> around I/O functions, extra I/O functions </li> |