The skabus library interface

General information

libskabus is a collection of C client libraries used to communicate with the various skabus daemons.




Preamble: synchronous functions

The bulk of libskabus functions takes two extra arguments at the end: deadline and stamp. Their type is tain_t. This means they are synchronous function calls, and the extra arguments are there to ensure those calls do not block forever.

stamp must be first initialized to an accurate enough approximation of the current time, for instance via skalibs' tain_now() function; it will then be automatically updated by the skabus function calls to always contain (an accurate enough approximation of) the current time.

deadline is an absolute date. The meaning is: if the function has not returned by deadline, its operation is interrupted, and it will immediately return with a failure code, and errno will be set to ETIMEDOUT.

deadline and stamp are used internally to compute a timeout, because blocking functions such as poll() use timeouts. The functions (like most functions) prefer to take a deadline and a timestamp instead of a timeout, because it's much easier (for both the application and the library's implementation) to work with absolute deadlines and update a timestamp regularly than it is to recompute a bunch of timeouts after every operation that potentially takes time.

skalibs can keep track of the timestamp for you, in the global STAMP variable. All libskabus functions taking a deadline and stamp argument also have a version with a name ending in _g, that does not take stamp, and assumes the STAMP variable always contains (an accurate enough approximation of) the current time.

Those synchronous function calls normally return almost instantly: there should be no blocking code path between the function call and its return. Nevertheless, since they involve communication with another process, they are at the whim of the scheduler, so it's impossible to guarantee that they will never block. The use of the deadline and stamp arguments ensures there is a cap on the amount of time they block.

skabus functions

The skabus/skabus.h header is actually a concatenation of other headers: the libskabus is separated into several modules, each of them with its own header.