1SD_EVENT_WAIT(3)                 sd_event_wait                SD_EVENT_WAIT(3)
2
3
4

NAME

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

SYNOPSIS

12       #include <systemd/sd-event.h>
13
14       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
24       int sd_event_prepare(sd_event *event);
25
26       int sd_event_wait(sd_event *event, uint64_t usec);
27
28       int sd_event_dispatch(sd_event *event);
29
30       int sd_event_get_state(sd_event *event);
31
32       int sd_event_get_iteration(sd_event *event, uint64_t *ret);
33

DESCRIPTION

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
41       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
46       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
55       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
62       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
65       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
71       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

STATE MACHINE

77       The event loop knows the following states, that may be queried with
78       sd_event_get_state().
79
80       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
85       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
93       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
98       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
104       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
112       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
117       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
122       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
126                     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
148

RETURN VALUE

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

ERRORS

160       Returned errors may indicate the following problems:
161
162       -EINVAL
163           The event parameter is invalid or NULL.
164
165       -EBUSY
166           The event loop object is not in the right state.
167
168       -ESTALE
169           The event loop is already terminated.
170
171       -ECHILD
172           The event loop has been created in a different process.
173
174       Other errors are possible, too.
175

NOTES

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

SEE ALSO

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)
185
186
187
188systemd 239                                                   SD_EVENT_WAIT(3)
Impressum