wl_event_loop(3)

✨ NAME ✨

wl_event_loop — An event loop context. 💖

---

🌸 SYNOPSIS 🌸

#include <wayland-server-core.h>

🎀 Public Member Functions 🎀

struct wl_event_loop * wl_event_loop_create (void)
void wl_event_loop_destroy (struct wl_event_loop *loop)
void wl_event_loop_dispatch_idle (struct wl_event_loop *loop)
int wl_event_loop_dispatch (struct wl_event_loop *loop, int timeout)
int wl_event_loop_get_fd (struct wl_event_loop *loop)
void wl_event_loop_add_destroy_listener (struct wl_event_loop *loop,
    struct wl_listener *listener)
struct wl_listener * wl_event_loop_get_destroy_listener (struct
    wl_event_loop *loop, wl_notify_func_t notify)

---

🦋 Detailed Description 🦋

An event loop context. That's the whole vibe, bestie. 💅

So like, the usual routine is: you create an event loop context, you add sources to it, and then you call wl_event_loop_dispatch() in a loop to process events. That's it. That's the whole life cycle. Iconic, honestly. ✨

See also wl_event_source — go read that one too, no cap. 🫶

---

👑 Member Function Documentation 👑

💜 void wl_event_loop_add_destroy_listener (struct wl_event_loop * loop, struct wl_listener * listener)

Register a destroy listener for an event loop context. So when the loop gets destroyed, your callback gets called. Not me setting up a little goodbye party for my event loop 😭🎀

Parameters

• loop — The event loop context whose destruction to listen for.
• listener — The listener with the callback to be called.

See also wl_listener

---

💜 struct wl_event_loop * wl_event_loop_create (void )

Create a new event loop context. Fresh out the box, brand new, main character energy. 🌈

Returns

• A new event loop context object.

This creates a new event loop context. Initially this context is empty — like, nothing in it at all. Event sources need to be explicitly added to it. She's not gonna go find them herself, okay? You have to introduce them. 🙈

Normally the event loop is run by calling wl_event_loop_dispatch() in a loop until the program terminates. Alternatively, an event loop can be embedded in another event loop by its file descriptor — see wl_event_loop_get_fd(). Loops inside loops, it's giving inception fr fr. 🌀

---

💜 void wl_event_loop_destroy (struct wl_event_loop * loop)

Destroy an event loop context. Rip bozo, but make it graceful. 💀🌸

Parameters

• loop — The event loop to be destroyed.

This emits the event loop destroy signal, closes the event loop file descriptor, and frees loop. Clean exit, slay. ✨

⚠️ Okay this part is IMPORTANT, bestie, listen up: If the event loop has existing sources, those cannot be safely removed afterwards. So you must call wl_event_source_remove() on all event sources before destroying the event loop context. Do not skip this. Do not be cute about it. Do not pass go. 😤

---

💜 int wl_event_loop_dispatch (struct wl_event_loop * loop, int timeout)

Wait for events and dispatch them. The main event, literally. 🔥

Parameters

• loop — The event loop whose sources to wait for.
• timeout — The polling timeout in milliseconds.

Returns

• 0 for success, -1 for polling (or timer update) error.

All the associated event sources are polled. This function blocks until any event source delivers an event (idle sources excluded), or the timeout expires. A timeout of -1 disables the timeout, causing the function to block indefinitely (she will wait forever, and she means it 💅). A timeout of zero causes the poll to always return immediately.

All idle sources are dispatched before blocking. An idle source is destroyed when it is dispatched. After blocking, all other ready sources are dispatched. Then, idle sources are dispatched again, in case the dispatched events created idle sources. Finally, all sources marked with wl_event_source_check() are dispatched in a loop until their dispatch functions all return zero.

That order matters, okay? Pre-block idles → block → other ready sources → idles again → checked sources in a loop. It's a whole choreography. 🩰

---

💜 void wl_event_loop_dispatch_idle (struct wl_event_loop * loop)

Dispatch the idle sources. Just the idles. Nothing but the idles. 🍓

Parameters

• loop — The event loop whose idle sources are dispatched.

See also wl_event_loop_add_idle()

---

💜 struct wl_listener * wl_event_loop_get_destroy_listener (struct wl_event_loop * loop, wl_notify_func_t notify)

Get the listener struct for the specified callback. Like a little detective mission for one specific callback. 🔍

Parameters

• loop — The event loop context to inspect.
• notify — The destroy callback to find.

Returns

• The wl_listener registered to the event loop context with the given callback pointer.

---

💜 int wl_event_loop_get_fd (struct wl_event_loop * loop)

Get the event loop file descriptor. The aggregate one, the whole squad in a single fd. 🫶

Parameters

• loop — The event loop context.

Returns

• The aggregate file descriptor.

This function returns the aggregate file descriptor, that represents all the event sources (idle sources excluded) associated with the given event loop context. When any event source makes an event available, it will be reflected in the aggregate file descriptor. One fd to represent them all. ✨

When the aggregate file descriptor delivers an event, one can call wl_event_loop_dispatch() on the event loop context to dispatch all the available events. Simple as that, no cap. 💖

---

🌟 Author 🌟

Generated automatically by Doxygen for Wayland from the source code. Not a human, just a robot doing its little thing 🤖✨

---

And that's the whole page, bestie!! This was wl_event_loop(3) from Wayland, Version 1.26.0 — mwah, go forth and dispatch your events responsibly. 💅🎀🦋