SD_EVENT_...ET_PREPARE(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_EVENT_SOURCE_SET_PREPARE — like, the prepare callback era 🎀

okay bestie, sit down, because this one is from sd_event_source_set_prepare in the systemd manual pages and it's genuinely such a serve ✨. It's giving "tell your event loop what to do right before it takes a lil nap" energy, and honestly? obsessed.

✨ SYNOPSIS ✨

#include <systemd/sd-event.h>

int sd_event_source_set_prepare(sd_event_source *source,
                                sd_event_handler_t callback);

typedef int (*sd_event_handler_t)(sd_event_source *s, void *userdata);

like, three lines, one typedef, zero drama. we love a minimal synopsis 🫶

🌸 DESCRIPTION 🌸

So sd_event_source_set_prepare() is the function you call when you wanna attach a preparation callback to the event source object you passed in as source. Cute, right? 💖

That callback function? It gets invoked immediately before the event loop goes to sleep to wait for incoming events. Yes, literally right before the nap. It's the "one more thing before bed" bestie. 🌙

It gets called with the user data pointer that was passed when the event source was created — same pointer, no substitutions, no surprises. 👑

And here's the tea: the event source will be disabled if the callback function returns a negative error code. So if your callback is out here returning -1, your source is getting benched. periodt. 💀

The callback function may be used to reconfigure the precise events to wait for. Very main character of it. 🔥

And if you pass NULL as the callback parameter? The callback function is reset. Gone. Clean slate. 🧚

🦋 the lore on defaults

Event source objects have no preparation callback associated when they're first created with calls such as sd_event_add_io(3), sd_event_add_time(3). So don't come looking for one — it's not there. 🙈

Preparation callback functions are supported for all event source types with the exception of those created with sd_event_add_exit(3). Not those. Never those. Don't try it. 😭

Preparation callback functions are dispatched in the order indicated by the event source's priority field, as set with sd_event_source_set_priority(3). Very organized, very "line leader" of them. ✨

And one more: preparation callbacks of disabled event sources (see sd_event_source_set_enabled(3)) are not invoked. Disabled means disabled, bestie. Vibe check failed, you're not getting called. 💅

🌈 RETURN VALUE 🌈

  • On success — sd_event_source_set_prepare() returns a non-negative integer. slay. ✨
  • On failure — it returns a negative errno-style error code. 😭

🍓 Errors

Returned errors may indicate the following problems:

  • -EINVAL — source is not a valid pointer to an sd_event_source object. like it's not even a real one bestie 💀
  • -ESTALE — The event loop is already terminated. RIP to that loop. 🪦
  • -ENOMEM — Not enough memory. the computer is full, no cap 😭
  • -ECHILD — The event loop has been created in a different process, library or module instance. it's not your loop, you can't claim it 🫶
  • -EDOM — The specified event source has been created with sd_event_add_exit(3). told you. we told you. 🙈

👑 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. link it, love it, live it. 🔗

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. So — one at a time per object, but everyone can have their moment. sharing is caring, scheduling is everything. 💅

⚠️ 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. seriously — no setenv() shenanigans from a parallel thread, that's a no from me 🚫

⭐ HISTORY ⭐

sd_event_source_set_prepare() and sd_event_handler_t() were added in version 229. vintage. iconic. still eating. 🍓

🌸 SEE ALSO 🌸

okay that's the whole page bestie, go forth and prepare your callbacks ✨💖 this one's from systemd 261.3 — mwah, catch you in the next manpage, iykyk 🎀🦋

📦 where this page comes from