--- /dev/null
+.\" $OpenBSD: event_base_loop.3,v 1.1 2023/04/08 16:21:22 schwarze Exp $
+.\" Copyright (c) 2023 Ted Bullock <tbullock@comlore.com>
+.\"
+.\" 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 .
projects / openbsd / commitdiff