Events

Events are a central data-type to “eventing” libraries such as libevent. Whenever you trigger an action that has a delayed response, such as setting a timer or reading from the network, an event is involved.

Events are essentially a handle representing your callback. While they cannot be composed as you might do with higher level constructs such as a Future or Pomise, they can be canceled which can be useful if developing higher level abstractions on top of Event.

Example

1
2
3
4
5
6
auto reactor = pembroke::reactor().build();
auto x = 0;

auto event = reactor->new_timer([&]() -> void {
    x += 1;
}, 100us);

If this event is not canceled, then in 100 micro-seconds the callback will run and x will have a value of 1. Cancelling the event may prevent this from happening if done before the callback triggers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
event->cancel();
assert(x == 0);

// OR if called after

std::this_thread.sleep_for(200us);
reactor->tick();
bool ret = event->cancel();

assert(ret == true); // successfully called cancel
assert(x == 1);      // BUT still ran event because it was cancelled too late

pembroke::Event

class Event

Represents a scheduled event to the user and provides a mechanism to cancel the event, assuming it is still pending.

Event objects may be received when scheduling many types of events (I/O, timers, etc).

Public Functions

bool cancel()

Cancels the event if it has not already completed and had it’s callback run. If the event has completed, calling cancel() will return True and have not effect.

Return

True if successfully canceled, False otherwise

pembroke::EventContext

struct EventContext

A companion class that is of use to any class/method that is responsible for creating events on the Reactor and needs a mechanism to tie Events into the libevent sub-system.

The EventContext can be stored in a hash by way of the EventContextHash using the key field of the EventContext.

// using in unordered set
std::unordered_set<EventContext, EventContextHash> my_events;

Note

If the EventContext object is intended to be stored in a map/set then the context must be populated with a unique-key. The EventContextHash will simply use this key (without transformations) to serve as the hash. Failure to set a unique value will break your hash/map.

See

pembroke::Reactor

See

pembroke::EventContextHash

Public Functions

EventContext(uint64_t key, std::function<void()> cb)

Parameters

  • key: Unique key to identify your event. This value will be used by the EventContextHash to provide a unique hash-value for maps/sets.

  • cb: User-provided callback to be called upon event completion

Public Members

const uint64_t key

Unique Identifier for ctx

const std::function<void()> callback

Callback called on event completion (user defined)

const struct event *event = nullptr

Event object that class represents

std::function<void()> post_event_cleanup = util::nop_f

A cleanup method that can be set by the class/method coordinating the event.

pembroke::EventContextHash

struct EventContextHash

Simple hash function to support using EventContext within a set/map.

Public Functions

size_t operator()(const std::shared_ptr<EventContext> &ctx) const

Parameters

  • ctx: Event context to return a hash for