From b9dc5cff35d301d869eaa7fd774fad1c85d20077 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 8 Apr 2023 16:21:22 +0000 Subject: [PATCH] New manual page written by Ted Bullock , providing more information and in a more systematic way than the current event(3) manual page. Not yet linked to the tree. Using input from nicm@ and jmc@. --- lib/libevent/event_base_loop.3 | 210 +++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 lib/libevent/event_base_loop.3 diff --git a/lib/libevent/event_base_loop.3 b/lib/libevent/event_base_loop.3 new file mode 100644 index 00000000000..5ce6b81ad88 --- /dev/null +++ b/lib/libevent/event_base_loop.3 @@ -0,0 +1,210 @@ +.\" $OpenBSD: event_base_loop.3,v 1.1 2023/04/08 16:21:22 schwarze Exp $ +.\" Copyright (c) 2023 Ted Bullock +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: April 8 2023 $ +.Dt EVENT_BASE_LOOP 3 +.Os +.Sh NAME +.Nm event_base_loop , +.Nm event_loop , +.Nm event_base_dispatch , +.Nm event_dispatch +.Nd run an event loop +.Sh SYNOPSIS +.In event.h +.Ft int +.Fn event_base_loop "struct event_base *base" "int flags" +.Ft int +.Fn event_loop "int flags" +.Ft int +.Fn event_base_dispatch "struct event_base *base" +.Ft int +.Fn event_dispatch void +.Fd #define EVLOOP_ONCE 0x01 +.Fd #define EVLOOP_NONBLOCK 0x02 +.Sh DESCRIPTION +An event loop waits for and dispatches events in a program. +This enables asynchronous programming, allowing a program to perform other +tasks while waiting for an event to occur. +Asynchronous programming is a useful idiom for handling multiple I/O +operations, such as network connections, user interfaces, or disk operations +without blocking the main loop of a program. +The event loop continuously processes events and executes callbacks associated +with each event as they occur. +.Pp +The +.Fn event_base_loop +family of functions start an event loop that replaces the main loop of a +program. +By default, they return when there are no more scheduled events. +.Pp +There are three types of events these functions monitor including signal, +kernel and timer. +Events involving POSIX signals are configured with +.Xr signal_set 3 . +Kernel events such as network activity and changes to file descriptors are +configured with +.Xr event_set 3 . +Timer events are configured with +.Xr evtimer_set 3 . +.Pp +The event library further categorizes event states as: +.Bl -tag -width "Initialized:" +.It Sy Initialized : +These have been configured with +.Xr event_set 3 +and not yet registered with an event loop. +.It Sy Scheduled : +These are registered to a loop using +.Xr event_add 3 +and are idle, waiting to trigger and be processed by the loop. +They can be be queried with +.Fn event_pending 3 . +.It Sy Activated : +These are triggered events. +The loop processes events until all +.Sy activated +events are resolved, some of these such as signals, may persist and become +.Sy scheduled +events again. +.El +.Pp +.Fn event_base_loop +starts an event loop, it takes two arguments: +.Bl -tag -width 6n +.It Fa base : +A pointer to an +.Vt event_base +structure returned from +.Xr event_init 3 +or +.Xr event_base_new 3 . +The behavior is undefined if +.Fa base +is +.Dv NULL . +.It Fa flags : +A set of flags that modify the behavior of the event loop. +The following flags are available: +.Pp +.Bl -hyphen -compact -width 1n +.It +.Dv EVLOOP_ONCE : +Run the event loop for one iteration and then return. +This is useful for a main program that needs to perform actions outside +the event loop. +.It +.Dv EVLOOP_NONBLOCK : +Run the event loop in non-blocking mode. +The loop returns after processing activated signal and kernel events and does +not wait for timer events to expire. +.El +.El +.Pp +The function +.Fn event_loop +is a version of +.Fn event_base_loop +that requires the library to be initialized by +.Xr event_init 3 . +The function has one argument, +.Fa flags , +with the same attributes as +.Fn event_base_loop . +.Pp +.Fn event_base_dispatch +is equivalent to calling +.Fn event_base_loop +with +.Fa flags +set to zero. +Likewise, +.Fn event_dispatch +is the same as invoking +.Fn event_loop +with +.Fa flags +set to zero. +.Sh RETURN VALUES +The event loop functions return: +.Pp +.Bl -tag -compact -offset 3n -width 3n +.It \-1 +on error, +.Va errno +is set. +.It 0 +on success, asked to terminate loop. +.It 1 +on success, no remaining events left or scheduled in queue. +.El +.Sh ERRORS +These functions have complex interactions with +.Va errno . +Error conditions that set +.Va errno +change corresponding to the kernel notification method the event library is +using. +These values directly correspond to +.Xr kevent 2 , +.Xr poll 2 +or +.Xr select 2 +system calls and default to +.Xr kevent 2 +on +.Ox . +Refer to +.Xr event_base_new 3 +for details on kernel notification methods. +.Bl -tag -width Er +.It Bq Er EINTR +Although the kernel notification methods can set +.Va errno +to +.Er EINTR , +.Fn event_base_loop +and related functions never fail with +.Va errno +set to +.Er EINTR . +.El +.Sh SEE ALSO +.Xr kevent 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr event_base_new 3 , +.Xr event_set 3 +.Sh HISTORY +.Fn event_dispatch +first appeared in libevent-0.1 and has been available since +.Ox 3.2 . +.Pp +.Fn event_loop +first appeared in libevent-0.4 and has been available since +.Ox 3.2 . +.Pp +.Fn event_base_dispatch +and +.Fn event_base_loop +first appeared in libevent-1.0 and has been available since +.Ox 3.8 . +.Sh AUTHORS +The event library and these functions were written by +.An -nosplit +.An Niels Provos . +.Pp +This manual page was written by +.An Ted Bullock Aq Mt tbullock@comlore.com . -- 2.20.1