From eaaa50c6f4dd22f34bf7911fad01c8b5b5ad1a90 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 10 Apr 2023 13:40:16 +0000 Subject: [PATCH] Various wording tweaks for clarity and precision, and a few for conciseness. OK jmc@ and Ted Bullock --- lib/libevent/event_base_loop.3 | 38 +++++++++++++++------------------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/lib/libevent/event_base_loop.3 b/lib/libevent/event_base_loop.3 index 8bc57545f81..dbf2ff42cd3 100644 --- a/lib/libevent/event_base_loop.3 +++ b/lib/libevent/event_base_loop.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: event_base_loop.3,v 1.2 2023/04/09 14:43:51 schwarze Exp $ +.\" $OpenBSD: event_base_loop.3,v 1.3 2023/04/10 13:40:16 schwarze Exp $ .\" Copyright (c) 2023 Ted Bullock .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,7 +13,7 @@ .\" 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 9 2023 $ +.Dd $Mdocdate: April 10 2023 $ .Dt EVENT_BASE_LOOP 3 .Os .Sh NAME @@ -33,22 +33,21 @@ .Ft int .Fn event_dispatch void .Sh DESCRIPTION -An event loop waits for and dispatches events in a program. +An event loop waits for events +and invokes an associated callback function whenever one occurs. 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 run an event loop. 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. +There are three types of events these functions monitor: +signal, kernel, and timer events. Events involving POSIX signals are configured with .Xr signal_set 3 . Kernel events such as network activity and changes to file descriptors are @@ -57,7 +56,7 @@ configured with Timer events are configured with .Xr evtimer_set 3 . .Pp -The event library further categorizes event states as: +The event library categorizes event states as: .Bl -tag -width "Initialized:" .It Sy Initialized : These have been configured with @@ -71,11 +70,8 @@ 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. +The loop processes events until all activated events are resolved. +Some of these, such as signals, may persist and become scheduled again. .El .Pp The arguments are as follows: @@ -84,12 +80,11 @@ The arguments are as follows: A pointer to an .Vt event_base structure returned from -.Xr event_init 3 +.Xr event_base_new 3 or -.Xr event_base_new 3 . +.Xr event_init 3 . .It Fa flags : -A set of flags that modify the behavior of the event loop. -The following flags are available: +Zero or more of the following flags OR'ed together: .Pp .Bl -hyphen -compact -width 1n .It @@ -136,15 +131,16 @@ is set. .It 0 on success, asked to terminate loop. .It 1 -on success, no remaining events left or scheduled in queue. +on success, no scheduled events remain. .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. +change corresponding to the kernel notification method the +.Fa base +structure is using. These values directly correspond to .Xr kevent 2 , .Xr poll 2 @@ -187,7 +183,7 @@ first appeared in libevent-0.4 and has been available since .Fn event_base_dispatch and .Fn event_base_loop -first appeared in libevent-1.0 and has been available since +first appeared in libevent-1.0 and have been available since .Ox 3.8 . .Sh AUTHORS The event library and these functions were written by -- 2.20.1