SD_EVENT_RUN(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_EVENT_RUN(3) — the sd_event_run manual, but make it make sense

okay bestie, so this is the page for sd_event_run and sd_event_loop — yes both of them, they're a package deal 🎀 — and it's literally all about running an event loop. you know, the thing that lets your program sit there looking cute until something actually happens. main character energy fr.

✨ NAME ✨

sd_event_run, sd_event_loop — run an event loop. that's it. that's the tweet. 💅

🌈 SYNOPSIS 🌈

#include <systemd/sd-event.h>

int sd_event_run(sd_event *event, uint64_t usec);

int sd_event_loop(sd_event *event);

🦋 DESCRIPTION 🦋

so, sd_event_run() — you use this to run a single iteration of the event loop that you passed in with the event parameter. one little lap around the track, no more. the function waits until there's actually an event to process (it's not out here doing busywork, it has boundaries) and then dispatches whatever handler you registered for it. and the usec parameter? that's the maximum time to wait for an event, measured in microseconds. and if you want to wait forever — like, no cap, forever — you hit it with (uint64_t) -1 for an infinite timeout. iconic. 💖

then there's sd_event_loop(), which is literally just sd_event_run() in a loop — and that is what actually implements the real, honest-to-god event loop. it keeps going and going, and the call returns as soon as exiting was requested via sd_event_exit(3). that's your off-ramp. 🛑

now — the event loop object event? you create that with sd_event_new(3). and the event sources you're waiting on, plus their handlers, get registered with any of these besties:

if you're the type who needs low-level control over event loop execution (respect, honestly), use sd_event_prepare(3), sd_event_wait(3) and sd_event_dispatch(3) — those three are the ones being wrapped by sd_event_run(). and together with sd_event_get_fd(3), this whole little friend group lets you integrate an sd-event(3) event loop into foreign event loop implementations. like, your loop can hang out with other loops. networking but make it social. 🫶

🔥 RETURN VALUE 🔥

when things go wrong, these functions return a negative errno-style error code. sad but true.

sd_event_run() is the interesting one: it returns a positive, non-zero integer if an event source was dispatched 🎉 — and it returns zero when the timeout you specified hit before any event source saw any event, which means no event source was dispatched. nothing happened, bestie. the clock just ran out.

sd_event_loop() returns the exit code you specified when you invoked sd_event_exit(). your code, your rules. 👑

😭 Errors

here's what the returned errors might be telling you:

  • -EINVAL — the event parameter is invalid or NULL. 💀
  • -EBUSY — the event loop object is not in the right state (peep sd_event_prepare(3) for an explanation of the possible states).
  • -ESTALE — the event loop is already terminated. it's gone, babe.
  • -ECHILD — the event loop was created in a different process, library or module instance. not your child, not your problem.
other errors are possible too, so don't come for me if you see something else. 🙈

🌸 NOTES 🌸

the functions described here are available as a shared library, which you can compile against and link to with the libsystemd pkg-config(1) file. slay. ✨

all functions listed here are thread-agnostic, and only a single thread may operate on a given object at any given time. different threads can access the same object at different times, and multiple independent objects can absolutely be used from different threads in parallel. so like… share the object, but not at the same time. consent matters, even for data structures. 💅

also — important — the code described here uses getenv(3), which is declared to be not multi-thread-safe. what that means for you: code calling the functions described here must not call setenv(3) from a parallel thread. the recommendation is to only do your setenv() calls from an early phase of the program, back when no other threads have been started. get in, get out, no drama. 🧚

⭐ HISTORY ⭐

sd_event_run() and sd_event_loop() were added in version 220. throwback era, honestly.

💜 SEE ALSO 💜

systemd(1), sd-event(3), 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_exit(3), sd_event_get_fd(3), sd_event_wait(3), GLib Main Event Loop[1]

Notes

  1. GLib Main Event Loop — https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html

okay that's the whole page 🍓 and just so you know exactly which vintage of the docs you're reading: this is systemd 261.3, page SD_EVENT_RUN(3). periodt. go run your loop, bestie, you're gonna eat 💖✨🌈

📦 where this page comes from