SD_EVENT_SOURCE_UNREF(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_EVENT_SOURCE_UNREF(3) — the sd_event_source_unref page, bestie edition

okay so this is the SD_EVENT_SOURCE_UNREF(3) manual page (yep, from the sd_event_source_unref family, she's the main character of this file) and she's here to teach you about reference counters on event sources. ngl it's lowkey iconic how much these tiny functions do. let's go 💖

✨ NAME ✨

sd_event_source_unref, sd_event_source_unrefp, sd_event_source_ref, sd_event_source_disable_unref, sd_event_source_disable_unrefp — increase or decrease event source reference counters, that's the whole vibe 🎀

🌸 SYNOPSIS 🌸

#include <systemd/sd-event.h>

sd_event_source* sd_event_source_unref(sd_event_source *source);

void sd_event_source_unrefp(sd_event_source **source);

sd_event_source* sd_event_source_ref(sd_event_source *source);

sd_event_source* sd_event_source_disable_unref(sd_event_source *source);

void sd_event_source_disable_unrefp(sd_event_source **source);

🦋 DESCRIPTION 🦋

  • sd_event_source_unref() — use this to decrement by one the internal reference counter of the event source object you passed as source. The counter starts out at one when the event source gets created, via calls like sd_event_add_io(3) or sd_event_add_time(3). And the second the counter hits zero? the object gets detached from the event loop object and destroyed. bye bestie 👋
  • sd_event_source_unrefp() — basically sd_event_source_unref()'s sibling, except she takes a pointer to a pointer to an sd_event_source object. This one is so useful with GCC's and LLVM's Clean-up Variable Attribute[1]. Note: this function is defined as an inline function. 🧚
  • sd_event_source_ref() — the opposite direction, queen: increase by one the internal reference counter of the event source object you handed her as source.
  • so here's a fun little quirk: sd_event_source_unref(), sd_bus_creds_unrefp() and sd_bus_creds_ref() execute no operation if the event source object you passed is NULL. no drama, no crash, just vibes 💀
⚠️ real talk though: event source objects stay alive and may be dispatched as long as they have a reference counter greater than zero. so if you want to drop a reference of an event source and make sure the associated event source handler function is not called anymore, the move is to combine a call of sd_event_source_unref() with a prior call to sd_event_source_set_enabled() with SD_EVENT_OFF — or just call sd_event_source_disable_unref(), see below. no cap, do this.
  • sd_event_source_disable_unref() — she's the combo meal 🍓: a call to sd_event_source_set_enabled() with SD_EVENT_OFF plus sd_event_source_unref(). This ensures the source is disabled before the local reference to it is lost. And good news — the source parameter is allowed to be NULL.
  • sd_event_source_disable_unrefp() — similar to sd_event_source_unrefp(), but in addition it disables the source first. Same deal as before: useful with GCC's and LLVM's Clean-up Variable Attribute[1], and note that this function is defined as an inline function. 🫶

🔥 RETURN VALUE 🔥

sd_event_source_unref() and sd_event_source_disable_unref() always return NULL. and sd_event_source_ref() always returns the event source object you passed in. she gives back what you gave her, periodt.

👑 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. (yes, it's giving "share the toy but one at a time" 🎀)

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

🌈 HISTORY 🌈

  • sd_event_source_unref(), sd_event_source_unrefp(), and sd_event_source_ref() were added in version 229.
  • sd_event_source_disable_unref() and sd_event_source_disable_unrefp() were added in version 243.

glow-up timeline, honestly. 💅

⭐ SEE ALSO ⭐

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_source_set_enabled(3) — go read all of them, iykyk 🦋

📎 NOTES (the footnote one)

  1. Clean-up Variable Attribute — https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html

and that's the page!! this one shipped with systemd 261.3, so if you're quoting her in a group chat, cite her properly 🫶 mwah, go unref something responsibly 💖

📦 where this page comes from