-
Notifications
You must be signed in to change notification settings - Fork 14
/
dasynq-namespace.html
187 lines (153 loc) · 7.72 KB
/
dasynq-namespace.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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
<html>
<head><title>Dasynq manual - dasynq namespace</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<div class="content">
<h1>dasynq namespace</h1>
<pre>
#include "dasynq.h"
namespace dasynq {
// "null mutex", i.e. a no-op mutex "implementation" suitable for use in a single-threaded application
class null_mutex;
// generic event loop
template <typename T_Mutex> class <a href="event_loop.html">event_loop</a>;
typedef event_loop<null_mutex> event_loop_n;
typedef event_loop<std::mutex> event_loop_th;
// event loop delay initialisation tag
class delayed_init;
// rearm codes
enum class <a href="#rearm">rearm</a>
{
/** Re-arm the event watcher so that it receives further events */
REARM,
/** Disarm the event watcher so that it receives no further events, until it is re-armed explicitly */
DISARM,
/** Leave in current armed/disarmed state */
NOOP,
/** Remove the event watcher (and call "removed" callback) */
REMOVE,
/** The watcher has been removed explicitly */
REMOVED,
/** RE-queue the watcher to have its notification called again */
REQUEUE
};
// clock types
enum class <a href="#clock_type">clock_type</a>
{
SYSTEM, // wall-time clock, time may jump if set by user
MONOTONIC // monotonically increasing clock without jumps
};
// clock time
class <a href="#time_val">time_val</a>;
// time_val operators
time_val operator-(const time_val &t1, const time_val &t2) noexcept;
time_val operator+(const time_val &t1, const time_val &t2) noexcept;
time_val &operator+=(time_val &t1, const time_val &t2) noexcept;
time_val &operator-=(time_val &t1, const time_val &t2) noexcept;
int operator/(const time_val &t1, const time_val &t2) noexcept;
bool operator<(const time_val &t1, const time_val &t2) noexcept;
bool operator==(const time_val &t1, const time_val &t2) noexcept;
bool operator<=(const time_val &t1, const time_val &t2) noexcept;
bool operator!=(const time_val &t1, const time_val &t2) noexcept;
bool operator>(const time_val &t1, const time_val &t2) noexcept;
bool operator>=(const time_val &t1, const time_val &t2) noexcept;
time_val &operator<<=(time_val &t, int n) noexcept;
time_val &operator>>=(time_val &t, int n) noexcept;
time_val operator<<(time_val &t, int n) noexcept;
time_val operator>>(time_val &t, int n) noexcept;
// event watch flags
constexpr unsigned int IN_EVENTS;
constexpr unsigned int OUT_EVENTS;
}
</pre>
<hr><h1 id="clock_type">clock_type</h1>
<pre>
#include "dasynq.h"
namespace dasynq {
enum class clock_type
{
SYSTEM, // wall-time clock, time may jump if set by user
MONOTONIC // monotonically increasing clock without jumps
};
}
</pre>
<p><b>Brief</b>: The <i class="code-name">clock_type</i> enumeration is used to differentiate between two
different types of clock: the <i>system</i> clock, which represents an adjustable "wall clock" time, or
the <i>monotonic</i> clock, a non-adjustable clock tracking time elapsed since some fixed (but arbitrary)
point in time.</p>
<h2>Details</h2>
<p>Not all systems support the monotonic clock. In Dasynq, using the <i class="code-name">MONOTONIC</i>
clock on such systems will instead refer to the <i class="code-name">SYSTEM</i> clock.</p>
<hr><h1 id="time_val">time_val</h1>
<pre>
#include "dasynq.h"
namespace dasynq {
class time_val;
}
</pre>
<p><b>Brief</b>: The <i class="code-name">time_val</i> class represents high-precision clock times, and supports
arithmetic operations on them. It acts as a wrapper to a <i class="code-name">struct timespec</i> object, so
that times are represented as a combination of seconds and nanoseconds. In addition to the public members
listed below, a number of arithmetic and comparison operators are defined as non-member functions. Noe that
<i class="code-name">time_val</i> cannot be used to represent negative time intervals.</p>
<h2>Public members</h2>
<ul>
<li><i class="code-name">time_val()</i> - default constructor; time is unintialised</li>
<li><i class="code-name">time_val(const struct timespec &t)</i> - construct using specified time from POSIX <i class="code-name">timespec</i></li>
<li><i class="code-name">time_val(second_t s, nsecond_t ns)</i> - construct using specified time</li>
<li><i class="code-name">second_t</i> [type] - type used to hold seconds component</li>
<li><i class="code-name">nsecond_t</i> [type] - type used to hold nanoseconds component</li>
<li><i class="code-name">second_t seconds() const</i><br>
<i class="code-name">second_t & seconds()</i> - access the seconds value</li>
<li><i class="code-name">nsecond_t nseconds() const</i><br>
<i class="code-name">nsecond_t & nseconds()</i> - access the nanoseconds value</li>
<li><i class="code-name">operator timespec() const</i> - conversion to <i class="code-name">struct timespec</i></li>
<li><i class="code-name">timespec & get_timespec() noexcept</i> - access to wrapped
<i class="code-name">struct timespec</i> object.</li>
<li><i class="code-name">const timespec & get_timespec() const noexcept</i> - access to wrapped
<i class="code-name">struct timespec</i> object.</li>
</ul>
<hr><h1 id="rearm">rearm — dasynq::rearm</h1>
<pre>
#include "dasynq.h"
namespace dasynq {
enum class rearm
{
/** Re-arm the event watcher so that it receives further events */
REARM,
/** Disarm the event watcher so that it receives no further events, until it is re-armed explicitly */
DISARM,
/** Leave in current armed/disarmed state */
NOOP,
/** Remove the event watcher (and call "removed" callback) */
REMOVE,
/** The watcher has been removed explicitly */
REMOVED,
/** Re-queue the watcher to have its callback called again */
REQUEUE
};
}
</pre>
<p><b>Brief</b>: The <i class="code-name">rearm</i> enumeration specifies various watcher actions that can
be applied automatically on return from the callback function.</p>
<h2>Details</h2>
<p>A watcher that has been added to an event loop can be enabled or disabled. If enabled, the watcher may be
queued for processing by the event loop; at the processing stage, the callback function of a queued
watcher will be called. See the <i class="code-name"><a href="event_loop.html">event_loop</a></i>
documentation for a detailed discussion. A watcher is disabled when it is queued and must be re-enabled
after processing in order to receive further events; an easy way to accomplish this is to return the
<i class="code-name">rearm::REARM</i> value from the callback.<br>
<span class="note"><i>Note:</i> a multi-threaded event loop has the limitation that the watcher should
normally not be re-enabled while the callback is being executed. Returning
<i class="code-name">rearm::REARM</i> from the callback is a convenient way to get around this
limitation.</span></p>
<p>In the case of a single-threaded event loop where a watcher has been re-enabled explicitly while the
callback function is executing, the <i class="code-name">rearm::DISARM</i> code can be returned in order
to disable it again (this has no effect if the watcher is already disabled).<p>
<p>Other return codes are largely self-explanatory. Note that <i class="code-name">rearm::REMOVED</i> code
must be returned if the watcher has been scheduled for removal from the loop (de-registered) via the
watcher's <i class="code-name">deregister</i> function.
<p>Note that a watcher that continuously requeues itself by returning <i class="code-name">REQUEUE</i>
potentially starves other, lower-priority, watchers from processing.</p>
</div></body></html>