root/opal/mca/event/libevent2022/libevent/include/event2/event.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   1 /*
   2  * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
   3  * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  * 3. The name of the author may not be used to endorse or promote products
  14  *    derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27 #ifndef _EVENT2_EVENT_H_
  28 #define _EVENT2_EVENT_H_
  29 
  30 /**
  31    @mainpage
  32 
  33   @section intro Introduction
  34 
  35   Libevent is an event notification library for developing scalable network
  36   servers.  The Libevent API provides a mechanism to execute a callback
  37   function when a specific event occurs on a file descriptor or after a
  38   timeout has been reached. Furthermore, Libevent also support callbacks due
  39   to signals or regular timeouts.
  40 
  41   Libevent is meant to replace the event loop found in event driven network
  42   servers. An application just needs to call event_dispatch() and then add or
  43   remove events dynamically without having to change the event loop.
  44 
  45 
  46   Currently, Libevent supports /dev/poll, kqueue(2), select(2), poll(2),
  47   epoll(4), and evports. The internal event mechanism is completely
  48   independent of the exposed event API, and a simple update of Libevent can
  49   provide new functionality without having to redesign the applications. As a
  50   result, Libevent allows for portable application development and provides
  51   the most scalable event notification mechanism available on an operating
  52   system.  Libevent can also be used for multithreaded programs.  Libevent
  53   should compile on Linux, *BSD, Mac OS X, Solaris and, Windows.
  54 
  55   @section usage Standard usage
  56 
  57   Every program that uses Libevent must inclurde the <event2/event.h>
  58   header, and pass the -levent flag to the linker.  (You can instead link
  59   -levent_core if you only want the main event and buffered IO-based code,
  60   and don't want to link any protocol code.)
  61 
  62   @section setup Library setup
  63 
  64   Before you call any other Libevent functions, you need to set up the
  65   library.  If you're going to use Libevent from multiple threads in a
  66   multithreaded application, you need to initialize thread support --
  67   typically by using evthread_use_pthreads() or
  68   evthread_use_windows_threads().  See <event2/thread.h> for more
  69   information.
  70 
  71   This is also the point where you can replace Libevent's memory
  72   management functions with event_set_mem_functions, and enable debug mode
  73   with event_enable_debug_mode().
  74 
  75   @section base Creating an event base
  76 
  77   Next, you need to create an event_base structure, using event_base_new()
  78   or event_base_new_with_config().  The event_base is responsible for
  79   keeping track of which events are "pending" (that is to say, being
  80   watched to see if they become active) and which events are "active".
  81   Every event is associated with a single event_base.
  82 
  83   @section event Event notification
  84 
  85   For each file descriptor that you wish to monitor, you must create an
  86   event structure with event_new().  (You may also declare an event
  87   structure and call event_assign() to initialize the members of the
  88   structure.)  To enable notification, you add the structure to the list
  89   of monitored events by calling event_add().  The event structure must
  90   remain allocated as long as it is active, so it should generally be
  91   allocated on the heap.
  92 
  93   @section loop Dispaching evets.
  94 
  95   Finally, you call event_base_dispatch() to loop and dispatch events.
  96   You can also use event_base_loop() for more fine-grained control.
  97 
  98   Currently, only one thread can be dispatching a given event_base at a
  99   time.  If you want to run events in multiple threads at once, you can
 100   either have a single event_base whose events add work to a work queue,
 101   or you can create multiple event_base objects.
 102 
 103   @section bufferevent I/O Buffers
 104 
 105   Libevent provides a buffered I/O abstraction on top of the regular event
 106   callbacks. This abstraction is called a bufferevent. A bufferevent
 107   provides input and output buffers that get filled and drained
 108   automatically. The user of a buffered event no longer deals directly
 109   with the I/O, but instead is reading from input and writing to output
 110   buffers.
 111 
 112   Once initialized via bufferevent_socket_new(), the bufferevent structure
 113   can be used repeatedly with bufferevent_enable() and
 114   bufferevent_disable().  Instead of reading and writing directly to a
 115   socket, you would call bufferevent_read() and bufferevent_write().
 116 
 117   When read enabled the bufferevent will try to read from the file descriptor
 118   and call the read callback. The write callback is executed whenever the
 119   output buffer is drained below the write low watermark, which is 0 by
 120   default.
 121 
 122   See <event2/bufferevent*.h> for more information.
 123 
 124   @section timers Timers
 125 
 126   Libevent can also be used to create timers that invoke a callback after a
 127   certain amount of time has expired. The evtimer_new() function returns
 128   an event struct to use as a timer. To activate the timer, call
 129   evtimer_add(). Timers can be deactivated by calling evtimer_del().
 130 
 131   @section evdns Asynchronous DNS resolution
 132 
 133   Libevent provides an asynchronous DNS resolver that should be used instead
 134   of the standard DNS resolver functions.  See the <event2/dns.h>
 135   functions for more detail.
 136 
 137   @section evhttp Event-driven HTTP servers
 138 
 139   Libevent provides a very simple event-driven HTTP server that can be
 140   embedded in your program and used to service HTTP requests.
 141 
 142   To use this capability, you need to include the <event2/http.h> header in your
 143   program.  See that header for more information.
 144 
 145   @section evrpc A framework for RPC servers and clients
 146 
 147   Libevent provides a framework for creating RPC servers and clients.  It
 148   takes care of marshaling and unmarshaling all data structures.
 149 
 150   @section api API Reference
 151 
 152   To browse the complete documentation of the libevent API, click on any of
 153   the following links.
 154 
 155   event2/event.h
 156   The primary libevent header
 157 
 158   event2/thread.h
 159   Functions for use by multithreaded programs
 160 
 161   event2/buffer.h and event2/bufferevent.h
 162   Buffer management for network reading and writing
 163 
 164   event2/util.h
 165   Utility functions for portable nonblocking network code
 166 
 167   event2/dns.h
 168   Asynchronous DNS resolution
 169 
 170   event2/http.h
 171   An embedded libevent-based HTTP server
 172 
 173   event2/rpc.h
 174   A framework for creating RPC servers and clients
 175 
 176  */
 177 
 178 /** @file event2/event.h
 179 
 180   Core functions for waiting for and receiving events, and using event bases.
 181 */
 182 
 183 #ifdef __cplusplus
 184 extern "C" {
 185 #endif
 186 
 187 /****    OMPI CHANGE    ****/
 188 #include "opal_rename.h"
 189 /****  END OMPI CHANGE  ****/
 190 
 191 #include <event2/event-config.h>
 192 #ifdef _EVENT_HAVE_SYS_TYPES_H
 193 #include <sys/types.h>
 194 #endif
 195 #ifdef _EVENT_HAVE_SYS_TIME_H
 196 #include <sys/time.h>
 197 #endif
 198 
 199 #include <stdio.h>
 200 
 201 /* For int types. */
 202 #include <event2/util.h>
 203 
 204 /**
 205  * Structure to hold information and state for a Libevent dispatch loop.
 206  *
 207  * The event_base lies at the center of Libevent; every application will
 208  * have one.  It keeps track of all pending and active events, and
 209  * notifies your application of the active ones.
 210  *
 211  * This is an opaque structure; you can allocate one using
 212  * event_base_new() or event_base_new_with_config().
 213  *
 214  * @see event_base_new(), event_base_free(), event_base_loop(),
 215  *    event_base_new_with_config()
 216  */
 217 struct event_base
 218 #ifdef _EVENT_IN_DOXYGEN
 219 {/*Empty body so that doxygen will generate documentation here.*/}
 220 #endif
 221 ;
 222 
 223 /**
 224  * @struct event
 225  *
 226  * Structure to represent a single event.
 227  *
 228  * An event can have some underlying condition it represents: a socket
 229  * becoming readable or writeable (or both), or a signal becoming raised.
 230  * (An event that represents no underlying condition is still useful: you
 231  * can use one to implement a timer, or to communicate between threads.)
 232  *
 233  * Generally, you can create events with event_new(), then make them
 234  * pending with event_add().  As your event_base runs, it will run the
 235  * callbacks of an events whose conditions are triggered.  When you
 236  * longer want the event, free it with event_free().
 237  *
 238  * In more depth:
 239  *
 240  * An event may be "pending" (one whose condition we are watching),
 241  * "active" (one whose condition has triggered and whose callback is about
 242  * to run), neither, or both.  Events come into existence via
 243  * event_assign() or event_new(), and are then neither active nor pending.
 244  *
 245  * To make an event pending, pass it to event_add().  When doing so, you
 246  * can also set a timeout for the event.
 247  *
 248  * Events become active during an event_base_loop() call when either their
 249  * condition has triggered, or when their timeout has elapsed.  You can
 250  * also activate an event manually using event_active().  The even_base
 251  * loop will run the callbacks of active events; after it has done so, it
 252  * marks them as no longer active.
 253  *
 254  * You can make an event non-pending by passing it to event_del().  This
 255  * also makes the event non-active.
 256  *
 257  * Events can be "persistent" or "non-persistent".  A non-persistent event
 258  * becomes non-pending as soon as it is triggered: thus, it only runs at
 259  * most once per call to event_add().  A persistent event remains pending
 260  * even when it becomes active: you'll need to event_del() it manually in
 261  * order to make it non-pending.  When a persistent event with a timeout
 262  * becomes active, its timeout is reset: this means you can use persistent
 263  * events to implement periodic timeouts.
 264  *
 265  * This should be treated as an opaque structure; you should never read or
 266  * write any of its fields directly.  For backward compatibility with old
 267  * code, it is defined in the event2/event_struct.h header; including this
 268  * header may make your code incompatible with other versions of Libevent.
 269  *
 270  * @see event_new(), event_free(), event_assign(), event_get_assignment(),
 271  *    event_add(), event_del(), event_active(), event_pending(),
 272  *    event_get_fd(), event_get_base(), event_get_events(),
 273  *    event_get_callback(), event_get_callback_arg(),
 274  *    event_priority_set()
 275  */
 276 struct event
 277 #ifdef _EVENT_IN_DOXYGEN
 278 {/*Empty body so that doxygen will generate documentation here.*/}
 279 #endif
 280 ;
 281 
 282 /**
 283  * Configuration for an event_base.
 284  *
 285  * There are many options that can be used to alter the behavior and
 286  * implementation of an event_base.  To avoid having to pass them all in a
 287  * complex many-argument constructor, we provide an abstract data type
 288  * wrhere you set up configation information before passing it to
 289  * event_base_new_with_config().
 290  *
 291  * @see event_config_new(), event_config_free(), event_base_new_with_config(),
 292  *   event_config_avoid_method(), event_config_require_features(),
 293  *   event_config_set_flag(), event_config_set_num_cpus_hint()
 294  */
 295 struct event_config
 296 #ifdef _EVENT_IN_DOXYGEN
 297 {/*Empty body so that doxygen will generate documentation here.*/}
 298 #endif
 299 ;
 300 
 301 /**
 302  * Enable some relatively expensive debugging checks in Libevent that
 303  * would normally be turned off.  Generally, these checks cause code that
 304  * would otherwise crash mysteriously to fail earlier with an assertion
 305  * failure.  Note that this method MUST be called before any events or
 306  * event_bases have been created.
 307  *
 308  * Debug mode can currently catch the following errors:
 309  *    An event is re-assigned while it is added
 310  *    Any function is called on a non-assigned event
 311  *
 312  * Note that debugging mode uses memory to track every event that has been
 313  * initialized (via event_assign, event_set, or event_new) but not yet
 314  * released (via event_free or event_debug_unassign).  If you want to use
 315  * debug mode, and you find yourself running out of memory, you will need
 316  * to use event_debug_unassign to explicitly stop tracking events that
 317  * are no longer considered set-up.
 318  *
 319  * @see event_debug_unassign()
 320  */
 321 void event_enable_debug_mode(void);
 322 
 323 /****    OMPI CHANGE    ****/
 324 void event_set_debug_output(int output);
 325 /****  END OMPI CHANGE  ****/
 326 
 327 /**
 328  * When debugging mode is enabled, informs Libevent that an event should no
 329  * longer be considered as assigned. When debugging mode is not enabled, does
 330  * nothing.
 331  *
 332  * This function must only be called on a non-added event.
 333  *
 334  * @see event_enable_debug_mode()
 335  */
 336 void event_debug_unassign(struct event *);
 337 
 338 /**
 339  * Create and return a new event_base to use with the rest of Libevent.
 340  *
 341  * @return a new event_base on success, or NULL on failure.
 342  *
 343  * @see event_base_free(), event_base_new_with_config()
 344  */
 345 struct event_base *event_base_new(void);
 346 
 347 /**
 348   Reinitialize the event base after a fork
 349 
 350   Some event mechanisms do not survive across fork.   The event base needs
 351   to be reinitialized with the event_reinit() function.
 352 
 353   @param base the event base that needs to be re-initialized
 354   @return 0 if successful, or -1 if some events could not be re-added.
 355   @see event_base_new()
 356 */
 357 int event_reinit(struct event_base *base);
 358 
 359 /**
 360    Event dispatching loop
 361 
 362   This loop will run the event base until either there are no more added
 363   events, or until something calls event_base_loopbreak() or
 364   event_base_loopexit().
 365 
 366   @param base the event_base structure returned by event_base_new() or
 367      event_base_new_with_config()
 368   @return 0 if successful, -1 if an error occurred, or 1 if no events were
 369     registered.
 370   @see event_base_loop()
 371  */
 372 int event_base_dispatch(struct event_base *);
 373 
 374 /**
 375  Get the kernel event notification mechanism used by Libevent.
 376 
 377  @param eb the event_base structure returned by event_base_new()
 378  @return a string identifying the kernel event mechanism (kqueue, epoll, etc.)
 379  */
 380 const char *event_base_get_method(const struct event_base *);
 381 
 382 /**
 383    Gets all event notification mechanisms supported by Libevent.
 384 
 385    This functions returns the event mechanism in order preferred by
 386    Libevent.  Note that this list will include all backends that
 387    Libevent has compiled-in support for, and will not necessarily check
 388    your OS to see whether it has the required resources.
 389 
 390    @return an array with pointers to the names of support methods.
 391      The end of the array is indicated by a NULL pointer.  If an
 392      error is encountered NULL is returned.
 393 */
 394 const char **event_get_supported_methods(void);
 395 
 396 /**
 397    Allocates a new event configuration object.
 398 
 399    The event configuration object can be used to change the behavior of
 400    an event base.
 401 
 402    @return an event_config object that can be used to store configuration, or
 403      NULL if an error is encountered.
 404    @see event_base_new_with_config(), event_config_free(), event_config
 405 */
 406 struct event_config *event_config_new(void);
 407 
 408 /**
 409    Deallocates all memory associated with an event configuration object
 410 
 411    @param cfg the event configuration object to be freed.
 412 */
 413 void event_config_free(struct event_config *cfg);
 414 
 415 /**
 416    Enters an event method that should be avoided into the configuration.
 417 
 418    This can be used to avoid event mechanisms that do not support certain
 419    file descriptor types, or for debugging to avoid certain event
 420    mechanisms.  An application can make use of multiple event bases to
 421    accommodate incompatible file descriptor types.
 422 
 423    @param cfg the event configuration object
 424    @param method the name of the event method to avoid
 425    @return 0 on success, -1 on failure.
 426 */
 427 int event_config_avoid_method(struct event_config *cfg, const char *method);
 428 
 429 /**
 430    A flag used to describe which features an event_base (must) provide.
 431 
 432    Because of OS limitations, not every Libevent backend supports every
 433    possible feature.  You can use this type with
 434    event_config_require_features() to tell Libevent to only proceed if your
 435    event_base implements a given feature, and you can receive this type from
 436    event_base_get_features() to see which features are available.
 437 */
 438 enum event_method_feature {
 439     /** Require an event method that allows edge-triggered events with EV_ET. */
 440     EV_FEATURE_ET = 0x01,
 441     /** Require an event method where having one event triggered among
 442      * many is [approximately] an O(1) operation. This excludes (for
 443      * example) select and poll, which are approximately O(N) for N
 444      * equal to the total number of possible events. */
 445     EV_FEATURE_O1 = 0x02,
 446     /** Require an event method that allows file descriptors as well as
 447      * sockets. */
 448     EV_FEATURE_FDS = 0x04
 449 };
 450 
 451 /**
 452    A flag passed to event_config_set_flag().
 453 
 454     These flags change the behavior of an allocated event_base.
 455 
 456     @see event_config_set_flag(), event_base_new_with_config(),
 457        event_method_feature
 458  */
 459 enum event_base_config_flag {
 460         /** Do not allocate a lock for the event base, even if we have
 461             locking set up. */
 462         EVENT_BASE_FLAG_NOLOCK = 0x01,
 463         /** Do not check the EVENT_* environment variables when configuring
 464             an event_base  */
 465         EVENT_BASE_FLAG_IGNORE_ENV = 0x02,
 466         /** Windows only: enable the IOCP dispatcher at startup
 467 
 468             If this flag is set then bufferevent_socket_new() and
 469             evconn_listener_new() will use IOCP-backed implementations
 470             instead of the usual select-based one on Windows.
 471          */
 472         EVENT_BASE_FLAG_STARTUP_IOCP = 0x04,
 473         /** Instead of checking the current time every time the event loop is
 474             ready to run timeout callbacks, check after each timeout callback.
 475          */
 476         EVENT_BASE_FLAG_NO_CACHE_TIME = 0x08,
 477 
 478         /** If we are using the epoll backend, this flag says that it is
 479             safe to use Libevent's internal change-list code to batch up
 480             adds and deletes in order to try to do as few syscalls as
 481             possible.  Setting this flag can make your code run faster, but
 482             it may trigger a Linux bug: it is not safe to use this flag
 483             if you have any fds cloned by dup() or its variants.  Doing so
 484             will produce strange and hard-to-diagnose bugs.
 485 
 486             This flag can also be activated by settnig the
 487             EVENT_EPOLL_USE_CHANGELIST environment variable.
 488 
 489             This flag has no effect if you wind up using a backend other than
 490             epoll.
 491          */
 492         EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST = 0x10
 493 };
 494 
 495 /**
 496    Return a bitmask of the features implemented by an event base.  This
 497    will be a bitwise OR of one or more of the values of
 498    event_method_feature
 499 
 500    @see event_method_feature
 501  */
 502 int event_base_get_features(const struct event_base *base);
 503 
 504 /**
 505    Enters a required event method feature that the application demands.
 506 
 507    Note that not every feature or combination of features is supported
 508    on every platform.  Code that requests features should be prepared
 509    to handle the case where event_base_new_with_config() returns NULL, as in:
 510    <pre>
 511      event_config_require_features(cfg, EV_FEATURE_ET);
 512      base = event_base_new_with_config(cfg);
 513      if (base == NULL) {
 514        // We can't get edge-triggered behavior here.
 515        event_config_require_features(cfg, 0);
 516        base = event_base_new_with_config(cfg);
 517      }
 518    </pre>
 519 
 520    @param cfg the event configuration object
 521    @param feature a bitfield of one or more event_method_feature values.
 522           Replaces values from previous calls to this function.
 523    @return 0 on success, -1 on failure.
 524    @see event_method_feature, event_base_new_with_config()
 525 */
 526 int event_config_require_features(struct event_config *cfg, int feature);
 527 
 528 /**
 529  * Sets one or more flags to configure what parts of the eventual event_base
 530  * will be initialized, and how they'll work.
 531  *
 532  * @see event_base_config_flags, event_base_new_with_config()
 533  **/
 534 int event_config_set_flag(struct event_config *cfg, int flag);
 535 
 536 /**
 537  * Records a hint for the number of CPUs in the system. This is used for
 538  * tuning thread pools, etc, for optimal performance.  In Libevent 2.0,
 539  * it is only on Windows, and only when IOCP is in use.
 540  *
 541  * @param cfg the event configuration object
 542  * @param cpus the number of cpus
 543  * @return 0 on success, -1 on failure.
 544  */
 545 int event_config_set_num_cpus_hint(struct event_config *cfg, int cpus);
 546 
 547 /**
 548   Initialize the event API.
 549 
 550   Use event_base_new_with_config() to initialize a new event base, taking
 551   the specified configuration under consideration.  The configuration object
 552   can currently be used to avoid certain event notification mechanisms.
 553 
 554   @param cfg the event configuration object
 555   @return an initialized event_base that can be used to registering events,
 556      or NULL if no event base can be created with the requested event_config.
 557   @see event_base_new(), event_base_free(), event_init(), event_assign()
 558 */
 559 struct event_base *event_base_new_with_config(const struct event_config *);
 560 
 561 /**
 562   Deallocate all memory associated with an event_base, and free the base.
 563 
 564   Note that this function will not close any fds or free any memory passed
 565   to event_new as the argument to callback.
 566 
 567   @param eb an event_base to be freed
 568  */
 569 void event_base_free(struct event_base *);
 570 
 571 /** @name Log severities
 572  */
 573 /**@{*/
 574 #define EVENT_LOG_DEBUG 0
 575 #define EVENT_LOG_MSG   1
 576 #define EVENT_LOG_WARN  2
 577 #define EVENT_LOG_ERR   3
 578 /**@}*/
 579 
 580 /* Obsolete names: these are deprecated, but older programs might use them.
 581  * They violate the reserved-identifier namespace. */
 582 #define _EVENT_LOG_DEBUG EVENT_LOG_DEBUG
 583 #define _EVENT_LOG_MSG EVENT_LOG_MSG
 584 #define _EVENT_LOG_WARN EVENT_LOG_WARN
 585 #define _EVENT_LOG_ERR EVENT_LOG_ERR
 586 
 587 /**
 588   A callback function used to intercept Libevent's log messages.
 589 
 590   @see event_set_log_callback
 591  */
 592 typedef void (*event_log_cb)(int severity, const char *msg);
 593 /**
 594   Redirect Libevent's log messages.
 595 
 596   @param cb a function taking two arguments: an integer severity between
 597      _EVENT_LOG_DEBUG and _EVENT_LOG_ERR, and a string.  If cb is NULL,
 598          then the default log is used.
 599 
 600   NOTE: The function you provide *must not* call any other libevent
 601   functionality.  Doing so can produce undefined behavior.
 602   */
 603 void event_set_log_callback(event_log_cb cb);
 604 
 605 /**
 606    A function to be called if Libevent encounters a fatal internal error.
 607 
 608    @see event_set_fatal_callback
 609  */
 610 typedef void (*event_fatal_cb)(int err);
 611 
 612 /**
 613  Override Libevent's behavior in the event of a fatal internal error.
 614 
 615  By default, Libevent will call exit(1) if a programming error makes it
 616  impossible to continue correct operation.  This function allows you to supply
 617  another callback instead.  Note that if the function is ever invoked,
 618  something is wrong with your program, or with Libevent: any subsequent calls
 619  to Libevent may result in undefined behavior.
 620 
 621  Libevent will (almost) always log an _EVENT_LOG_ERR message before calling
 622  this function; look at the last log message to see why Libevent has died.
 623  */
 624 void event_set_fatal_callback(event_fatal_cb cb);
 625 
 626 /**
 627   Associate a different event base with an event.
 628 
 629   The event to be associated must not be currently active or pending.
 630 
 631   @param eb the event base
 632   @param ev the event
 633   @return 0 on success, -1 on failure.
 634  */
 635 int event_base_set(struct event_base *, struct event *);
 636 
 637 /** @name Loop flags
 638 
 639     These flags control the behavior of event_base_loop().
 640  */
 641 /**@{*/
 642 /** Block until we have an active event, then exit once all active events
 643  * have had their callbacks run. */
 644 #define EVLOOP_ONCE     0x01
 645 /** Do not block: see which events are ready now, run the callbacks
 646  * of the highest-priority ones, then exit. */
 647 #define EVLOOP_NONBLOCK 0x02
 648 /**@}*/
 649 
 650 /**
 651   Wait for events to become active, and run their callbacks.
 652 
 653   This is a more flexible version of event_base_dispatch().
 654 
 655   By default, this loop will run the event base until either there are no more
 656   added events, or until something calls event_base_loopbreak() or
 657   evenet_base_loopexit().  You can override this behavior with the 'flags'
 658   argument.
 659 
 660   @param eb the event_base structure returned by event_base_new() or
 661      event_base_new_with_config()
 662   @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK
 663   @return 0 if successful, -1 if an error occurred, or 1 if no events were
 664     registered.
 665   @see event_base_loopexit(), event_base_dispatch(), EVLOOP_ONCE,
 666      EVLOOP_NONBLOCK
 667   */
 668 int event_base_loop(struct event_base *, int);
 669 
 670 /**
 671   Exit the event loop after the specified time
 672 
 673   The next event_base_loop() iteration after the given timer expires will
 674   complete normally (handling all queued events) then exit without
 675   blocking for events again.
 676 
 677   Subsequent invocations of event_base_loop() will proceed normally.
 678 
 679   @param eb the event_base structure returned by event_init()
 680   @param tv the amount of time after which the loop should terminate,
 681     or NULL to exit after running all currently active events.
 682   @return 0 if successful, or -1 if an error occurred
 683   @see event_base_loopbreak()
 684  */
 685 int event_base_loopexit(struct event_base *, const struct timeval *);
 686 
 687 /**
 688   Abort the active event_base_loop() immediately.
 689 
 690   event_base_loop() will abort the loop after the next event is completed;
 691   event_base_loopbreak() is typically invoked from this event's callback.
 692   This behavior is analogous to the "break;" statement.
 693 
 694   Subsequent invocations of event_loop() will proceed normally.
 695 
 696   @param eb the event_base structure returned by event_init()
 697   @return 0 if successful, or -1 if an error occurred
 698   @see event_base_loopexit()
 699  */
 700 int event_base_loopbreak(struct event_base *);
 701 
 702 /**
 703   Checks if the event loop was told to exit by event_loopexit().
 704 
 705   This function will return true for an event_base at every point after
 706   event_loopexit() is called, until the event loop is next entered.
 707 
 708   @param eb the event_base structure returned by event_init()
 709   @return true if event_base_loopexit() was called on this event base,
 710     or 0 otherwise
 711   @see event_base_loopexit()
 712   @see event_base_got_break()
 713  */
 714 int event_base_got_exit(struct event_base *);
 715 
 716 /**
 717   Checks if the event loop was told to abort immediately by event_loopbreak().
 718 
 719   This function will return true for an event_base at every point after
 720   event_loopbreak() is called, until the event loop is next entered.
 721 
 722   @param eb the event_base structure returned by event_init()
 723   @return true if event_base_loopbreak() was called on this event base,
 724     or 0 otherwise
 725   @see event_base_loopbreak()
 726   @see event_base_got_exit()
 727  */
 728 int event_base_got_break(struct event_base *);
 729 
 730 /**
 731  * @name event flags
 732  *
 733  * Flags to pass to event_new(), event_assign(), event_pending(), and
 734  * anything else with an argument of the form "short events"
 735  */
 736 /**@{*/
 737 /** Indicates that a timeout has occurred.  It's not necessary to pass
 738  * this flag to event_for new()/event_assign() to get a timeout. */
 739 #define EV_TIMEOUT      0x01
 740 /** Wait for a socket or FD to become readable */
 741 #define EV_READ         0x02
 742 /** Wait for a socket or FD to become writeable */
 743 #define EV_WRITE        0x04
 744 /** Wait for a POSIX signal to be raised*/
 745 #define EV_SIGNAL       0x08
 746 /**
 747  * Persistent event: won't get removed automatically when activated.
 748  *
 749  * When a persistent event with a timeout becomes activated, its timeout
 750  * is reset to 0.
 751  */
 752 #define EV_PERSIST      0x10
 753 /** Select edge-triggered behavior, if supported by the backend. */
 754 #define EV_ET       0x20
 755 /**@}*/
 756 
 757 /**
 758    @name evtimer_* macros
 759 
 760     Aliases for working with one-shot timer events */
 761 /**@{*/
 762 #define evtimer_assign(ev, b, cb, arg) \
 763         event_assign((ev), (b), -1, 0, (cb), (arg))
 764 #define evtimer_new(b, cb, arg)        event_new((b), -1, 0, (cb), (arg))
 765 #define evtimer_add(ev, tv)             event_add((ev), (tv))
 766 #define evtimer_del(ev)                 event_del(ev)
 767 #define evtimer_pending(ev, tv)         event_pending((ev), EV_TIMEOUT, (tv))
 768 #define evtimer_initialized(ev)         event_initialized(ev)
 769 /**@}*/
 770 
 771 /**
 772    @name evsignal_* macros
 773 
 774    Aliases for working with signal events
 775  */
 776 /**@{*/
 777 #define evsignal_add(ev, tv)            event_add((ev), (tv))
 778 #define evsignal_assign(ev, b, x, cb, arg)                      \
 779         event_assign((ev), (b), (x), EV_SIGNAL|EV_PERSIST, cb, (arg))
 780 #define evsignal_new(b, x, cb, arg)                             \
 781         event_new((b), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg))
 782 #define evsignal_del(ev)                event_del(ev)
 783 #define evsignal_pending(ev, tv)        event_pending((ev), EV_SIGNAL, (tv))
 784 #define evsignal_initialized(ev)        event_initialized(ev)
 785 /**@}*/
 786 
 787 /**
 788    A callback function for an event.
 789 
 790    It receives three arguments:
 791 
 792    @param fd An fd or signal
 793    @param events One or more EV_* flags
 794    @param arg A user-supplied argument.
 795 
 796    @see event_new()
 797  */
 798 typedef void (*event_callback_fn)(evutil_socket_t, short, void *);
 799 
 800 /**
 801   Allocate and asssign a new event structure, ready to be added.
 802 
 803   The function event_new() returns a new event that can be used in
 804   future calls to event_add() and event_del().  The fd and events
 805   arguments determine which conditions will trigger the event; the
 806   callback and callback_arg arguments tell Libevent what to do when the
 807   event becomes active.
 808 
 809   If events contains one of EV_READ, EV_WRITE, or EV_READ|EV_WRITE, then
 810   fd is a file descriptor or socket that should get monitored for
 811   readiness to read, readiness to write, or readiness for either operation
 812   (respectively).  If events contains EV_SIGNAL, then fd is a signal
 813   number to wait for.  If events contains none of those flags, then the
 814   event can be triggered only by a timeout or by manual activation with
 815   event_active(): In this case, fd must be -1.
 816 
 817   The EV_PERSIST flag can also be passed in the events argument: it makes
 818   event_add() persistent until event_del() is called.
 819 
 820   The EV_ET flag is compatible with EV_READ and EV_WRITE, and supported
 821   only by certain backends.  It tells Libevent to use edge-triggered
 822   events.
 823 
 824   The EV_TIMEOUT flag has no effect here.
 825 
 826   It is okay to have multiple events all listening on the same fds; but
 827   they must either all be edge-triggered, or all not be edge triggerd.
 828 
 829   When the event becomes active, the event loop will run the provided
 830   callbuck function, with three arguments.  The first will be the provided
 831   fd value.  The second will be a bitfield of the events that triggered:
 832   EV_READ, EV_WRITE, or EV_SIGNAL.  Here the EV_TIMEOUT flag indicates
 833   that a timeout occurred, and EV_ET indicates that an edge-triggered
 834   event occurred.  The third event will be the callback_arg pointer that
 835   you provide.
 836 
 837   @param base the event base to which the event should be attached.
 838   @param fd the file descriptor or signal to be monitored, or -1.
 839   @param events desired events to monitor: bitfield of EV_READ, EV_WRITE,
 840       EV_SIGNAL, EV_PERSIST, EV_ET.
 841   @param callback callback function to be invoked when the event occurs
 842   @param callback_arg an argument to be passed to the callback function
 843 
 844   @return a newly allocated struct event that must later be freed with
 845     event_free().
 846   @see event_free(), event_add(), event_del(), event_assign()
 847  */
 848 struct event *event_new(struct event_base *, evutil_socket_t, short, event_callback_fn, void *);
 849 
 850 
 851 /**
 852   Prepare a new, already-allocated event structure to be added.
 853 
 854   The function event_assign() prepares the event structure ev to be used
 855   in future calls to event_add() and event_del().  Unlike event_new(), it
 856   doesn't allocate memory itself: it requires that you have already
 857   allocated a struct event, probably on the heap.  Doing this will
 858   typically make your code depend on the size of the event structure, and
 859   thereby create incompatibility with future versions of Libevent.
 860 
 861   The easiest way to avoid this problem is just to use event_new() and
 862   event_free() instead.
 863 
 864   A slightly harder way to future-proof your code is to use
 865   event_get_struct_event_size() to determine the required size of an event
 866   at runtime.
 867 
 868   Note that it is NOT safe to call this function on an event that is
 869   active or pending.  Doing so WILL corrupt internal data structures in
 870   Libevent, and lead to strange, hard-to-diagnose bugs.  You _can_ use
 871   event_assign to change an existing event, but only if it is not active
 872   or pending!
 873 
 874   The arguments for this function, and the behavior of the events that it
 875   makes, are as for event_new().
 876 
 877   @param ev an event struct to be modified
 878   @param base the event base to which ev should be attached.
 879   @param fd the file descriptor to be monitored
 880   @param events desired events to monitor; can be EV_READ and/or EV_WRITE
 881   @param callback callback function to be invoked when the event occurs
 882   @param callback_arg an argument to be passed to the callback function
 883 
 884   @return 0 if success, or -1 on invalid arguments.
 885 
 886   @see event_new(), event_add(), event_del(), event_base_once(),
 887     event_get_struct_event_size()
 888   */
 889 int event_assign(struct event *, struct event_base *, evutil_socket_t, short, event_callback_fn, void *);
 890 
 891 /**
 892    Deallocate a struct event * returned by event_new().
 893 
 894    If the event is pending or active, first make it non-pending and
 895    non-active.
 896  */
 897 void event_free(struct event *);
 898 
 899 /**
 900   Schedule a one-time event
 901 
 902   The function event_base_once() is similar to event_set().  However, it
 903   schedules a callback to be called exactly once, and does not require the
 904   caller to prepare an event structure.
 905 
 906   Note that in Libevent 2.0 and earlier, if the event is never triggered,
 907   the internal memory used to hold it will never be freed.  This may be
 908   fixed in a later version of Libevent.
 909 
 910   @param base an event_base
 911   @param fd a file descriptor to monitor, or -1 for no fd.
 912   @param events event(s) to monitor; can be any of EV_READ |
 913          EV_WRITE, or EV_TIMEOUT
 914   @param callback callback function to be invoked when the event occurs
 915   @param arg an argument to be passed to the callback function
 916   @param timeout the maximum amount of time to wait for the event. NULL
 917          makes an EV_READ/EV_WRITE event make forever; NULL makes an
 918         EV_TIMEOUT event succees immediately.
 919   @return 0 if successful, or -1 if an error occurred
 920  */
 921 int event_base_once(struct event_base *, evutil_socket_t, short, event_callback_fn, void *, const struct timeval *);
 922 
 923 /**
 924   Add an event to the set of pending events.
 925 
 926   The function event_add() schedules the execution of the ev event when the
 927   event specified in event_assign()/event_new() occurs, or when the time
 928   specified in timeout has elapesed.  If atimeout is NULL, no timeout
 929   occurs and the function will only be
 930   called if a matching event occurs.  The event in the
 931   ev argument must be already initialized by event_assign() or event_new()
 932   and may not be used
 933   in calls to event_assign() until it is no longer pending.
 934 
 935   If the event in the ev argument already has a scheduled timeout, calling
 936   event_add() replaces the old timeout with the new one, or clears the old
 937   timeout if the timeout argument is NULL.
 938 
 939   @param ev an event struct initialized via event_set()
 940   @param timeout the maximum amount of time to wait for the event, or NULL
 941          to wait forever
 942   @return 0 if successful, or -1 if an error occurred
 943   @see event_del(), event_assign(), event_new()
 944   */
 945 int event_add(struct event *ev, const struct timeval *timeout);
 946 
 947 /**
 948   Remove an event from the set of monitored events.
 949 
 950   The function event_del() will cancel the event in the argument ev.  If the
 951   event has already executed or has never been added the call will have no
 952   effect.
 953 
 954   @param ev an event struct to be removed from the working set
 955   @return 0 if successful, or -1 if an error occurred
 956   @see event_add()
 957  */
 958 int event_del(struct event *);
 959 
 960 
 961 /**
 962   Make an event active.
 963 
 964   You can use this function on a pending or a non-pending event to make it
 965   active, so that its callback will be run by event_base_dispatch() or
 966   event_base_loop().
 967 
 968   One common use in multithreaded programs is to wake the thread running
 969   event_base_loop() from another thread.
 970 
 971   @param ev an event to make active.
 972   @param res a set of flags to pass to the event's callback.
 973   @param ncalls an obsolete argument: this is ignored.
 974  **/
 975 void event_active(struct event *ev, int res, short ncalls);
 976 
 977 /**
 978   Checks if a specific event is pending or scheduled.
 979 
 980   @param ev an event struct previously passed to event_add()
 981   @param events the requested event type; any of EV_TIMEOUT|EV_READ|
 982          EV_WRITE|EV_SIGNAL
 983   @param tv if this field is not NULL, and the event has a timeout,
 984          this field is set to hold the time at which the timeout will
 985          expire.
 986 
 987   @return true if the event is pending on any of the events in 'what', (that
 988   is to say, it has been added), or 0 if the event is not added.
 989  */
 990 int event_pending(const struct event *ev, short events, struct timeval *tv);
 991 
 992 
 993 /**
 994   Test if an event structure might be initialized.
 995 
 996   The event_initialized() function can be used to check if an event has been
 997   initialized.
 998 
 999   Warning: This function is only useful for distinguishing a a zeroed-out
1000     piece of memory from an initialized event, it can easily be confused by
1001     uninitialized memory.  Thus, it should ONLY be used to distinguish an
1002     initialized event from zero.
1003 
1004   @param ev an event structure to be tested
1005   @return 1 if the structure might be initialized, or 0 if it has not been
1006           initialized
1007  */
1008 int event_initialized(const struct event *ev);
1009 
1010 /**
1011    Get the signal number assigned to a signal event
1012 */
1013 #define event_get_signal(ev) ((int)event_get_fd(ev))
1014 
1015 /**
1016    Get the socket or signal assigned to an event, or -1 if the event has
1017    no socket.
1018 */
1019 evutil_socket_t event_get_fd(const struct event *ev);
1020 
1021 /**
1022    Get the event_base associated with an event.
1023 */
1024 struct event_base *event_get_base(const struct event *ev);
1025 
1026 /**
1027    Return the events (EV_READ, EV_WRITE, etc) assigned to an event.
1028 */
1029 short event_get_events(const struct event *ev);
1030 
1031 /**
1032    Return the callback assigned to an event.
1033 */
1034 event_callback_fn event_get_callback(const struct event *ev);
1035 
1036 /**
1037    Return the callback argument assigned to an event.
1038 */
1039 void *event_get_callback_arg(const struct event *ev);
1040 
1041 /**
1042    Extract _all_ of arguments given to construct a given event.  The
1043    event_base is copied into *base_out, the fd is copied into *fd_out, and so
1044    on.
1045 
1046    If any of the "_out" arguments is NULL, it will be ignored.
1047  */
1048 void event_get_assignment(const struct event *event,
1049     struct event_base **base_out, evutil_socket_t *fd_out, short *events_out,
1050     event_callback_fn *callback_out, void **arg_out);
1051 
1052 /**
1053    Return the size of struct event that the Libevent library was compiled
1054    with.
1055 
1056    This will be NO GREATER than sizeof(struct event) if you're running with
1057    the same version of Libevent that your application was built with, but
1058    otherwise might not.
1059 
1060    Note that it might be SMALLER than sizeof(struct event) if some future
1061    version of Libevent adds extra padding to the end of struct event.
1062    We might do this to help ensure ABI-compatibility between different
1063    versions of Libevent.
1064  */
1065 size_t event_get_struct_event_size(void);
1066 
1067 /**
1068    Get the Libevent version.
1069 
1070    Note that this will give you the version of the library that you're
1071    currently linked against, not the version of the headers that you've
1072    compiled against.
1073 
1074    @return a string containing the version number of Libevent
1075 */
1076 const char *event_get_version(void);
1077 
1078 /**
1079    Return a numeric representation of Libevent's version.
1080 
1081    Note that this will give you the version of the library that you're
1082    currently linked against, not the version of the headers you've used to
1083    compile.
1084 
1085    The format uses one byte each for the major, minor, and patchlevel parts of
1086    the version number.  The low-order byte is unused.  For example, version
1087    2.0.1-alpha has a numeric representation of 0x02000100
1088 */
1089 ev_uint32_t event_get_version_number(void);
1090 
1091 /** As event_get_version, but gives the version of Libevent's headers. */
1092 #define LIBEVENT_VERSION _EVENT_VERSION
1093 /** As event_get_version_number, but gives the version number of Libevent's
1094  * headers. */
1095 #define LIBEVENT_VERSION_NUMBER _EVENT_NUMERIC_VERSION
1096 
1097 /** Largest number of priorities that Libevent can support. */
1098 #define EVENT_MAX_PRIORITIES 256
1099 /**
1100   Set the number of different event priorities
1101 
1102   By default Libevent schedules all active events with the same priority.
1103   However, some time it is desirable to process some events with a higher
1104   priority than others.  For that reason, Libevent supports strict priority
1105   queues.  Active events with a lower priority are always processed before
1106   events with a higher priority.
1107 
1108   The number of different priorities can be set initially with the
1109   event_base_priority_init() function.  This function should be called
1110   before the first call to event_base_dispatch().  The
1111   event_priority_set() function can be used to assign a priority to an
1112   event.  By default, Libevent assigns the middle priority to all events
1113   unless their priority is explicitly set.
1114 
1115   Note that urgent-priority events can starve less-urgent events: after
1116   running all urgent-priority callbacks, Libevent checks for more urgent
1117   events again, before running less-urgent events.  Less-urgent events
1118   will not have their callbacks run until there are no events more urgent
1119   than them that want to be active.
1120 
1121   @param eb the event_base structure returned by event_base_new()
1122   @param npriorities the maximum number of priorities
1123   @return 0 if successful, or -1 if an error occurred
1124   @see event_priority_set()
1125  */
1126 int     event_base_priority_init(struct event_base *, int);
1127 
1128 /**
1129   Assign a priority to an event.
1130 
1131   @param ev an event struct
1132   @param priority the new priority to be assigned
1133   @return 0 if successful, or -1 if an error occurred
1134   @see event_priority_init()
1135   */
1136 int     event_priority_set(struct event *, int);
1137 
1138 /**
1139    Prepare an event_base to use a large number of timeouts with the same
1140    duration.
1141 
1142    Libevent's default scheduling algorithm is optimized for having a large
1143    number of timeouts with their durations more or less randomly
1144    distributed.  But if you have a large number of timeouts that all have
1145    the same duration (for example, if you have a large number of
1146    connections that all have a 10-second timeout), then you can improve
1147    Libevent's performance by telling Libevent about it.
1148 
1149    To do this, call this function with the common duration.  It will return a
1150    pointer to a different, opaque timeout value.  (Don't depend on its actual
1151    contents!)  When you use this timeout value in event_add(), Libevent will
1152    schedule the event more efficiently.
1153 
1154    (This optimization probably will not be worthwhile until you have thousands
1155    or tens of thousands of events with the same timeout.)
1156  */
1157 const struct timeval *event_base_init_common_timeout(struct event_base *base,
1158     const struct timeval *duration);
1159 
1160 #if !defined(_EVENT_DISABLE_MM_REPLACEMENT) || defined(_EVENT_IN_DOXYGEN)
1161 /**
1162  Override the functions that Libevent uses for memory management.
1163 
1164  Usually, Libevent uses the standard libc functions malloc, realloc, and
1165  free to allocate memory.  Passing replacements for those functions to
1166  event_set_mem_functions() overrides this behavior.
1167 
1168  Note that all memory returned from Libevent will be allocated by the
1169  replacement functions rather than by malloc() and realloc().  Thus, if you
1170  have replaced those functions, it will not be appropriate to free() memory
1171  that you get from Libevent.  Instead, you must use the free_fn replacement
1172  that you provided.
1173 
1174  Note also that if you are going to call this function, you should do so
1175  before any call to any Libevent function that does allocation.
1176  Otherwise, those funtions will allocate their memory using malloc(), but
1177  then later free it using your provided free_fn.
1178 
1179  @param malloc_fn A replacement for malloc.
1180  @param realloc_fn A replacement for realloc
1181  @param free_fn A replacement for free.
1182  **/
1183 void event_set_mem_functions(
1184         void *(*malloc_fn)(size_t sz),
1185         void *(*realloc_fn)(void *ptr, size_t sz),
1186         void (*free_fn)(void *ptr));
1187 /** This definition is present if Libevent was built with support for
1188     event_set_mem_functions() */
1189 #define EVENT_SET_MEM_FUNCTIONS_IMPLEMENTED
1190 #endif
1191 
1192 void event_base_dump_events(struct event_base *, FILE *);
1193 
1194 /** Sets 'tv' to the current time (as returned by gettimeofday()),
1195     looking at the cached value in 'base' if possible, and calling
1196     gettimeofday() or clock_gettime() as appropriate if there is no
1197     cached time.
1198 
1199     Generally, this value will only be cached while actually
1200     processing event callbacks, and may be very inaccuate if your
1201     callbacks take a long time to execute.
1202 
1203     Returns 0 on success, negative on failure.
1204  */
1205 int event_base_gettimeofday_cached(struct event_base *base,
1206     struct timeval *tv);
1207 
1208 #ifdef __cplusplus
1209 }
1210 #endif
1211 
1212 #endif /* _EVENT2_EVENT_H_ */

/* [<][>][^][v][top][bottom][index][help] */