Class EventPublisher

• Defined in File event-publisher.h

Nested Relationships

Nested Types

• Struct EventPublisher::Subscriber

Class Documentation

class EventPublisher

The EventPublisher class is a thread-safe, multi-publisher multi-subscriber event/message dispatch class. This is a singleton class, so only one can be instantiated in any application that links to this library.

Public Functions

virtual ~EventPublisher()

virtual void Start() = 0

Begin the dispatch thread.

This is separate from the dispatcher initialization in the constructor for platforms where it may not be possible to create threads at the time of dispatcher construction. The caller is responsible for determining when it is safe to create threads and invoke this method accordingly.

Note

It is not required to call this method; if this method is not called, then all events/messages will be delivered synchronously at the time of publication.

virtual void Publish(char const **topics, EventData *event) = 0

Publish an event/message to registered subscribers.

Note

If the Start() method is called, and the dispatcher delivers events/messages asynchronously, then events/messages can be delivered at any time after publication (including at the time of publication). Otherwise, event is guaranteed to have been delivered to all subscribers registered for topics before returning from this call.

Parameters

• topics -- A null-terminated array of string pointers referencing the names of the topics on which to publish event.

• event -- EventData implementation containing the event/message data to deliver. Because it is possible for events/messages to be delivered asynchronously, it is required that event be created on the heap and not the stack; EventPublisher will take ownership of the object and call its destructor once it has been delivered to all subscribers registered for topics.

virtual void Publish(char const *topic, EventData *event) = 0

Publish an event/message to registered subscribers.

Note

If the Start() method is called, and the dispatcher delivers events/messages asynchronously, then events/messages can be delivered at any time after publication (including at the time of publication). Otherwise, event is guaranteed to have been delivered to all subscribers registered for topic before returning from this call.

Parameters

• topic -- A string pointer referencing the name of the topic on which to publish event.

• event -- EventData implementation containing the event/message data to deliver. Because it is possible for events/messages to be delivered asynchronously, it is required that event be created on the heap and not the stack; EventPublisher will take ownership of the object and call its destructor once it has been delivered to all subscribers registered for topic.

virtual void Subscribe(char const **topics, Subscriber *subscriber) = 0

Subscribe subscriber to receive notifications of event/message publication on topics.

Parameters

• topics -- A null-terminated array of string pointers referencing the names of the topics on which subscriber wishes to recieve event/message activity.

• subscriber -- Implementation of Subscriber interface. Does not need to be a heap object, as EventPublisher does not assume ownership of the implementation.

virtual void Unsubscribe(char const **topics, Subscriber *subscriber) = 0

Unsubscribe a previously-subscribed subscriber.

Parameters

• topics -- Topics for which the subscriber no longer wishes to recieve events/messages.

• subscriber -- Implementation of Subscriber interface to unregister.

struct Subscriber

Subscribers to the event/message dispatcher will implement this interface.

Subclassed by gpa::playback::MetricsExtractor, gpa::runtime::ActionPublisher

Public Functions

virtual ~Subscriber()

virtual void OnEvent(char const *topic, EventData const &event) = 0

When an event/message is available on a topic for which this subscriber has registered, it will be delivered via this method.

Note

If the data in the event/message needs to be used beyond the scope of this method, the implementation should copy the relevant contents of the event/message and not attempt to cache the event object itself, as there is no guarantee that the event object will be available beyond this method's return.

Parameters

• topic -- Name of the topic ("channel") on which the event was published.

• event -- The event data. The implementation should use the EventData::ID() method to determine the actual event/message type, and cast accordingly.