-
Notifications
You must be signed in to change notification settings - Fork 14
/
index.html
92 lines (77 loc) · 5.06 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
<html>
<head><title>Dasynq manual</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<div class="content">
<h1>Dasynq manual</h1>
This is the manual for the <b>Dasynq</b> event loop library (version 2.1.0).
<ul>
<li><a href="#intro">Introduction</a></l1>
<li>Reference
<ul>
<li><a href="event_loop.html">event_loop, event_loop_n, event_loop_th</a></li>
<li><a href="fd_watcher.html">fd_watcher, fd_watcher_impl</a></li>
<li><a href="bidi_fd_watcher.html">bidi_fd_watcher, bidi_fd_watcher_impl</a></li>
<li><a href="signal_watcher.html">signal_watcher, signal_watcher_impl</a></li>
<li><a href="child_proc_watcher.html">child_proc_watcher, child_proc_watcher_impl</a></li>
<li><a href="timer.html">timer, timer_impl</a></li>
<li><a href="dasynq-namespace.html">dasynq namespace synopsis</a></li>
</ul>
</ul>
<hr>
<a name="intro"></a><h2>Introduction</h2>
<p>An event loop library provides a means for waiting on events that occur asynchronously. One good
example is network input/output; in a server with multiple client connections, a mechanism is needed to
wait until data is available, or until it is possible to write data, to one or more of the current
connections (and to be able to identify <i>which</i> connections are ready). Dasynq is a multi-platform,
thread-safe C++ library which provides such functionality.</p>
<p>Note that an event loop generally supports managing various different kinds of event. Dasynq can be used
for detecting:
<ul>
<li>read/write readiness on sockets, pipes, and certain devices including terminals and serial lines;</li>
<li>connections to listening sockets;</li>
<li>reception of POSIX signals (such as SIGTERM); and</li>
<li>child process status notifications (termination etc).</li>
</ul>
It also supports one-shot and periodic timers.</p>
<p>Dasynq is fully thread safe, allowing events to be polled and processed on any thread. There are
<i>some</i> limitations on the use the Dasynq API in a multi-threaded application. However, when used in a
single-thread application, the API is just about as straight-forward as the API of most other event loop
libraries.</p>
<p>Dasynq is also intended to allow development of extremely robust client applications. Where possible,
it allows pre-allocation of resources to prevent allocation failures from occurring at inopportune moments
during program execution. </p>
<h3>Caveat</h3>
<p>It should be possible for an application (whether using Dasynq or not) to be able to gracefully
handle all error situations that it could be faced with. This is a necessary pre-requisite for a
truly stable system—one where important programs do not terminate unexpectedly. Part of
handling errors gracefully is being able to control when they can occur; it needs to be possible to
allocate resources up-front, rather than just as they are needed. Dasynq is designed to allow, as much as
possible, for exactly that, and to have well-defined error modes so that it is possible to
produce robust and stable software. However, unfortunate external implementation and interface
details can prevent this goal from being realised properly (regardless of whether Dasynq is used).</p>
<p>One of these external details is related to an aspect of Dasynq that is, arguably, avoidable.
The <a href="http://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#cxx-throw">Itanium C++ ABI</a>,
which is the basis for the C++ ABI on many platforms (for instance it is the
ABI which the Sys V ABI for x86-64 defers to), has one very unfortunate flaw: throwing an
exception requires making a heap allocation, and if the allocation fails, the process terminates.
Implementations have an "emergency allocation pool" for exceptions which should mean that the
allocation fails only in truly exceptional circumstances, but the possibility is there.
Unfortunately Dasynq at this stage sometimes uses exceptions (in some cases exposing them as part
of its API, in others handling them internally) and in theory could trigger process
termination on these platforms. I consider this a bug in the ABI and in the platforms implementing
it, however a future version of Dasynq may endeavour to avoid use of exceptions entirely (or at
least make it possible for the client to avoid unwittingly triggering exceptions).</p>
<p>Another unfortunate externally-imposed limitation is that the event polling mechanisms used by
Dasynq typically have no means for pre-sizing. Adding a file descriptor to an <i>epoll</i> set, or to
a <i>kqueue</i>, is an operation that may fail due to lack of resources (kernel memory, etc): but it
fails at the wrong time, when we have already accepted the network connection (or opened the device,
etc). Dasynq can't pre-determine the number of descriptors that can be added to an event set, and so it
must potentially return an error condition (or throw an exception) <i>when</i> the operation fails,
and the application must deal with it then, without reasonable warning.</p>
<p>I remain hopeful that such limitations can one day be lifted—but that requires changes outside
of Dasynq itself. So, I suppose, we shall have to wait and see.</p>
</div>
</body>
</html>