wl_event_source(3)

📦
version 1.26.0 · 13 versions
, in arch rolling, fedora 43, fedora 44, nixpkgs unstable, ubuntu stonking

💖 wl_event_source 💖

okay bestie, welcome to the manual page for wl_event_source — it's a Library Functions Manual situation, and this one's genuinely a banger. she's abstract, she's iconic, and she's the reason your Wayland compositor doesn't just spin forever doing nothing. let's get into it 💅

✨ NAME ✨

wl_event_source — An abstract event source. that's it. that's the whole name. short, mysterious, main character energy fr fr 🌸

🌈 SYNOPSIS 🌈

#include <wayland-server-core.h>

🎀 Public Types

typedef int(* wl_event_loop_fd_func_t) (int fd, uint32_t mask, void
    *data)

typedef int(* wl_event_loop_timer_func_t) (void *data)

typedef int(* wl_event_loop_signal_func_t) (int signal_number, void
    *data)

typedef void(* wl_event_loop_idle_func_t) (void *data)

🦋 Public Member Functions

struct wl_event_source * wl_event_loop_add_fd (struct wl_event_loop
    *loop, int fd, uint32_t mask, wl_event_loop_fd_func_t func, void
    *data)

int wl_event_source_fd_update (struct wl_event_source *source, uint32_t
    mask)

struct wl_event_source * wl_event_loop_add_timer (struct wl_event_loop
    *loop, wl_event_loop_timer_func_t func, void *data)

int wl_event_source_timer_update (struct wl_event_source *source, int
    ms_delay)

struct wl_event_source * wl_event_loop_add_signal (struct wl_event_loop
    *loop, int signal_number, wl_event_loop_signal_func_t func, void
    *data)

struct wl_event_source * wl_event_loop_add_idle (struct wl_event_loop
    *loop, wl_event_loop_idle_func_t func, void *data)

void wl_event_source_check (struct wl_event_source *source)

int wl_event_source_remove (struct wl_event_source *source)

💜 Detailed Description 💜

An abstract event source.

so like. this is the generic type for fd, timer, signal, and idle sources. that's the whole vibe: one abstract mama type, four chaotic children.

🚨 important, bestie, do not skip this: functions that operate on specific source types must not be used with a different type, even if the function signature allows it. i know, i know, C lets you do it. C lets you do a lot of things. that does not mean you should. this is undefined behaviour territory and we do <em>not</em> go there 💀

🌸 Member Typedef Documentation 🌸

🧚 typedef int(* wl_event_loop_fd_func_t) (int fd, uint32_t mask, void *data)

File descriptor dispatch function type — she's the callback for file descriptor events, and she serves 💅

Functions of this type are used as callbacks for file descriptor events.

Parameters

  • fd — the file descriptor delivering the event.
  • mask — describes the kind of the event as a bitwise-or of: WL_EVENT_READABLE, WL_EVENT_WRITABLE, WL_EVENT_HANGUP, WL_EVENT_ERROR.
  • data — the user data argument of the related wl_event_loop_add_fd() call.

Returns

If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.

See also

wl_event_loop_add_fd()

🦋 typedef void(* wl_event_loop_idle_func_t) (void *data)

Idle task function type — she runs before the loop goes night-night 😴

Functions of this type are used as callbacks before blocking in wl_event_loop_dispatch().

Parameters

  • data — the user data argument of the related wl_event_loop_add_idle() call.

See also

wl_event_loop_add_idle() wl_event_loop_dispatch()

⭐ typedef int(* wl_event_loop_signal_func_t) (int signal_number, void *data)

Signal dispatch function type — POSIX signals, but make it a callback ✨

Functions of this type are used as callbacks for (POSIX) signals.

Parameters

  • signal_number
  • data — the user data argument of the related wl_event_loop_add_signal() call.

Returns

If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.

See also

wl_event_loop_add_signal()

⏰ typedef int(* wl_event_loop_timer_func_t) (void *data)

Timer dispatch function type — she goes off when the timer expires, and she goes off on time, periodt ⏳

Functions of this type are used as callbacks for timer expiry.

Parameters

  • data — the user data argument of the related wl_event_loop_add_timer() call.

Returns

If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.

See also

wl_event_loop_add_timer()

👑 Member Function Documentation 👑

💖 struct wl_event_source * wl_event_loop_add_fd (struct wl_event_loop * loop, int fd, uint32_t mask, wl_event_loop_fd_func_t func, void * data)

Create a file descriptor event source — new source just dropped 🎀

Parameters

  • loop — the event loop that will process the new source.
  • fd — the file descriptor to watch.
  • mask — a bitwise-or of which events to watch for: WL_EVENT_READABLE, WL_EVENT_WRITABLE.
  • func — the file descriptor dispatch function.
  • data — user data.

Returns

A new file descriptor event source.

The given file descriptor is initially watched for the events given in mask. This can be changed as needed with wl_event_source_fd_update().

If it is possible that program execution causes the file descriptor to be read while leaving the data in a buffer without actually processing it, it may be necessary to register the file descriptor source to be re-checked, see wl_event_source_check(). This will ensure that the dispatch function gets called even if the file descriptor is not readable or writable anymore. This is especially useful with IPC libraries that automatically buffer incoming data, possibly as a side-effect of other operations. (iykyk 😌)

See also

wl_event_loop_fd_func_t

💜 struct wl_event_source * wl_event_loop_add_idle (struct wl_event_loop * loop, wl_event_loop_idle_func_t func, void * data)

Create an idle task — lowkey the chillest source in the group chat 🌙

Parameters

  • loop — the event loop that will process the new task.
  • func — the idle task dispatch function.
  • data — user data.

Returns

A new idle task (an event source).

Idle tasks are dispatched before wl_event_loop_dispatch() goes to sleep. See wl_event_loop_dispatch() for more details.

Idle tasks fire once, and are automatically destroyed right after the callback function has been called. one and done, no encore, she ate and left no crumbs 🍓

An idle task can be cancelled before the callback has been called by wl_event_source_remove(). Calling wl_event_source_remove() after or from within the callback results in undefined behaviour. don't do it bestie i am begging 😭

See also

wl_event_loop_idle_func_t

🌈 struct wl_event_source * wl_event_loop_add_signal (struct wl_event_loop * loop, int signal_number, wl_event_loop_signal_func_t func, void * data)

Create a POSIX signal event source — signals but we're doing them synchronously now, slay ✨

Parameters

  • loop — the event loop that will process the new source.
  • signal_number — number of the signal to watch for.
  • func — the signal dispatch function.
  • data — user data.

Returns

A new signal event source.

This function blocks the normal delivery of the given signal in the calling thread, and creates a "watch" for it. Signal delivery no longer happens asynchronously, but by wl_event_loop_dispatch() calling the dispatch callback function func.

🫶 It is <strong>the caller's responsibility</strong> to ensure that all other threads have also blocked the signal. every. single. thread. no cap.

See also

wl_event_loop_signal_func_t

⏳ struct wl_event_source * wl_event_loop_add_timer (struct wl_event_loop * loop, wl_event_loop_timer_func_t func, void * data)

Create a timer event source — she exists but she's not armed yet, she's just vibing 🔥

Parameters

  • loop — the event loop that will process the new source.
  • func — the timer dispatch function.
  • data — user data.

Returns

A new timer event source.

The timer is initially disarmed. It needs to be armed with a call to wl_event_source_timer_update() before it can trigger a dispatch call. so like, she's here, she's ready, but you gotta actually ask her to go off 💅

See also

wl_event_loop_timer_func_t

🎀 void wl_event_source_check (struct wl_event_source * source)

Mark event source to be re-checked — the "are we done? are we SURE we're done?" button 🔁

Parameters

  • source — the event source to be re-checked.

This function permanently marks the event source to be re-checked after the normal dispatch of sources in wl_event_loop_dispatch(). Re-checking will keep iterating over all such event sources until the dispatch function for them all returns zero.

Re-checking is used on sources that may become ready to dispatch as a side-effect of dispatching themselves or other event sources, including idle sources. Re-checking ensures all the incoming events have been fully drained before wl_event_loop_dispatch() returns. fully drained. no leftovers. she checked under the bed and everything 🧚

🦋 int wl_event_source_fd_update (struct wl_event_source * source, uint32_t mask)

Update a file descriptor source's event mask — glow-up for your mask 💅

Parameters

  • source — the file descriptor event source to update.
  • mask — the new mask, a bitwise-or of: WL_EVENT_READABLE, WL_EVENT_WRITABLE.

Returns

0 on success, -1 on failure.

This changes which events, readable and/or writable, cause the dispatch callback to be called on.

File descriptors are usually writable to begin with, so they do not need to be polled for writable until a write actually fails. When a write fails, the event mask can be changed to poll for readable and writable, delivering a dispatch callback when it is possible to write more. Once all data has been written, the mask can be changed to poll only for readable to avoid busy-looping on dispatch. (avoid busy-looping bestie, she's not built for that level of chaos 🙈)

See also

wl_event_loop_add_fd()

💀 int wl_event_source_remove (struct wl_event_source * source)

Remove an event source from its event loop — it's over, she's leaving the group chat ✌️

Parameters

  • source — the event source to be removed.

Returns

Zero.

The event source is removed from the event loop it was created for, and is effectively destroyed. This invalidates source. The dispatch function of the source will no longer be called through this source.

⚠️ yeah, source is cooked after this. do not touch it. do not look at it. do not call it. it is gone, and any pointer you keep is a ghost 👻

⭐ int wl_event_source_timer_update (struct wl_event_source * source, int ms_delay)

Arm or disarm a timer — the on/off switch, the arming and the disarming, she does both 🌟

Parameters

  • source — the timer event source to modify.
  • ms_delay — the timeout in milliseconds.

Returns

0 on success, -1 on failure.

If the timeout is zero, the timer is disarmed.

If the timeout is non-zero, the timer is set to expire after the given timeout in milliseconds. When the timer expires, the dispatch function set with wl_event_loop_add_timer() is called once from wl_event_loop_dispatch(). If another dispatch is desired after another expiry, wl_event_source_timer_update() needs to be called again. yes, again. and again. that's the whole bit, that's the whole trick 🎯

🌟 Author 🌟

Generated automatically by Doxygen for Wayland from the source code. (yes bestie, even the author section is autogenerated, she didn't write this one by hand, she's a robot and she's thriving 🤖💖)

and that's the whole page!! 💅 Wayland, Version 1.26.0, manual page wl_event_source(3) — thanks for reading my little manpage TED talk, now go block those signals in every thread, mwah 🫶🎀✨

📦 where this page comes from