---
name: "wl_event_loop"
section: "3"
platform: "linux"
package: "wayland-docs"
version: "1.26.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/wl_event_loop"
---

# wl\_event\_loop(3)

An event loop context.

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

Usually you create an event loop context, add sources to it, and call **wl\_event\_loop\_dispatch()** in a loop to process events.

**See also**

**wl\_event\_source**

## 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

**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

**Returns**

A new event loop context object.

This creates a new event loop context. Initially this context is empty. Event sources need to be explicitly added to it.

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()**.

### void wl\_event\_loop\_destroy (struct wl\_event\_loop \* loop)

Destroy an event loop context

**Parameters**

*loop* The event loop to be destroyed.

This emits the event loop destroy signal, closes the event loop file descriptor, and frees loop.

If the event loop has existing sources, those cannot be safely removed afterwards. Therefore one must call **wl\_event\_source\_remove()** on all event sources before destroying the event loop context.

### int wl\_event\_loop\_dispatch (struct wl\_event\_loop \* loop, int timeout)

Wait for events and dispatch them

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

### void wl\_event\_loop\_dispatch\_idle (struct wl\_event\_loop \* loop)

Dispatch the idle sources

**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

**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

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

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.

## Author

Generated automatically by Doxygen for Wayland from the source code.