NAME

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