.TH "wl_event_source" 3 "Wed Sep 5 2018" "Version 1.16.0" "Wayland" \" -*- nroff -*- .ad l .nh .SH NAME wl_event_source \- An abstract event source\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .SS "Public Types" .in +1c .ti -1c .RI "typedef int(* \fBwl_event_loop_fd_func_t\fP) (int fd, uint32_t mask, void *data)" .br .ti -1c .RI "typedef int(* \fBwl_event_loop_timer_func_t\fP) (void *data)" .br .ti -1c .RI "typedef int(* \fBwl_event_loop_signal_func_t\fP) (int signal_number, void *data)" .br .ti -1c .RI "typedef void(* \fBwl_event_loop_idle_func_t\fP) (void *data)" .br .in -1c .SS "Public Member Functions" .in +1c .ti -1c .RI "struct \fBwl_event_source\fP * \fBwl_event_loop_add_fd\fP (struct \fBwl_event_loop\fP *loop, int fd, uint32_t mask, \fBwl_event_loop_fd_func_t\fP func, void *data)" .br .ti -1c .RI "int \fBwl_event_source_fd_update\fP (struct \fBwl_event_source\fP *source, uint32_t mask)" .br .ti -1c .RI "struct \fBwl_event_source\fP * \fBwl_event_loop_add_timer\fP (struct \fBwl_event_loop\fP *loop, \fBwl_event_loop_timer_func_t\fP func, void *data)" .br .ti -1c .RI "int \fBwl_event_source_timer_update\fP (struct \fBwl_event_source\fP *source, int ms_delay)" .br .ti -1c .RI "struct \fBwl_event_source\fP * \fBwl_event_loop_add_signal\fP (struct \fBwl_event_loop\fP *loop, int signal_number, \fBwl_event_loop_signal_func_t\fP func, void *data)" .br .ti -1c .RI "struct \fBwl_event_source\fP * \fBwl_event_loop_add_idle\fP (struct \fBwl_event_loop\fP *loop, \fBwl_event_loop_idle_func_t\fP func, void *data)" .br .ti -1c .RI "void \fBwl_event_source_check\fP (struct \fBwl_event_source\fP *source)" .br .ti -1c .RI "int \fBwl_event_source_remove\fP (struct \fBwl_event_source\fP *source)" .br .in -1c .SH "Detailed Description" .PP 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\&. .SH "Member Typedef Documentation" .PP .SS "typedef int(* wl_event_loop_fd_func_t) (int fd, uint32_t mask, void *data)" File descriptor dispatch function type .PP Functions of this type are used as callbacks for file descriptor events\&. .PP \fBParameters:\fP .RS 4 \fIfd\fP The file descriptor delivering the event\&. .br \fImask\fP Describes the kind of the event as a bitwise-or of: \fCWL_EVENT_READABLE\fP, \fCWL_EVENT_WRITABLE\fP, \fCWL_EVENT_HANGUP\fP, \fCWL_EVENT_ERROR\fP\&. .br \fIdata\fP The user data argument of the related \fBwl_event_loop_add_fd()\fP call\&. .RE .PP \fBReturns:\fP .RS 4 If the event source is registered for re-check with \fBwl_event_source_check()\fP: 0 for all done, 1 for needing a re-check\&. If not registered, the return value is ignored and should be zero\&. .RE .PP \fBSee also:\fP .RS 4 \fBwl_event_loop_add_fd()\fP .RE .PP .SS "typedef void(* wl_event_loop_idle_func_t) (void *data)" Idle task function type .PP Functions of this type are used as callbacks before blocking in \fBwl_event_loop_dispatch()\fP\&. .PP \fBParameters:\fP .RS 4 \fIdata\fP The user data argument of the related \fBwl_event_loop_add_idle()\fP call\&. .RE .PP \fBSee also:\fP .RS 4 \fBwl_event_loop_add_idle()\fP \fBwl_event_loop_dispatch()\fP .RE .PP .SS "typedef int(* wl_event_loop_signal_func_t) (int signal_number, void *data)" Signal dispatch function type .PP Functions of this type are used as callbacks for (POSIX) signals\&. .PP \fBParameters:\fP .RS 4 \fIsignal_number\fP .br \fIdata\fP The user data argument of the related \fBwl_event_loop_add_signal()\fP call\&. .RE .PP \fBReturns:\fP .RS 4 If the event source is registered for re-check with \fBwl_event_source_check()\fP: 0 for all done, 1 for needing a re-check\&. If not registered, the return value is ignored and should be zero\&. .RE .PP \fBSee also:\fP .RS 4 \fBwl_event_loop_add_signal()\fP .RE .PP .SS "typedef int(* wl_event_loop_timer_func_t) (void *data)" Timer dispatch function type .PP Functions of this type are used as callbacks for timer expiry\&. .PP \fBParameters:\fP .RS 4 \fIdata\fP The user data argument of the related \fBwl_event_loop_add_timer()\fP call\&. .RE .PP \fBReturns:\fP .RS 4 If the event source is registered for re-check with \fBwl_event_source_check()\fP: 0 for all done, 1 for needing a re-check\&. If not registered, the return value is ignored and should be zero\&. .RE .PP \fBSee also:\fP .RS 4 \fBwl_event_loop_add_timer()\fP .RE .PP .SH "Member Function Documentation" .PP .SS "struct \fBwl_event_source\fP * wl_event_loop_add_fd (struct \fBwl_event_loop\fP * loop, int fd, uint32_t mask, \fBwl_event_loop_fd_func_t\fP func, void * data)" Create a file descriptor event source .PP \fBParameters:\fP .RS 4 \fIloop\fP The event loop that will process the new source\&. .br \fIfd\fP The file descriptor to watch\&. .br \fImask\fP A bitwise-or of which events to watch for: \fCWL_EVENT_READABLE\fP, \fCWL_EVENT_WRITABLE\fP\&. .br \fIfunc\fP The file descriptor dispatch function\&. .br \fIdata\fP User data\&. .RE .PP \fBReturns:\fP .RS 4 A new file descriptor event source\&. .RE .PP The given file descriptor is initially watched for the events given in \fCmask\fP\&. This can be changed as needed with \fBwl_event_source_fd_update()\fP\&. .PP 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 \fBwl_event_source_check()\fP\&. 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\&. .PP \fBSee also:\fP .RS 4 \fBwl_event_loop_fd_func_t\fP .RE .PP .SS "struct \fBwl_event_source\fP * wl_event_loop_add_idle (struct \fBwl_event_loop\fP * loop, \fBwl_event_loop_idle_func_t\fP func, void * data)" Create an idle task .PP \fBParameters:\fP .RS 4 \fIloop\fP The event loop that will process the new task\&. .br \fIfunc\fP The idle task dispatch function\&. .br \fIdata\fP User data\&. .RE .PP \fBReturns:\fP .RS 4 A new idle task (an event source)\&. .RE .PP Idle tasks are dispatched before \fBwl_event_loop_dispatch()\fP goes to sleep\&. See \fBwl_event_loop_dispatch()\fP for more details\&. .PP Idle tasks fire once, and are automatically destroyed right after the callback function has been called\&. .PP An idle task can be cancelled before the callback has been called by \fBwl_event_source_remove()\fP\&. Calling \fBwl_event_source_remove()\fP after or from within the callback results in undefined behaviour\&. .PP \fBSee also:\fP .RS 4 \fBwl_event_loop_idle_func_t\fP .RE .PP .SS "struct \fBwl_event_source\fP * wl_event_loop_add_signal (struct \fBwl_event_loop\fP * loop, int signal_number, \fBwl_event_loop_signal_func_t\fP func, void * data)" Create a POSIX signal event source .PP \fBParameters:\fP .RS 4 \fIloop\fP The event loop that will process the new source\&. .br \fIsignal_number\fP Number of the signal to watch for\&. .br \fIfunc\fP The signal dispatch function\&. .br \fIdata\fP User data\&. .RE .PP \fBReturns:\fP .RS 4 A new signal event source\&. .RE .PP 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 \fBwl_event_loop_dispatch()\fP calling the dispatch callback function \fCfunc\fP\&. .PP It is the caller's responsibility to ensure that all other threads have also blocked the signal\&. .PP \fBSee also:\fP .RS 4 \fBwl_event_loop_signal_func_t\fP .RE .PP .SS "struct \fBwl_event_source\fP * wl_event_loop_add_timer (struct \fBwl_event_loop\fP * loop, \fBwl_event_loop_timer_func_t\fP func, void * data)" Create a timer event source .PP \fBParameters:\fP .RS 4 \fIloop\fP The event loop that will process the new source\&. .br \fIfunc\fP The timer dispatch function\&. .br \fIdata\fP User data\&. .RE .PP \fBReturns:\fP .RS 4 A new timer event source\&. .RE .PP The timer is initially disarmed\&. It needs to be armed with a call to \fBwl_event_source_timer_update()\fP before it can trigger a dispatch call\&. .PP \fBSee also:\fP .RS 4 \fBwl_event_loop_timer_func_t\fP .RE .PP .SS "void wl_event_source_check (struct \fBwl_event_source\fP * source)" Mark event source to be re-checked .PP \fBParameters:\fP .RS 4 \fIsource\fP The event source to be re-checked\&. .RE .PP This function permanently marks the event source to be re-checked after the normal dispatch of sources in \fBwl_event_loop_dispatch()\fP\&. Re-checking will keep iterating over all such event sources until the dispatch function for them all returns zero\&. .PP 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 \fBwl_event_loop_dispatch()\fP returns\&. .SS "int wl_event_source_fd_update (struct \fBwl_event_source\fP * source, uint32_t mask)" Update a file descriptor source's event mask .PP \fBParameters:\fP .RS 4 \fIsource\fP The file descriptor event source to update\&. .br \fImask\fP The new mask, a bitwise-or of: \fCWL_EVENT_READABLE\fP, \fCWL_EVENT_WRITABLE\fP\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on failure\&. .RE .PP This changes which events, readable and/or writable, cause the dispatch callback to be called on\&. .PP 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\&. .PP \fBSee also:\fP .RS 4 \fBwl_event_loop_add_fd()\fP .RE .PP .SS "int wl_event_source_remove (struct \fBwl_event_source\fP * source)" Remove an event source from its event loop .PP \fBParameters:\fP .RS 4 \fIsource\fP The event source to be removed\&. .RE .PP \fBReturns:\fP .RS 4 Zero\&. .RE .PP The event source is removed from the event loop it was created for, and is effectively destroyed\&. This invalidates \fCsource\fP \&. The dispatch function of the source will no longer be called through this source\&. .SS "int wl_event_source_timer_update (struct \fBwl_event_source\fP * source, int ms_delay)" Arm or disarm a timer .PP \fBParameters:\fP .RS 4 \fIsource\fP The timer event source to modify\&. .br \fIms_delay\fP The timeout in milliseconds\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on failure\&. .RE .PP If the timeout is zero, the timer is disarmed\&. .PP 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 \fBwl_event_loop_add_timer()\fP is called once from \fBwl_event_loop_dispatch()\fP\&. If another dispatch is desired after another expiry, \fBwl_event_source_timer_update()\fP needs to be called again\&. .SH "Author" .PP Generated automatically by Doxygen for Wayland from the source code\&.