From 3534b428629be185e096be99e3bd5fdfe32d5544 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 18 Sep 2014 18:55:44 +0000 Subject: initial commit with rc for skalibs-2.0.0.0 --- doc/libstddjb/iopause.html | 196 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 doc/libstddjb/iopause.html (limited to 'doc/libstddjb/iopause.html') diff --git a/doc/libstddjb/iopause.html b/doc/libstddjb/iopause.html new file mode 100644 index 0000000..72eedde --- /dev/null +++ b/doc/libstddjb/iopause.html @@ -0,0 +1,196 @@ + + + + + skalibs: the iopause library interface + + + + + + +

+libstddjb
+libskarnet
+skalibs
+Software
+skarnet.org +

+ +

The `iopause` library interface

+ +

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

+ +

General information

+ +

+ iopause is the skalibs API for event loop selection. It's a +wrapper around the system's +poll() +(if available) or +select() +(if poll() is unavailable) function. It +works around some system-dependent quirks; also it works with +absolute dates instead of timeouts. This is a good thing: +see below. +

+ +

+ iopause is a derived work from Dan J. Bernstein's +iopause library, but the +skalibs implementation is subtly different. +

+ +

Data structures

+ +

+ An iopause_fd structure is similar to a +struct pollfd +structure, and must be filled the same way. Usually, the user declares +an array of iopause_fd and fills it, one element per descriptor +to select on. If x is an iopause_fd: +

+ +

x.fd must be set to the fd number to select on.
x.events must be a disjunction of the following flags: +
- IOPAUSE_READ if the fd is to be selected for reading.
- IOPAUSE_WRITE if the fd is to be selected for writing.
When the selection function returns, x.revents contains +a disjunction of the following flags: +
- IOPAUSE_READ if the fd is readable (this include reception of an EOF).
- IOPAUSE_WRITE if the fd is writable.
- IOPAUSE_EXCEPT if an exception (such as EOF or an error) occurred on the fd.

+ +

+ Unlike poll() or select(), which use a timeout +argument, the iopause() function uses a deadline argument, +i.e. an absolute time at which it must return 0 if no event has happened +so far, as well as a stamp argument, i.e. an absolute time meaning +now. Those arguments are stored in +tain_ts. Here is why: +

+ +

+ The event loop pattern is mostly used to multiplex several asynchronous +events that can happen independently, at the same time or not. Let's +say you have 3 events, x, y and z. Each of +those has a separate timeout: if x happens before x-timeout +milliseconds, you call the x-event-handler function, but +if x-timeout milliseconds elapse without x happening, +you call x-timeout-handler function. And similarly with y +and z. +

+ +

+ But the selection function returning does not mean x has happened +or that x has timed out. It might also mean that y has +happened, that y has timed out, that z has happened, that +z has timed out, or something else entirely. In the post-selection +part of the loop, the proper handler is called for the event or timeout +that has happened; then the loop is executed again, and in the +pre-selection part of the loop, the array describing the events is filled, +and the selection timeout is computed. +

+ +

+ How are you going to compute that global selection timeout? Easy: it's the +shortest of the three. But we just spent some amount of time waiting, so the +individual timeouts must be recomputed! This means: +

You need a way to know the time spent in a selection primitive, which +basically means getting a timestamp before the selection and once again +after the timestamp.
You need to recompute every individual timeout everytime you enter +the loop.

+ +

+ That is really cumbersome. A much simpler way of doing things is: +

+ +

Always keep a reasonably accurate estimation of the current +time in a stamp variable. That means getting the current time +at the start of the process, and updating it right after any +action that takes a significant amount of time. When to update stamp +can be difficult to estimate in CPU-bound processes; fortunately, most +processes using an event loop are IO-bound, and the only actions that take +a non-negligible amount of time in an IO-bound process are the blocking +primitives. So, stamp must be updated right after a selection +function returns, and if the program has been correctly written and +cannot block anywhere else, it's the only place where it needs to be.
For every event, compute the deadline of that event: +x-deadline is x-timeout added to the current stamp +value when x enters the loop. This is done only once per event: +you never have to recompute event deadlines - unlike timeouts, which diminish +over time, deadlines do not change.
At every iteration, the selection deadline is the earliest of all the +available event deadlines.
As an added bonus: after the selection function returns and + stamp has been updated, it is easy to check which events have +timed out and which have not: x has timed out iff x-deadline +is earlier than stamp.

+ +

+ Maintaining a global timestamp and using absolute times instead of relative +times really is the right way to work with event loops, and the iopause +interface reflects that. Of course, you need a reliable, bug-free time library +and a monotonic, constant system clock to handle absolute times correctly; +that is why iopause relies on the tai library. +

+ +

Functions

+ +

+ int iopause (iopause_fd *x, unsigned int len, tain_t const *deadline, tain_t const *stamp)
+Blocks until one of the events described in the x array, of length +len, happens, or until the absolute date *deadline is +reached. deadline may be null, in which case the function blocks +indefinitely until an event happens. If deadline is not null, then +stamp must not be null, and must contain an accurate estimation +of the current time. The function returns the number of events that have +happened, 0 for a timeout, or -1 (and sets errno) for an error. +

+ +

+ int iopause_stamp (iopause_fd *x, unsigned int len, tain_t const *deadline, tain_t *stamp)
+Like iopause(), but if stamp is not null, it is updated +right before the function returns. This helps the user always keep a +reasonably accurate estimation of the current time in stamp; +it is recommended to use this function instead of the lower-level +iopause(). +

+ +

Underlying implementations

+ +

+ iopause is an alias to either iopause_poll or +or iopause_select. By default, it is aliased to iopause_poll; to +alias it to iopause_select instead, configure skalibs with the +--enable-iopause-select option. +

+ +

+Both iopause_poll and iopause_select are implemented on top of the +ppoll() system call +if it is available; but if it is not, then iopause_poll defaults to +poll(), +which has a more comfortable API than +select(), +but a maximum precision of 1 millisecond which might not be enough for some applications; whereas +iopause_select defaults to select(), which incurs some CPU overhead for the +API conversion, but has a 1 microsecond precision. +

+ + + -- cgit v1.2.3

The iopause library interface

General information

Data structures

Functions

Underlying implementations

The `iopause` library interface