wl_event_source - Man Page

An abstract event source​.

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

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

Info

Version 1.26.0 Wayland