SD_EVENT_NEW(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_EVENT_NEW(3) — the sd_event_new girlies' guide 🎀

okay so this is sd_event_new(3), from the systemd manual, and bestie we are about to get so comfy with event loop objects. sit down, grab a boba, this is gonna slay ✨

🌸 NAME 🌸

sd_event_new, sd_event_default, sd_event_ref, sd_event_unref, sd_event_unrefp, sd_event_get_tid, sd_event — literally just: acquire and release an event loop object 💖

✨ SYNOPSIS ✨

#include <systemd/sd-event.h>

typedef struct sd_event sd_event;

int sd_event_new(sd_event **event);

int sd_event_default(sd_event **event);

sd_event *sd_event_ref(sd_event *event);

sd_event *sd_event_unref(sd_event *event);

void sd_event_unrefp(sd_event **event);

int sd_event_get_tid(sd_event *event, pid_t *ret);

🦋 DESCRIPTION 🦋

the birthing of a loop: sd_event_new()

sd_event_new() allocates a brand new event loop object, and hands it back to you in the event parameter. it's giving newborn main character energy 👑

after you're done using it, drop that reference with sd_event_unref(). and when the last reference is dropped — poof — the object is freed. no cap.

the group chat: sd_event_default()

sd_event_default() acquires a reference to the default event loop object of the calling thread. and like, if no default event loop object has been allocated yet for that thread? it'll possibly allocate a new one for you. so generous of it 🫶

after use, drop the returned reference with sd_event_unref(). when the last reference is dropped, the event loop is freed.

and here's the iconic part: if this function is called while the object returned from a previous call from the same thread is still referenced, the same object is returned again — but the reference count goes up by one. lowkey the same bestie, just counted twice 💅

bestie, it is recommended to use this call instead of sd_event_new() so that event loop objects can be shared between various components dispatched in the same thread. all threads have exactly either zero or one default event loop objects associated — but never more. periodt.

and then you feed it 👀

after allocating an event loop object, you add event sources to it with 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_add_post(3) or sd_event_add_exit(3) — and then you execute the event loop using sd_event_loop(3). that's the whole meal. ate. 🔥

refcounting, the remix

  • sd_event_ref() — increases the reference count of the specified event loop object by one. simple. clean. ✨
  • sd_event_unref() — decreases the reference count of the specified event loop object by one. if the count hits zero, the object is freed. 😭
⚠️ okay important: it is freed regardless of whether it is the default event loop object for a thread or not. which means — and this is the messy part — allocating an event loop with sd_event_default(), then releasing it, then acquiring a new one with sd_event_default() will result in two distinct objects. not the same one. two. different. objects. 💀
also note: in order to free an event loop object, all remaining event sources of the event loop also need to be freed, because each one keeps a reference to it. it's very "you can't leave the party until everyone leaves the party" energy.

the cleanup queen: sd_event_unrefp()

sd_event_unrefp() is similar to sd_event_unref(), except it takes a pointer to a pointer to an sd_event object. honestly so useful when paired with GCC's and LLVM's Clean-up Variable Attribute[1]. note that this function is defined as an inline function 🧚

use a declaration like the following so your event loop object frees itself automatically as the code block is left:

{
        __attribute__((cleanup(sd_event_unrefp))) sd_event *event = NULL;
        int r;
        ...
        r = sd_event_default(&event);
        if (r < 0) {
          errno = -r;
          fprintf(stderr, "Failed to allocate event loop: %m\n");
        }
        ...
}

so organized. the code block ends, the object cleans itself up. self-care honestly 🌸

the NULL clause 🫶

sd_event_ref(), sd_event_unref() and sd_event_unrefp() execute no operation if the passed-in event loop object is NULL. they simply do not perceive it. 🙈

whose thread is this anyway: sd_event_get_tid()

sd_event_get_tid() retrieves the thread identifier ("TID") of the thread the specified event loop object is associated with. it returns the identifier for the thread the event loop is the default event loop of.

🚨 this call is only supported for event loops allocated with sd_event_default(). don't try it on anything else.

see gettid(2) for more info on thread identifiers. iykyk ⭐

👑 RETURN VALUE 👑

on success, sd_event_new(), sd_event_default() and sd_event_get_tid() return 0 or a positive integer. slay.

on failure, they return a negative errno-style error code. 😭

sd_event_ref() always returns a pointer to the event loop object passed in. sd_event_unref() always returns NULL. always. no thoughts head empty.

💀 Errors 💀

returned errors may indicate the following problems:

  • -ENOMEM — not enough memory to allocate the object. she's out of RAM, bestie.
  • -EMFILE — the maximum number of event loops has been allocated. you hit the limit, the limit hit back.
  • -ENXIO — sd_event_get_tid() was invoked on an event loop object that was not allocated with sd_event_default(). wrong loop, wrong vibe, denied.

🌈 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 — that part's fine, just not the same object simultaneously, okay? 💅

⚠️ the code described here uses getenv(3), which is declared to be not multi-thread-safe. this means 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. like, get it out of the way first, then start your threads. timing is everything fr fr ⭐

🌸 HISTORY 🌸

  • sd_event_new(), sd_event_default(), sd_event_ref(), and sd_event_unref() were added in version 213.
  • sd_event_unrefp() and sd_event_get_tid() were added in version 229.

glow-up timeline, honestly. 👑

🫶 SEE ALSO 🫶

systemd(1), sd-event(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), gettid(2)

go read those next, bestie, the rabbit hole is deep 🐇✨

🎀 NOTES 🎀

  1. Clean-up Variable Attribute — https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
💖 okay that's the whole page!! this was systemd version 261.3 of SD_EVENT_NEW(3) — mwah, love u, go refcount responsibly 💋✨ — your girl, signing off 💅
📦 where this page comes from