sd_event_wait

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).