jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: event_base_loop.3,v 1.6 2025/06/07 20:50:40 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: June 7 2025 $
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.Lb libevent
27.In event.h
28.Ft int
29.Fn event_base_loop "struct event_base *base" "int flags"
30.Ft int
31.Fn event_loop "int flags"
32.Ft int
33.Fn event_base_dispatch "struct event_base *base"
34.Ft int
35.Fn event_dispatch void
36.Sh DESCRIPTION
37An event loop waits for events
38and invokes an associated callback function whenever one occurs.
39This enables asynchronous programming, allowing a program to perform other
40tasks while waiting for an event to occur.
41Asynchronous programming is a useful idiom for handling multiple I/O
42operations, such as network connections, user interfaces, or disk operations
43without blocking the main loop of a program.
44.Pp
45The
46.Fn event_base_loop
47family of functions run an event loop.
48By default, they return when there are no more scheduled events.
49.Pp
50There are three types of events these functions monitor:
51signal, kernel, and timer events.
52Events involving POSIX signals are configured with
53.Xr signal_set 3 .
54Kernel events such as network activity and changes to file descriptors are
55configured with
56.Xr event_set 3 .
57Timer events are configured with
58.Xr evtimer_set 3 .
59.Pp
60The event library categorizes event states as:
61.Bl -tag -width initialized
62.It Em initialized
63These have been configured with
64.Xr event_set 3
65and not yet registered with an event loop.
66.It Em scheduled
67These are registered to a loop using
68.Xr event_add 3
69and are idle, waiting to trigger and be processed by the loop.
70They can be queried with
71.Fn event_pending 3 .
72.It Em activated
73These are triggered events.
74The loop processes events until all activated events are resolved.
75Some of these, such as signals, may persist and become scheduled again.
76.El
77.Pp
78The arguments are as follows:
79.Bl -tag -width flags
80.It Fa base
81A pointer to an
82.Vt event_base
83structure returned from
84.Xr event_base_new 3
85or
86.Xr event_init 3 .
87.It Fa flags
88Zero or more of the following flags OR'ed together:
89.Bl -tag -width EVLOOP_NONBLOCK
90.It Dv EVLOOP_ONCE
91Run the event loop for one iteration and then return.
92This is useful for a main program that needs to perform actions outside
93the event loop.
94.It Dv EVLOOP_NONBLOCK
95Run the event loop in non-blocking mode.
96The loop returns after processing activated signal and kernel events and does
97not wait for timer events to expire.
98.El
99.El
100.Pp
101The function
102.Fn event_loop
103is a version of
104.Fn event_base_loop
105that requires the library to be initialized by
106.Xr event_init 3 .
107.Pp
108.Fn event_base_dispatch
109is equivalent to calling
110.Fn event_base_loop
111with
112.Fa flags
113set to zero.
114Likewise,
115.Fn event_dispatch
116is the same as invoking
117.Fn event_loop
118with
119.Fa flags
120set to zero.
121.Sh RETURN VALUES
122The event loop functions return:
123.Pp
124.Bl -tag -compact -offset 3n -width 3n
125.It \-1
126on error,
127.Va errno
128is set.
129.It 0
130on success, asked to terminate loop.
131.It 1
132on success, no scheduled events remain.
133.El
134.Sh ERRORS
135These functions have complex interactions with
136.Va errno .
137Error conditions that set
138.Va errno
139change corresponding to the kernel notification method the
140.Fa base
141structure is using.
142These values directly correspond to
143.Xr kevent 2 ,
144.Xr poll 2
145or
146.Xr select 2
147system calls and default to
148.Xr kevent 2
149on
150.Ox .
151Refer to
152.Xr event_base_new 3
153for details on kernel notification methods.
154.Bl -tag -width Er
155.It Bq Er EINTR
156Although the kernel notification methods can set
157.Va errno
158to
159.Er EINTR ,
160.Fn event_base_loop
161and related functions never fail with
162.Va errno
163set to
164.Er EINTR .
165.El
166.Sh SEE ALSO
167.Xr kevent 2 ,
168.Xr poll 2 ,
169.Xr select 2 ,
170.Xr event_base_new 3 ,
171.Xr event_set 3
172.Sh HISTORY
173.Fn event_dispatch
174first appeared in libevent-0.1 and has been available since
175.Ox 3.2 .
176.Pp
177.Fn event_loop
178first appeared in libevent-0.4 and has been available since
179.Ox 3.2 .
180.Pp
181.Fn event_base_dispatch
182and
183.Fn event_base_loop
184first appeared in libevent-1.0 and have been available since
185.Ox 3.8 .
186.Sh AUTHORS
187The event library and these functions were written by
188.An -nosplit
189.An Niels Provos .
190.Pp
191This manual page was written by
192.An Ted Bullock Aq Mt tbullock@comlore.com .