sd_event_wait, sd_event_prepare, sd_event_dispatch, sd_event_get_state,
sd_event_get_iteration, SD_EVENT_INITIAL, SD_EVENT_PREPARING, SD_EVENT_ARMED,
SD_EVENT_PENDING, SD_EVENT_RUNNING, SD_EVENT_EXITING, SD_EVENT_FINISHED -
Low-level event loop operations
int sd_event_wait(sd_event *event,
The low-level sd_event_prepare(), sd_event_wait() and
sd_event_dispatch() functions may be used to execute specific phases of
an event loop. See sd_event_run(3) and sd_event_loop(3) for
higher-level functions that execute individual but complete iterations of an
event loop or run it continuously.
sd_event_prepare() checks for pending events and arms
necessary timers. If any events are ready to be processed
("pending"), it returns a positive, non-zero value, and the caller
should process these events with sd_event_dispatch().
sd_event_dispatch() dispatches the highest priority event
source that has a pending event. On success, sd_event_dispatch()
returns either zero, which indicates that no further event sources may be
dispatched and exiting of the event loop was requested via
sd_event_exit(3); or a positive non-zero value, which means that an
event source was dispatched and the loop returned to its initial state, and
the caller should initiate the next event loop iteration by invoking
In case sd_event_prepare() returned zero,
sd_event_wait() should be called to wait for further events or a
timeout. If any events are ready to be processed, it returns a positive,
non-zero value, and the events should be dispatched with
sd_event_dispatch(). Otherwise, the event loop returned to its
initial state and the next event loop iteration should be initiated by
invoking sd_event_prepare() again.
sd_event_get_state() may be used to determine the state the
event loop is currently in. It returns one of the states described
sd_event_get_iteration() may be used to determine the
current iteration of the event loop. It returns an unsigned 64bit integer
containing a counter that increases monotonically with each iteration of the
event loop, starting with 0. The counter is increased at the time of the
All five functions take, as the first argument, the event loop
object event that has been created with sd_event_new(). The
timeout for sd_event_wait() is specified in usec in
microseconds. (uint64_t) -1 may be used to specify an infinite
The event loop knows the following states, that may be queried with
The initial state the event loop is in, before each event
loop iteration. Use sd_event_prepare() to transition the event loop
into the SD_EVENT_ARMED or SD_EVENT_PENDING states.
An event source is currently being prepared, i.e. the
preparation handler is currently being executed, as set with
. This state is only seen in the event
source preparation handler that is invoked from the sd_event_prepare()
call and is immediately followed by SD_EVENT_ARMED
sd_event_prepare() has been called and no event
sources were ready to be dispatched. Use sd_event_wait() to wait for
new events, and transition into SD_EVENT_PENDING or back into
sd_event_prepare() or sd_event_wait() have
been called and there were event sources with events pending. Use
sd_event_dispatch() to dispatch the highest priority event source and
transition back to SD_EVENT_INITIAL, or SD_EVENT_FINISHED.
A regular event source is currently being dispatched.
This state is only seen in the event source handler that is invoked from the
sd_event_dispatch() call, and is immediately followed by
SD_EVENT_INITIAL or SD_EVENT_FINISHED as soon the event source
handler returns. Note that during dispatching of exit event sources the
SD_EVENT_EXITING state is seen instead.
Similar to SD_EVENT_RUNNING but is the state in
effect while dispatching exit event sources. It is followed by
SD_EVENT_INITIAL or SD_EVENT_FINISHED as soon as the event
The event loop has exited. All exit event sources have
run. If the event loop is in this state it serves no purpose anymore, and
should be freed.
A simplified flow chart of the states and the calls to transition
between them is shown below. Note that SD_EVENT_PREPARING,
SD_EVENT_RUNNING and SD_EVENT_EXITING are not shown here.
On success, these functions return 0 or a positive integer. On failure, they
return a negative errno-style error code. In case of sd_event_prepare()
and sd_event_wait(), a positive, non-zero return code indicates that
events are ready to be processed and zero indicates that no events are ready.
In case of sd_event_dispatch(), a positive, non-zero return code
indicates that the event loop returned to its initial state and zero indicates
the event loop has exited. sd_event_get_state() returns a positive or
zero state on success.
Returned errors may indicate the following problems:
v ret == 0 |
sd_event_prepare() >--->--->--->--->- ARMED |
| | ^
| ret > 0 | |
| | |
v v ret == 0 |
PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+
| ret > 0 ^
| ret > 0
| ret == 0
The event parameter is invalid or
The event loop object is not in the right state.
The event loop is already terminated.
The event loop has been created in a different
Other errors are possible, too.
These APIs are implemented as a shared library, which can be compiled and linked
to with the libsystemd pkg-config(1) file.
systemd(1), sd_event_new(3), sd_event_add_io(3),