libstddjb
libskarnet
skalibs
Software
skarnet.org

The alarm library interface

The following functions are declared in the skalibs/alarm.h header, and implemented in the libskarnet.a or libskarnet.so library.

General information

alarm is a set of primitives to provide the same functionality as alarm(), but with sub-second precision.

Depending on the functionality the underlying system provides, the precision can be 1 nanosecond (implementation via timer_settime(), 1 microsecond (implementation via setitimer(), or 1 second (fallback implementation with alarm() when nothing better can be found).

Functions

int alarm_milliseconds (unsigned int n)
Sets a fuse that will raise a SIGALRM after n milliseconds. If n is 0, the SIGALRM will be raised instantly. Returns 1 on success and 0 (and sets errno) on failure.

int alarm_timeout (tain_t const *tto)
Sets a fuse that will raise a SIGALRM after some amount of time has passed. The amount of time is described in *tto, which is a relative tain_t, i.e. a structure containing a relative TAIN64 time. Returns 1 on success and 0 (and sets errno) on failure.

int alarm_deadline (tain_t const *deadline)
Sets a fuse that will raise a SIGALRM when the clock reaches *deadline, which is an absolute time expressed in TAI64N format. Returns 1 on success and 0 (and sets errno) on failure.

void alarm_disable (void)
Cancels a previously set fuse. No SIGALRM will be raised.

Notes

• 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 iopause(). 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 alarm_* set of functions is meant to work around that, with hopefully better granularity than the POSIX alarm() function.