--- name: "wl_event_source" 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_source" --- # wl\_event\_source(3) An abstract event source. ## NAME wl\_event\_source - An abstract event source. ## SYNOPSIS \#include \ ### 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. This is the generic type for fd, timer, signal, and idle sources. Functions that operate on specific source types must not be used with a different type, even if the function signature allows it. ## Member Typedef Documentation ### typedef int(\* wl\_event\_loop\_fd\_func\_t) (int fd, uint32\_t mask, void \*data) File descriptor dispatch function type 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 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 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 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 **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. **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 **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. 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. **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 **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 the caller's responsibility to ensure that all other threads have also blocked the signal. **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 **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. **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 **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. ### int wl\_event\_source\_fd\_update (struct wl\_event\_source \* source, uint32\_t mask) Update a file descriptor source's event 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. **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 **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. ### int wl\_event\_source\_timer\_update (struct wl\_event\_source \* source, int ms\_delay) Arm or disarm a timer **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. ## Author Generated automatically by Doxygen for Wayland from the source code.