SD_EVENT_WAIT(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💖 SD_EVENT_WAIT(3) — low-level event loop ops, bestie edition 💖

okay so this whole page is about the low-level event loop girlies: sd_event_wait, sd_event_prepare, sd_event_dispatch, sd_event_get_state, sd_event_get_iteration, and the state constants SD_EVENT_INITIAL, SD_EVENT_PREPARING, SD_EVENT_ARMED, SD_EVENT_PENDING, SD_EVENT_RUNNING, SD_EVENT_EXITING, SD_EVENT_FINISHED. It's literally Low-level event loop operations, no cap.

✨ SYNOPSIS ✨

#include <systemd/sd-event.h>

enum {
        SD_EVENT_INITIAL,
        SD_EVENT_PREPARING,
        SD_EVENT_ARMED,
        SD_EVENT_PENDING,
        SD_EVENT_RUNNING,
        SD_EVENT_EXITING,
        SD_EVENT_FINISHED,
};

int sd_event_prepare(sd_event *event);

int sd_event_wait(sd_event *event, uint64_t usec);

int sd_event_dispatch(sd_event *event);

int sd_event_get_state(sd_event *event);

int sd_event_get_iteration(sd_event *event, uint64_t *ret);

🌸 DESCRIPTION 🌸

So the low-level besties sd_event_prepare(), sd_event_wait(), and sd_event_dispatch() are what you use when you want to run specific phases of an event loop yourself. If you want the higher-level glow-up — complete individual iterations of an event loop, or just run it continuously — go look at sd_event_run(3) and sd_event_loop(3). iykyk.

sd_event_prepare() checks for pending events and arms the necessary timers. If any events are ready to be processed (“pending”), it returns a positive, non-zero value, and the caller should process those 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 means 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 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 sd_event_prepare() again.

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

sd_event_get_iteration() may be used to determine the current iteration of the event loop. It returns an unsigned 64-bit 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 sd_event_prepare() invocation.

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 timeout. 💅

🦋 STATE MACHINE 🦋

The event loop knows the following states, that may be queried with sd_event_get_state().

  • SD_EVENT_INITIAL — 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.

Added in version 229.

  • SD_EVENT_PREPARING — An event source is currently being prepared, i.e. the preparation handler is currently being executed, as set with sd_event_source_set_prepare(3). 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 or SD_EVENT_PENDING.

Added in version 229.

  • 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_INITIAL.

Added in version 229.

  • SD_EVENT_PENDING — 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.

Added in version 229.

  • SD_EVENT_RUNNING — 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.

Added in version 229.

  • SD_EVENT_EXITING — 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 handler returns.

Added in version 229.

  • SD_EVENT_FINISHED — 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.

Added in version 229.

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

                     INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\
                        |                                                     |
                        |                                                     ^
                        |                                                     |
                        v                 ret == 0                            |
                 sd_event_prepare() >--->--->--->--->- ARMED                  |
                        |                                |                    ^
                        | ret > 0                        |                    |
                        |                                |                    |
                        v                                v          ret == 0  |
                     PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+
                        |           ret > 0                                   ^
                        |                                                     |
                        |                                                     |
                        v                                                     |
                 sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/
                        |                             ret > 0
                        | ret == 0
                        |
                        v
                     FINISHED

💜 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, 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.

💔 Errors

Returned errors may indicate the following problems:

  • -EINVAL — The event parameter is invalid or 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, library or module instance.

Other errors are possible, too. 😭

🔥 NOTES 🔥

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

All functions listed here are thread-agnostic and only a single thread may operate on a given object at any given time. Different threads may access the same object at different times. Multiple independent objects may be used from different threads in parallel.

The code described here uses getenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call setenv(3) from a parallel thread. It is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started.

bestie, that last one is a real “do not do this in a parallel thread” situation, okay? no chaotic setenv() side-quests while other threads are running 🙈

👑 HISTORY 👑

sd_event_prepare(), sd_event_wait(), sd_event_dispatch(), and sd_event_get_state() were added in version 221.

sd_event_get_iteration() was added in version 231.

🌈 SEE ALSO 🌈

systemd(1), sd_event_new(3), sd_event_add_io(3), sd_event_add_time(3), sd_event_add_signal(3), sd_event_add_child(3), sd_event_add_inotify(3), sd_event_add_defer(3), sd_event_run(3), sd_event_get_fd(3), sd_event_source_set_prepare(3)

k bye bestie, this iconic little page is from systemd 261.3, manual page SD_EVENT_WAIT(3) 💅✨ (footer didn't print a date, so no invented dates here 🫶)

📦 where this page comes from