1SD_EVENT_WAIT(3) sd_event_wait SD_EVENT_WAIT(3)
2
6 sd_event_wait, sd_event_prepare, sd_event_dispatch, sd_event_get_state,
7 sd_event_get_iteration, SD_EVENT_INITIAL, SD_EVENT_PREPARING,
8 SD_EVENT_ARMED, SD_EVENT_PENDING, SD_EVENT_RUNNING, SD_EVENT_EXITING,
9 SD_EVENT_FINISHED - Low-level event loop operations
10
12 #include <systemd/sd-event.h>
13 enum {
15 SD_EVENT_INITIAL,
16 SD_EVENT_PREPARING,
17 SD_EVENT_ARMED,
18 SD_EVENT_PENDING,
19 SD_EVENT_RUNNING,
20 SD_EVENT_EXITING,
21 SD_EVENT_FINISHED,
22 };
23 int sd_event_prepare(sd_event *event);
25 int sd_event_wait(sd_event *event, uint64_t usec);
27 int sd_event_dispatch(sd_event *event);
29 int sd_event_get_state(sd_event *event);
31 int sd_event_get_iteration(sd_event *event, uint64_t *ret);
33
35 The low-level sd_event_prepare(), sd_event_wait() and
36 sd_event_dispatch() functions may be used to execute specific phases of
37 an event loop. See sd_event_run(3) and sd_event_loop(3) for
38 higher-level functions that execute individual but complete iterations
39 of an event loop or run it continuously.
40 sd_event_prepare() checks for pending events and arms necessary timers.
42 If any events are ready to be processed ("pending"), it returns a
43 positive, non-zero value, and the caller should process these events
44 with sd_event_dispatch().
45 sd_event_dispatch() dispatches the highest priority event source that
47 has a pending event. On success, sd_event_dispatch() returns either
48 zero, which indicates that no further event sources may be dispatched
49 and exiting of the event loop was requested via sd_event_exit(3); or a
50 positive non-zero value, which means that an event source was
51 dispatched and the loop returned to its initial state, and the caller
52 should initiate the next event loop iteration by invoking
53 sd_event_prepare() again.
54 In case sd_event_prepare() returned zero, sd_event_wait() should be
56 called to wait for further events or a timeout. If any events are ready
57 to be processed, it returns a positive, non-zero value, and the events
58 should be dispatched with sd_event_dispatch(). Otherwise, the event
59 loop returned to its initial state and the next event loop iteration
60 should be initiated by invoking sd_event_prepare() again.
61 sd_event_get_state() may be used to determine the state the event loop
63 is currently in. It returns one of the states described below.
64 sd_event_get_iteration() may be used to determine the current iteration
66 of the event loop. It returns an unsigned 64bit integer containing a
67 counter that increases monotonically with each iteration of the event
68 loop, starting with 0. The counter is increased at the time of the
69 sd_event_prepare() invocation.
70 All five functions take, as the first argument, the event loop object
72 event that has been created with sd_event_new(). The timeout for
73 sd_event_wait() is specified in usec in microseconds. (uint64_t) -1
74 may be used to specify an infinite timeout.
75
77 The event loop knows the following states, that may be queried with
78 sd_event_get_state().
79 SD_EVENT_INITIAL
81 The initial state the event loop is in, before each event loop
82 iteration. Use sd_event_prepare() to transition the event loop into
83 the SD_EVENT_ARMED or SD_EVENT_PENDING states.
84 SD_EVENT_PREPARING
86 An event source is currently being prepared, i.e. the preparation
87 handler is currently being executed, as set with
88 sd_event_source_set_prepare(3). This state is only seen in the
89 event source preparation handler that is invoked from the
90 sd_event_prepare() call and is immediately followed by
91 SD_EVENT_ARMED or SD_EVENT_PENDING.
92 SD_EVENT_ARMED
94 sd_event_prepare() has been called and no event sources were ready
95 to be dispatched. Use sd_event_wait() to wait for new events, and
96 transition into SD_EVENT_PENDING or back into SD_EVENT_INITIAL.
97 SD_EVENT_PENDING
99 sd_event_prepare() or sd_event_wait() have been called and there
100 were event sources with events pending. Use sd_event_dispatch() to
101 dispatch the highest priority event source and transition back to
102 SD_EVENT_INITIAL, or SD_EVENT_FINISHED.
103 SD_EVENT_RUNNING
105 A regular event source is currently being dispatched. This state is
106 only seen in the event source handler that is invoked from the
107 sd_event_dispatch() call, and is immediately followed by
108 SD_EVENT_INITIAL or SD_EVENT_FINISHED as soon the event source
109 handler returns. Note that during dispatching of exit event sources
110 the SD_EVENT_EXITING state is seen instead.
111 SD_EVENT_EXITING
113 Similar to SD_EVENT_RUNNING but is the state in effect while
114 dispatching exit event sources. It is followed by SD_EVENT_INITIAL
115 or SD_EVENT_FINISHED as soon as the event handler returns.
116 SD_EVENT_FINISHED
118 The event loop has exited. All exit event sources have run. If the
119 event loop is in this state it serves no purpose anymore, and
120 should be freed.
121 A simplified flow chart of the states and the calls to transition
123 between them is shown below. Note that SD_EVENT_PREPARING,
124 SD_EVENT_RUNNING and SD_EVENT_EXITING are not shown here.
125 INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\
127 | |
128 | ^
129 | |
130 v ret == 0 |
131 sd_event_prepare() >--->--->--->--->- ARMED |
132 | | ^
133 | ret > 0 | |
134 | | |
135 v v ret == 0 |
136 PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+
137 | ret > 0 ^
138 | |
139 | |
140 v |
141 sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/
142 | ret > 0
143 | ret == 0
144 |
145 v
146 FINISHED
147
150 On success, these functions return 0 or a positive integer. On failure,
151 they return a negative errno-style error code. In case of
152 sd_event_prepare() and sd_event_wait(), a positive, non-zero return
153 code indicates that events are ready to be processed and zero indicates
154 that no events are ready. In case of sd_event_dispatch(), a positive,
155 non-zero return code indicates that the event loop returned to its
156 initial state and zero indicates the event loop has exited.
157 sd_event_get_state() returns a positive or zero state on success.
158
160 Returned errors may indicate the following problems:
161 -EINVAL
163 The event parameter is invalid or NULL.
164 -EBUSY
166 The event loop object is not in the right state.
167 -ESTALE
169 The event loop is already terminated.
170 -ECHILD
172 The event loop has been created in a different process.
173 Other errors are possible, too.
175
177 These APIs are implemented as a shared library, which can be compiled
178 and linked to with the libsystemd pkg-config(1) file.
179
181 systemd(1), sd_event_new(3), sd_event_add_io(3), sd_event_add_time(3),
182 sd_event_add_signal(3), sd_event_add_defer(3), sd_event_add_exit(3),
183 sd_event_add_post(3), sd_event_run(3), sd_event_get_fd(3),
184 sd_event_source_set_prepare(3)
185systemd 239 SD_EVENT_WAIT(3)