1.\" $OpenBSD: event_base_loop.3,v 1.5 2023/04/27 16:10:11 schwarze Exp $ 2.\" Copyright (c) 2023 Ted Bullock <tbullock@comlore.com> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.Dd $Mdocdate: April 27 2023 $ 17.Dt EVENT_BASE_LOOP 3 18.Os 19.Sh NAME 20.Nm event_base_loop , 21.Nm event_loop , 22.Nm event_base_dispatch , 23.Nm event_dispatch 24.Nd run an event loop 25.Sh SYNOPSIS 26.In event.h 27.Ft int 28.Fn event_base_loop "struct event_base *base" "int flags" 29.Ft int 30.Fn event_loop "int flags" 31.Ft int 32.Fn event_base_dispatch "struct event_base *base" 33.Ft int 34.Fn event_dispatch void 35.Sh DESCRIPTION 36An event loop waits for events 37and invokes an associated callback function whenever one occurs. 38This enables asynchronous programming, allowing a program to perform other 39tasks while waiting for an event to occur. 40Asynchronous programming is a useful idiom for handling multiple I/O 41operations, such as network connections, user interfaces, or disk operations 42without blocking the main loop of a program. 43.Pp 44The 45.Fn event_base_loop 46family of functions run an event loop. 47By default, they return when there are no more scheduled events. 48.Pp 49There are three types of events these functions monitor: 50signal, kernel, and timer events. 51Events involving POSIX signals are configured with 52.Xr signal_set 3 . 53Kernel events such as network activity and changes to file descriptors are 54configured with 55.Xr event_set 3 . 56Timer events are configured with 57.Xr evtimer_set 3 . 58.Pp 59The event library categorizes event states as: 60.Bl -tag -width initialized 61.It Em initialized 62These have been configured with 63.Xr event_set 3 64and not yet registered with an event loop. 65.It Em scheduled 66These are registered to a loop using 67.Xr event_add 3 68and are idle, waiting to trigger and be processed by the loop. 69They can be queried with 70.Fn event_pending 3 . 71.It Em activated 72These are triggered events. 73The loop processes events until all activated events are resolved. 74Some of these, such as signals, may persist and become scheduled again. 75.El 76.Pp 77The arguments are as follows: 78.Bl -tag -width flags 79.It Fa base 80A pointer to an 81.Vt event_base 82structure returned from 83.Xr event_base_new 3 84or 85.Xr event_init 3 . 86.It Fa flags 87Zero or more of the following flags OR'ed together: 88.Bl -tag -width EVLOOP_NONBLOCK 89.It Dv EVLOOP_ONCE 90Run the event loop for one iteration and then return. 91This is useful for a main program that needs to perform actions outside 92the event loop. 93.It Dv EVLOOP_NONBLOCK 94Run the event loop in non-blocking mode. 95The loop returns after processing activated signal and kernel events and does 96not wait for timer events to expire. 97.El 98.El 99.Pp 100The function 101.Fn event_loop 102is a version of 103.Fn event_base_loop 104that requires the library to be initialized by 105.Xr event_init 3 . 106.Pp 107.Fn event_base_dispatch 108is equivalent to calling 109.Fn event_base_loop 110with 111.Fa flags 112set to zero. 113Likewise, 114.Fn event_dispatch 115is the same as invoking 116.Fn event_loop 117with 118.Fa flags 119set to zero. 120.Sh RETURN VALUES 121The event loop functions return: 122.Pp 123.Bl -tag -compact -offset 3n -width 3n 124.It \-1 125on error, 126.Va errno 127is set. 128.It 0 129on success, asked to terminate loop. 130.It 1 131on success, no scheduled events remain. 132.El 133.Sh ERRORS 134These functions have complex interactions with 135.Va errno . 136Error conditions that set 137.Va errno 138change corresponding to the kernel notification method the 139.Fa base 140structure is using. 141These values directly correspond to 142.Xr kevent 2 , 143.Xr poll 2 144or 145.Xr select 2 146system calls and default to 147.Xr kevent 2 148on 149.Ox . 150Refer to 151.Xr event_base_new 3 152for details on kernel notification methods. 153.Bl -tag -width Er 154.It Bq Er EINTR 155Although the kernel notification methods can set 156.Va errno 157to 158.Er EINTR , 159.Fn event_base_loop 160and related functions never fail with 161.Va errno 162set to 163.Er EINTR . 164.El 165.Sh SEE ALSO 166.Xr kevent 2 , 167.Xr poll 2 , 168.Xr select 2 , 169.Xr event_base_new 3 , 170.Xr event_set 3 171.Sh HISTORY 172.Fn event_dispatch 173first appeared in libevent-0.1 and has been available since 174.Ox 3.2 . 175.Pp 176.Fn event_loop 177first appeared in libevent-0.4 and has been available since 178.Ox 3.2 . 179.Pp 180.Fn event_base_dispatch 181and 182.Fn event_base_loop 183first appeared in libevent-1.0 and have been available since 184.Ox 3.8 . 185.Sh AUTHORS 186The event library and these functions were written by 187.An -nosplit 188.An Niels Provos . 189.Pp 190This manual page was written by 191.An Ted Bullock Aq Mt tbullock@comlore.com . 192