From 38c9492b4fb971fe08e4ac0167e06e5dccb3eb2e Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 24 Nov 2017 22:46:28 +0000 Subject: A bit more documentation --- doc/libskabus/index.html | 127 +++++++++++++++++++++++++++++++++++++++++++++++ doc/libskabus/rpc.html | 41 +++++++++++++++ 2 files changed, 168 insertions(+) create mode 100644 doc/libskabus/index.html create mode 100644 doc/libskabus/rpc.html (limited to 'doc/libskabus') diff --git a/doc/libskabus/index.html b/doc/libskabus/index.html new file mode 100644 index 0000000..0ebcb80 --- /dev/null +++ b/doc/libskabus/index.html @@ -0,0 +1,127 @@ + + + + + + skabus: the skabus library interface + + + + + + +

+skabus
+Software
+skarnet.org +

+ +

The skabus library interface

+ +

General information

+ +

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

+ +

Compiling

+ + + +

Linking

+ + + +

Programming

+ +

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 skarnet.org 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. +

+ + + + + diff --git a/doc/libskabus/rpc.html b/doc/libskabus/rpc.html new file mode 100644 index 0000000..486258e --- /dev/null +++ b/doc/libskabus/rpc.html @@ -0,0 +1,41 @@ + + + + + + skabus: the skabus_rpc library interface + + + + + + +

+libskabus
+skabus
+Software
+skarnet.org +

+ +

The skabus/rpc.h library interface

+ +

+ The skabus_rpc library provides an API for clients +to the skabus-rpcd daemon. +This is the way they register interfaces and send queries to +other clients. +

+ +

Programming

+ +

+ Check the skabus/rpc.h header for the +exact function prototypes. +

+ +

Starting and ending a session

+ +to be continued + + + -- cgit v1.3.1