Index · Directives · Python · libudev · gudev systemd 220

Name

sd_event_wait, sd_event_prepare, sd_event_dispatch — Run parts of libsystemd event loop

Synopsis

#include <systemd/sd-event.h>
int sd_event_prepare(sd_event *event);
 
int sd_event_wait(sd_event *event,
 uint64_t timeout);
 
int sd_event_dispatch(sd_event *event);
 

Description

Functions described here form parts of an event loop.

sd_event_prepare checks for pending events and arms necessary timers. If any events are ready to be processed, it returns a positive value, and the events should be processed with sd_event_dispatch. sd_event_dispatch runs a handler for one of the events from the sources with the highest priority. On success, sd_event_dispatch returns either 0, which means that the loop is finished, or a positive value, which means that the loop is again in the initial state and sd_event_prepare should be called again.

In case sd_event_prepare returned 0, sd_event_wait should be called to wait for events or a timeout. If any events are ready to be processed, it returns a positive value, and the events should be processed with sd_event_dispatch. Otherwise, the loop is back in the initial state and sd_event_prepare should be called again.

             ┌──────────┐
             │ initial  ├──←←←←←←←←←←←←←←←←←←←─┐
             └───┬──────┘                      ↑
                 │                             ↑
           sd_event_prepare   ┌─────────┐      ↑
                 ├ 0 →→→→→→→──┤  armed  │      ↑
                 1            └───┬─────┘      ↑
                 ↓                │            ↑
                 ↓           sd_event_wait     ↑
                 ├───←←←←←←←─── 1 ┴─ 0 →→→→→→→─┘
             ┌───┴──────┐                      ↑
             │ pending  │                      ↑
             └───┬──────┘                      ↑
                 │                             ↑
           sd_event_dispatch                   ↑
                 ↓                             ↑
                 ├ 1 ──────────→→→→→→→─────────┘
                 0
                 ↓
             ┌───┴──────┐
             │ finished │
             └──────────┘
    

All three functions as the first argument take the event loop object event that is created with with sd_event_new. The timeout for sd_event_wait is specified with timeout in milliseconds. (uint64_t) -1 may be used to specify an infinite timeout.

Return Value

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 value means that events are ready to be processed and 0 means that no events are ready. In case of sd_event_dispatch a positive value means that the loop is again in the initial state and 0 means the loop is finished. For any of those functions, a negative return value means the loop must be aborted.

Errors

Returned errors may indicate the following problems:

-EINVAL

Parameter event is NULL.

-EBUSY

The event loop object is not in the right state.

-ESTALE

The event loop is already terminated.

-ECHILD

The event loop has been created in a different process.

Other errors are possible too.

Notes

Functions described here are available as a shared library, which can be compiled and linked to with the libsystemd pkg-config(1) file.

See Also

systemd(1), sd_event_new(3), sd_event_run(3), sd_event_add_io(3), sd_event_add_time(3), sd_event_add_signal(3), sd_event_add_defer(3), sd_event_add_exit(3), sd_event_add_post(3).