Detailed Description

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 no 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 also: 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()

The documentation for this struct was generated from the following file:

event2/event.h