Structure to hold information and state for a Libevent dispatch loop.
The event_base lies at the center of Libevent; every application will have one. It keeps track of all pending and active events, and notifies your application of the active ones.
This is an opaque structure; you can allocate one using event_base_new() or event_base_new_with_config().
@see event_base_new(), event_base_free(), event_base_loop(), event_base_new_with_config()
@struct event
Structure to represent a single event.
An event can have some underlying condition it represents: a socket becoming readable or writeable (or both), or a signal becoming raised. (An event that represents no underlying condition is still useful: you can use one to implement a timer, or to communicate between threads.)
Generally, you can create events with event_new(), then make them pending with event_add(). As your event_base runs, it will run the callbacks of an events whose conditions are triggered. When you longer want the event, free it with event_free().
In more depth:
An event may be "pending" (one whose condition we are watching), "active" (one whose condition has triggered and whose callback is about to run), neither, or both. Events come into existence via event_assign() or event_new(), and are then neither active nor pending.
To make an event pending, pass it to event_add(). When doing so, you can also set a timeout for the event.
Events become active during an event_base_loop() call when either their condition has triggered, or when their timeout has elapsed. You can also activate an event manually using event_active(). The even_base loop will run the callbacks of active events; after it has done so, it marks them as no longer active.
You can make an event non-pending by passing it to event_del(). This also makes the event non-active.
Events can be "persistent" or "non-persistent". A non-persistent event becomes non-pending as soon as it is triggered: thus, it only runs at most once per call to event_add(). A persistent event remains pending even when it becomes active: you'll need to event_del() it manually in order to make it non-pending. When a persistent event with a timeout becomes active, its timeout is reset: this means you can use persistent events to implement periodic timeouts.
This should be treated as an opaque structure; you should never read or write any of its fields directly. For backward compatibility with old code, it is defined in the event2/event_struct.h header; including this header may make your code incompatible with other versions of Libevent.
@see event_new(), event_free(), event_assign(), event_get_assignment(), event_add(), event_del(), event_active(), event_pending(), event_get_fd(), event_get_base(), event_get_events(), event_get_callback(), event_get_callback_arg(), event_priority_set()
A callback function for an event.
A function to be called if Libevent encounters a fatal internal error.
A callback function used to intercept Libevent's log messages.
@{
A flag passed to event_config_set_flag().
A flag used to describe which features an event_base (must) provide.
Make an event active.
Add an event to the set of pending events.
Prepare a new, already-allocated event structure to be added.
Event dispatching loop
Deallocate all memory associated with an event_base, and free the base.
Return a bitmask of the features implemented by an event base. This will be a bitwise OR of one or more of the values of event_method_feature
Get the kernel event notification mechanism used by Libevent.
Sets 'tv' to the current time (as returned by gettimeofday()), looking at the cached value in 'base' if possible, and calling gettimeofday() or clock_gettime() as appropriate if there is no cached time.
Checks if the event loop was told to abort immediately by event_loopbreak().
Checks if the event loop was told to exit by event_loopexit().
Prepare an event_base to use a large number of timeouts with the same duration.
Wait for events to become active, and run their callbacks.
Abort the active event_base_loop() immediately.
Exit the event loop after the specified time
Create and return a new event_base to use with the rest of Libevent.
Initialize the event API.
Schedule a one-time event
Set the number of different event priorities
Associate a different event base with an event.
Enters an event method that should be avoided into the configuration.
Deallocates all memory associated with an event configuration object
Allocates a new event configuration object.
Enters a required event method feature that the application demands.
Sets one or more flags to configure what parts of the eventual event_base will be initialized, and how they'll work.
Records a hint for the number of CPUs in the system. This is used for tuning thread pools, etc, for optimal performance. In Libevent 2.0, it is only on Windows, and only when IOCP is in use.
When debugging mode is enabled, informs Libevent that an event should no longer be considered as assigned. When debugging mode is not enabled, does nothing.
Remove an event from the set of monitored events.
Enable some relatively expensive debugging checks in Libevent that would normally be turned off. Generally, these checks cause code that would otherwise crash mysteriously to fail earlier with an assertion failure. Note that this method MUST be called before any events or event_bases have been created.
Deallocate a event* returned by event_new().
Extract _all_ of arguments given to cona given event. The event_base is copied into* base_out, the fd is copied into* fd_out, and so on.
Get the event_base associated with an event.
Return the callback assigned to an event.
Return the callback argument assigned to an event.
Return the events (EV_READ, EV_WRITE, etc) assigned to an event.
Get the socket or signal assigned to an event, or -1 if the event has no socket.
Get the signal number assigned to a signal event
Return the size of event that the Libevent library was compiled with.
Gets all event notification mechanisms supported by Libevent.
Get the Libevent version.
Return a numeric representation of Libevent's version.
Test if an event structure might be initialized.
Allocate and asssign a new event structure, ready to be added.
Checks if a specific event is pending or scheduled.
Assign a priority to an event.
Reinitialize the event base after a fork
Override Libevent's behavior in the event of a fatal internal error.
Redirect Libevent's log messages.
Override the functions that Libevent uses for memory management.
@{
Largest number of priorities that Libevent can support.
This definition is present if Libevent was built with support for event_set_mem_functions()
Do not block: see which events are ready now, run the callbacks * of the highest-priority ones, then exit.
Block until we have an active event, then exit once all active events * have had their callbacks run.
Select edge-triggered behavior, if supported by the backend.
Persistent event: won't get removed automatically when activated.
Wait for a socket or FD to become readable
Wait for a POSIX signal to be raised
Indicates that a timeout has occurred. It's not necessary to pass * this flag to event_for new()/event_assign() to get a timeout.
Wait for a socket or FD to become writeable
As event_get_version, but gives the version of Libevent's headers.
As event_get_version_number, but gives the version number of Libevent's headers.
@{
Configuration for an event_base.
@file event2/event.h
Core functions for waiting for and receiving events, and using event bases.