| blob | c4707ab5416ea15aa9831d48a4a672d20f0de48c |
1 .\" $NetBSD$
2 .\"
3 .\" $OpenBSD: event.3,v 1.4 2002/07/12 18:50:48 provos Exp $
4 .\"
5 .\" Copyright (c) 2000 Artur Grabowski <art@openbsd.org>
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. The name of the author may not be used to endorse or promote products
18 .\" derived from this software without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
21 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
22 .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
23 .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24 .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
26 .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
27 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
28 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
29 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 .\"
31 .Dd August 8, 2000
32 .Dt EVENT 3
33 .Os
34 .Sh NAME
35 .Nm event_init ,
36 .Nm event_dispatch ,
37 .Nm event_loop ,
38 .Nm event_loopexit ,
39 .Nm event_loopbreak ,
40 .Nm event_set ,
41 .Nm event_base_dispatch ,
42 .Nm event_base_loop ,
43 .Nm event_base_loopexit ,
44 .Nm event_base_loopbreak ,
45 .Nm event_base_set ,
46 .Nm event_base_free ,
47 .Nm event_add ,
48 .Nm event_del ,
49 .Nm event_once ,
50 .Nm event_base_once ,
51 .Nm event_pending ,
52 .Nm event_initialized ,
53 .Nm event_priority_init ,
54 .Nm event_priority_set ,
55 .Nm evtimer_set ,
56 .Nm evtimer_add ,
57 .Nm evtimer_del ,
58 .Nm evtimer_pending ,
59 .Nm evtimer_initialized ,
60 .Nm signal_set ,
61 .Nm signal_add ,
62 .Nm signal_del ,
63 .Nm signal_pending ,
64 .Nm signal_initialized ,
65 .Nm bufferevent_new ,
66 .Nm bufferevent_free ,
67 .Nm bufferevent_write ,
68 .Nm bufferevent_write_buffer ,
69 .Nm bufferevent_read ,
70 .Nm bufferevent_enable ,
71 .Nm bufferevent_disable ,
72 .Nm bufferevent_settimeout ,
73 .Nm bufferevent_base_set ,
74 .Nm evbuffer_new ,
75 .Nm evbuffer_free ,
76 .Nm evbuffer_add ,
77 .Nm evbuffer_add_buffer ,
78 .Nm evbuffer_add_printf ,
79 .Nm evbuffer_add_vprintf ,
80 .Nm evbuffer_drain ,
81 .Nm evbuffer_write ,
82 .Nm evbuffer_read ,
83 .Nm evbuffer_find ,
84 .Nm evbuffer_readline ,
85 .Nm evhttp_new ,
86 .Nm evhttp_bind_socket ,
87 .Nm evhttp_free
88 .Nd execute a function when a specific event occurs
89 .Sh SYNOPSIS
90 .Fd #include <sys/time.h>
91 .Fd #include <event.h>
92 .Ft "struct event_base *"
93 .Fn "event_init" "void"
94 .Ft int
95 .Fn "event_dispatch" "void"
96 .Ft int
97 .Fn "event_loop" "int flags"
98 .Ft int
99 .Fn "event_loopexit" "struct timeval *tv"
100 .Ft int
101 .Fn "event_loopbreak" "void"
102 .Ft void
103 .Fn "event_set" "struct event *ev" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg"
104 .Ft int
105 .Fn "event_base_dispatch" "struct event_base *base"
106 .Ft int
107 .Fn "event_base_loop" "struct event_base *base" "int flags"
108 .Ft int
109 .Fn "event_base_loopexit" "struct event_base *base" "struct timeval *tv"
110 .Ft int
111 .Fn "event_base_loopbreak" "struct event_base *base"
112 .Ft int
113 .Fn "event_base_set" "struct event_base *base" "struct event *"
114 .Ft void
115 .Fn "event_base_free" "struct event_base *base"
116 .Ft int
117 .Fn "event_add" "struct event *ev" "struct timeval *tv"
118 .Ft int
119 .Fn "event_del" "struct event *ev"
120 .Ft int
121 .Fn "event_once" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv"
122 .Ft int
123 .Fn "event_base_once" "struct event_base *base" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv"
124 .Ft int
125 .Fn "event_pending" "struct event *ev" "short event" "struct timeval *tv"
126 .Ft int
127 .Fn "event_initialized" "struct event *ev"
128 .Ft int
129 .Fn "event_priority_init" "int npriorities"
130 .Ft int
131 .Fn "event_priority_set" "struct event *ev" "int priority"
132 .Ft void
133 .Fn "evtimer_set" "struct event *ev" "void (*fn)(int, short, void *)" "void *arg"
134 .Ft void
135 .Fn "evtimer_add" "struct event *ev" "struct timeval *"
136 .Ft void
137 .Fn "evtimer_del" "struct event *ev"
138 .Ft int
139 .Fn "evtimer_pending" "struct event *ev" "struct timeval *tv"
140 .Ft int
141 .Fn "evtimer_initialized" "struct event *ev"
142 .Ft void
143 .Fn "signal_set" "struct event *ev" "int signal" "void (*fn)(int, short, void *)" "void *arg"
144 .Ft void
145 .Fn "signal_add" "struct event *ev" "struct timeval *"
146 .Ft void
147 .Fn "signal_del" "struct event *ev"
148 .Ft int
149 .Fn "signal_pending" "struct event *ev" "struct timeval *tv"
150 .Ft int
151 .Fn "signal_initialized" "struct event *ev"
152 .Ft "struct bufferevent *"
153 .Fn "bufferevent_new" "int fd" "evbuffercb readcb" "evbuffercb writecb" "everrorcb" "void *cbarg"
154 .Ft void
155 .Fn "bufferevent_free" "struct bufferevent *bufev"
156 .Ft int
157 .Fn "bufferevent_write" "struct bufferevent *bufev" "void *data" "size_t size"
158 .Ft int
159 .Fn "bufferevent_write_buffer" "struct bufferevent *bufev" "struct evbuffer *buf"
160 .Ft size_t
161 .Fn "bufferevent_read" "struct bufferevent *bufev" "void *data" "size_t size"
162 .Ft int
163 .Fn "bufferevent_enable" "struct bufferevent *bufev" "short event"
164 .Ft int
165 .Fn "bufferevent_disable" "struct bufferevent *bufev" "short event"
166 .Ft void
167 .Fn "bufferevent_settimeout" "struct bufferevent *bufev" "int timeout_read" "int timeout_write"
168 .Ft int
169 .Fn "bufferevent_base_set" "struct event_base *base" "struct bufferevent *bufev"
170 .Ft "struct evbuffer *"
171 .Fn "evbuffer_new" "void"
172 .Ft void
173 .Fn "evbuffer_free" "struct evbuffer *buf"
174 .Ft int
175 .Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size"
176 .Ft int
177 .Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src"
178 .Ft int
179 .Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..."
180 .Ft int
181 .Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap"
182 .Ft void
183 .Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size"
184 .Ft int
185 .Fn "evbuffer_write" "struct evbuffer *buf" "int fd"
186 .Ft int
187 .Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size"
188 .Ft "u_char *"
189 .Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size"
190 .Ft "char *"
191 .Fn "evbuffer_readline" "struct evbuffer *buf"
192 .Ft "struct evhttp *"
193 .Fn "evhttp_new" "struct event_base *base"
194 .Ft int
195 .Fn "evhttp_bind_socket" "struct evhttp *http" "const char *address" "u_short port"
196 .Ft "void"
197 .Fn "evhttp_free" "struct evhttp *http"
198 .Ft int
199 .Fa (*event_sigcb)(void) ;
200 .Ft volatile sig_atomic_t
201 .Fa event_gotsig ;
202 .Sh DESCRIPTION
203 The
204 .Nm event
205 API provides a mechanism to execute a function when a specific event
206 on a file descriptor occurs or after a given time has passed.
207 .Pp
208 The
209 .Nm event
210 API needs to be initialized with
211 .Fn event_init
212 before it can be used.
213 .Pp
214 In order to process events, an application needs to call
215 .Fn event_dispatch .
216 This function only returns on error, and should replace the event core
217 of the application program.
218 .Pp
219 The function
220 .Fn event_set
221 prepares the event structure
222 .Fa ev
223 to be used in future calls to
224 .Fn event_add
225 and
226 .Fn event_del .
227 The event will be prepared to call the function specified by the
228 .Fa fn
229 argument with an
230 .Fa int
231 argument indicating the file descriptor, a
232 .Fa short
233 argument indicating the type of event, and a
234 .Fa void *
235 argument given in the
236 .Fa arg
237 argument.
238 The
239 .Fa fd
240 indicates the file descriptor that should be monitored for events.
241 The events can be either
242 .Va EV_READ ,
243 .Va EV_WRITE ,
244 or both,
245 indicating that an application can read or write from the file descriptor
246 respectively without blocking.
247 .Pp
248 The function
249 .Fa fn
250 will be called with the file descriptor that triggered the event and
251 the type of event which will be either
252 .Va EV_TIMEOUT ,
253 .Va EV_SIGNAL ,
254 .Va EV_READ ,
255 or
256 .Va EV_WRITE .
257 Additionally, an event which has registered interest in more than one of the
258 preceeding events, via bitwise-OR to
259 .Fn event_set ,
260 can provide its callback function with a bitwise-OR of more than one triggered
261 event.
262 The additional flag
263 .Va EV_PERSIST
264 makes an
265 .Fn event_add
266 persistent until
267 .Fn event_del
268 has been called.
269 .Pp
270 Once initialized, the
271 .Fa ev
272 structure can be used repeatedly with
273 .Fn event_add
274 and
275 .Fn event_del
276 and does not need to be reinitialized unless the function called and/or
277 the argument to it are to be changed.
278 However, when an
279 .Fa ev
280 structure has been added to libevent using
281 .Fn event_add
282 the structure must persist until the event occurs (assuming
283 .Fa EV_PERSIST
284 is not set) or is removed
285 using
286 .Fn event_del .
287 You may not reuse the same
288 .Fa ev
289 structure for multiple monitored descriptors; each descriptor
290 needs its own
291 .Fa ev .
292 .Pp
293 The function
294 .Fn event_add
295 schedules the execution of the
296 .Fa ev
297 event when the event specified in
298 .Fn event_set
299 occurs or in at least the time specified in the
300 .Fa tv .
301 If
302 .Fa tv
303 is
304 .Dv NULL ,
305 no timeout occurs and the function will only be called
306 if a matching event occurs on the file descriptor.
307 The event in the
308 .Fa ev
309 argument must be already initialized by
310 .Fn event_set
311 and may not be used in calls to
312 .Fn event_set
313 until it has timed out or been removed with
314 .Fn event_del .
315 If the event in the
316 .Fa ev
317 argument already has a scheduled timeout, the old timeout will be
318 replaced by the new one.
319 .Pp
320 The function
321 .Fn event_del
322 will cancel the event in the argument
323 .Fa ev .
324 If the event has already executed or has never been added
325 the call will have no effect.
326 .Pp
327 The functions
328 .Fn evtimer_set ,
329 .Fn evtimer_add ,
330 .Fn evtimer_del ,
331 .Fn evtimer_initialized ,
332 and
333 .Fn evtimer_pending
334 are abbreviations for common situations where only a timeout is required.
335 The file descriptor passed will be \-1, and the event type will be
336 .Va EV_TIMEOUT .
337 .Pp
338 The functions
339 .Fn signal_set ,
340 .Fn signal_add ,
341 .Fn signal_del ,
342 .Fn signal_initialized ,
343 and
344 .Fn signal_pending
345 are abbreviations.
346 The event type will be a persistent
347 .Va EV_SIGNAL .
348 That means
349 .Fn signal_set
350 adds
351 .Va EV_PERSIST .
352 .Pp
353 In order to avoid races in signal handlers, the
354 .Nm event
355 API provides two variables:
356 .Va event_sigcb
357 and
358 .Va event_gotsig .
359 A signal handler
360 sets
361 .Va event_gotsig
362 to indicate that a signal has been received.
363 The application sets
364 .Va event_sigcb
365 to a callback function.
366 After the signal handler sets
367 .Va event_gotsig ,
368 .Nm event_dispatch
369 will execute the callback function to process received signals.
370 The callback returns 1 when no events are registered any more.
371 It can return \-1 to indicate an error to the
372 .Nm event
373 library, causing
374 .Fn event_dispatch
375 to terminate with
376 .Va errno
377 set to
378 .Er EINTR .
379 .Pp
380 The function
381 .Fn event_once
382 is similar to
383 .Fn event_set .
384 However, it schedules a callback to be called exactly once and does not
385 require the caller to prepare an
386 .Fa event
387 structure.
388 This function supports
389 .Fa EV_TIMEOUT ,
390 .Fa EV_READ ,
391 and
392 .Fa EV_WRITE .
393 .Pp
394 The
395 .Fn event_pending
396 function can be used to check if the event specified by
397 .Fa event
398 is pending to run.
399 If
400 .Va EV_TIMEOUT
401 was specified and
402 .Fa tv
403 is not
404 .Dv NULL ,
405 the expiration time of the event will be returned in
406 .Fa tv .
407 .Pp
408 The
409 .Fn event_initialized
410 macro can be used to check if an event has been initialized.
411 .Pp
412 The
413 .Nm event_loop
414 function provides an interface for single pass execution of pending
415 events.
416 The flags
417 .Va EVLOOP_ONCE
418 and
419 .Va EVLOOP_NONBLOCK
420 are recognized.
421 The
422 .Nm event_loopexit
423 function exits from the event loop. The next
424 .Fn event_loop
425 iteration after the
426 given timer expires will complete normally (handling all queued events) then
427 exit without blocking for events again. Subsequent invocations of
428 .Fn event_loop
429 will proceed normally.
430 The
431 .Nm event_loopbreak
432 function exits from the event loop immediately.
433 .Fn event_loop
434 will abort after the next event is completed;
435 .Fn event_loopbreak
436 is typically invoked from this event's callback. This behavior is analogous
437 to the "break;" statement. Subsequent invocations of
438 .Fn event_loop
439 will proceed normally.
440 .Pp
441 It is the responsibility of the caller to provide these functions with
442 pre-allocated event structures.
443 .Pp
444 .Sh EVENT PRIORITIES
445 By default
446 .Nm libevent
447 schedules all active events with the same priority.
448 However, sometimes it is desirable to process some events with a higher
449 priority than others.
450 For that reason,
451 .Nm libevent
452 supports strict priority queues.
453 Active events with a lower priority are always processed before events
454 with a higher priority.
455 .Pp
456 The number of different priorities can be set initially with the
457 .Fn event_priority_init
458 function.
459 This function should be called before the first call to
460 .Fn event_dispatch .
461 The
462 .Fn event_priority_set
463 function can be used to assign a priority to an event.
464 By default,
465 .Nm libevent
466 assigns the middle priority to all events unless their priority
467 is explicitly set.
468 .Sh THREAD SAFE EVENTS
469 .Nm Libevent
470 has experimental support for thread-safe events.
471 When initializing the library via
472 .Fn event_init ,
473 an event base is returned.
474 This event base can be used in conjunction with calls to
475 .Fn event_base_set ,
476 .Fn event_base_dispatch ,
477 .Fn event_base_loop ,
478 .Fn event_base_loopexit ,
479 .Fn bufferevent_base_set
480 and
481 .Fn event_base_free .
482 .Fn event_base_set
483 should be called after preparing an event with
484 .Fn event_set ,
485 as
486 .Fn event_set
487 assigns the provided event to the most recently created event base.
488 .Fn bufferevent_base_set
489 should be called after preparing a bufferevent with
490 .Fn bufferevent_new .
491 .Fn event_base_free
492 should be used to free memory associated with the event base
493 when it is no longer needed.
494 .Sh BUFFERED EVENTS
495 .Nm libevent
496 provides an abstraction on top of the regular event callbacks.
497 This abstraction is called a
498 .Va "buffered event" .
499 A buffered event provides input and output buffers that get filled
500 and drained automatically.
501 The user of a buffered event no longer deals directly with the IO,
502 but instead is reading from input and writing to output buffers.
503 .Pp
504 A new bufferevent is created by
505 .Fn bufferevent_new .
506 The parameter
507 .Fa fd
508 specifies the file descriptor from which data is read and written to.
509 This file descriptor is not allowed to be a
510 .Xr pipe 2 .
511 The next three parameters are callbacks.
512 The read and write callback have the following form:
513 .Ft void
514 .Fn "(*cb)" "struct bufferevent *bufev" "void *arg" .
515 The error callback has the following form:
516 .Ft void
517 .Fn "(*cb)" "struct bufferevent *bufev" "short what" "void *arg" .
518 The argument is specified by the fourth parameter
519 .Fa "cbarg" .
520 A
521 .Fa bufferevent struct
522 pointer is returned on success, NULL on error.
523 Both the read and the write callback may be NULL.
524 The error callback has to be always provided.
525 .Pp
526 Once initialized, the bufferevent structure can be used repeatedly with
527 bufferevent_enable() and bufferevent_disable().
528 The flags parameter can be a combination of
529 .Va EV_READ
530 and
531 .Va EV_WRITE .
532 When read enabled the bufferevent will try to read from the file
533 descriptor and call the read callback.
534 The write callback is executed
535 whenever the output buffer is drained below the write low watermark,
536 which is
537 .Va 0
538 by default.
539 .Pp
540 The
541 .Fn bufferevent_write
542 function can be used to write data to the file descriptor.
543 The data is appended to the output buffer and written to the descriptor
544 automatically as it becomes available for writing.
545 .Fn bufferevent_write
546 returns 0 on success or \-1 on failure.
547 The
548 .Fn bufferevent_read
549 function is used to read data from the input buffer,
550 returning the amount of data read.
551 .Pp
552 If multiple bases are in use, bufferevent_base_set() must be called before
553 enabling the bufferevent for the first time.
554 .Sh NON-BLOCKING HTTP SUPPORT
555 .Nm libevent
556 provides a very thin HTTP layer that can be used both to host an HTTP
557 server and also to make HTTP requests.
558 An HTTP server can be created by calling
559 .Fn evhttp_new .
560 It can be bound to any port and address with the
561 .Fn evhttp_bind_socket
562 function.
563 When the HTTP server is no longer used, it can be freed via
564 .Fn evhttp_free .
565 .Pp
566 To be notified of HTTP requests, a user needs to register callbacks with the
567 HTTP server.
568 This can be done by calling
569 .Fn evhttp_set_cb .
570 The second argument is the URI for which a callback is being registered.
571 The corresponding callback will receive an
572 .Va struct evhttp_request
573 object that contains all information about the request.
574 .Pp
575 This section does not document all the possible function calls; please
576 check
577 .Va event.h
578 for the public interfaces.
579 .Sh ADDITIONAL NOTES
580 It is possible to disable support for
581 .Va epoll , kqueue , devpoll , poll
582 or
583 .Va select
584 by setting the environment variable
585 .Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL , EVENT_NOPOLL
586 or
587 .Va EVENT_NOSELECT ,
588 respectively.
589 By setting the environment variable
590 .Va EVENT_SHOW_METHOD ,
591 .Nm libevent
592 displays the kernel notification method that it uses.
593 .Sh RETURN VALUES
594 Upon successful completion
595 .Fn event_add
596 and
597 .Fn event_del
598 return 0.
599 Otherwise, \-1 is returned and the global variable errno is
600 set to indicate the error.
601 .Sh SEE ALSO
602 .Xr kqueue 2 ,
603 .Xr poll 2 ,
604 .Xr select 2 ,
605 .Xr evdns 3 ,
606 .Xr timeout 9
607 .Sh HISTORY
608 The
609 .Nm event
610 API manpage is based on the
611 .Xr timeout 9
612 manpage by Artur Grabowski.
613 The port of
614 .Nm libevent
615 to Windows is due to Michael A. Davis.
616 Support for real-time signals is due to Taral.
617 .Sh AUTHORS
618 The
619 .Nm event
620 library was written by Niels Provos.
621 .Sh BUGS
622 This documentation is neither complete nor authoritative.
623 If you are in doubt about the usage of this API then
624 check the source code to find out how it works, write
625 up the missing piece of documentation and send it to
626 me for inclusion in this man page.