third_party/libevent/event.3

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