summaryrefslogtreecommitdiff
path: root/doc/libstddjb/alarm.html
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2016-10-24 02:15:36 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2016-10-24 02:15:36 +0000
commit9ef3a9f8b2704693496af12120ea3ab40389bf7b (patch)
tree9ed582b049881f1271a6b02978f1ed6d28a4f948 /doc/libstddjb/alarm.html
parent422d91b2b0a2b8b3a8af510cc55b1400c60be303 (diff)
downloadskalibs-9ef3a9f8b2704693496af12120ea3ab40389bf7b.tar.xz
Add the alarm library, first draft.
Diffstat (limited to 'doc/libstddjb/alarm.html')
-rw-r--r--doc/libstddjb/alarm.html94
1 files changed, 94 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>