carb::events::IEventStream

class IEventStream : public carb::IObject 

Event stream is fundamental primitive used to send, receive and listen for events.

Different event system models can be designed using it. It is thread-safe and can also be used as a sync primitive. Similar to Go Language Channels.

Basically stream is just a queue with listeners:

                             +------------------+
   push() / pushBlocked()    |                  |   tryPop() / pop()
+--------------------------->+   IEventStream   +------------------------>
                        ^    |                  |    ^
                        |    +------------------+    |
      subscribeToPush() |                            |  subscribeToPop()
                        |                            |
                        |                            |
              +---------+--------+          +--------+---------+
              |  IEventListener  |          |  IEventListener  |
              +------------------+          +------------------+

You can push to stream and pop events (acts like a queue).
Given the stream you can listen for pushed and/or popped events. That is basically immediate callbacks vs deferred callbacks.
Blocking methods (pushBlocked() and pop()) will block the thread until event is popped (for push method) or any event is pushed (for pop method). That can be used as thread sync.
Pumping of stream is just popping all events until it is empty.
EventType allows you to filter which events to listen for. IEventStream may contain only one type, conceptually more like channels, or a lot of events - like event bus.
Listeners are subscribed specifying the order in which they want to receive events. When processing, they may consume an event which stops other listeners from receiving it (only when being dispatched).

Public Functions

virtual IEvent *createEventPtr(EventType eventType, SenderId sender) = 0

Create new event of certain type.

Parameters

eventType – The type of event to create.
sender – The sender of the event, or carb::events::kGlobalSenderId.

Returns

A pointer to a newly created event.

template<typename ...ValuesT> inline ObjectPtr<IEvent> createEvent(EventType eventType, SenderId sender, ValuesT&&... values)

Create new event of certain type.

Parameters

eventType – The type of event to create.
sender – The sender of the event, or carb::events::kGlobalSenderId.
values – Key/value pairs as passed to IEvent::setValues().

Returns

A pointer to a newly created event.

virtual void dispatch(IEvent *e) = 0

Dispatch event immediately without putting it into stream.

Parameters: e – The event to dispatch.

virtual void push(IEvent *e) = 0

Push event into the stream.

Parameters: e – The event to push.

virtual void pushBlocked(IEvent *e) = 0

Push event into the stream and block until it is dispatched by some other thread.

Parameters: e – The event to push.

virtual size_t getCount() = 0

Get approximate number of events waiting for dispatch in the stream.

Thread Safety: While safe to call from multiple threads, since there is no lock involved this value should be considered approximate as another thread could modify the number before the return value is read. This call is strongly ordered with respect to other calls.

Returns: The approximate number of events waiting for dispatch in the stream.

inline ObjectPtr<IEvent> pop()

Pop and dispatches a single event from the stream, blocking until one becomes available.

Warning

This function blocks until an event is available.

Returns: The event that was popped and dispatched.

virtual IEvent *popPtr() = 0

Pop and dispatches a single event from the stream, blocking until one becomes available.

Warning

This function blocks until an event is available.

Returns: The event that was popped and dispatched.

inline ObjectPtr<IEvent> tryPop()

Pops and dispatches a single event from the stream, if available.

Note

Unlike pop(), this function does not wait for an event to become available.

Returns: The event that was popped and dispatched, or nullptr if no event was available.

virtual IEvent *tryPopPtr() = 0

Pops and dispatches a single event from the stream, if available.

Note

Unlike pop(), this function does not wait for an event to become available.

Returns: The event that was popped and dispatched, or nullptr if no event was available.

inline void pump(): Dispatches and pops all available events from the stream.

inline ObjectPtr<ISubscription> createSubscriptionToPop(IEventListener *listener, Order order = kDefaultOrder, const char *subscriptionName = nullptr)

Subscribe to receive notification when event stream is popped.

See also

pump() pop() tryPop()

Note

Adding or removing a subscription from IEventListener::onEvent() is perfectly valid. The newly added subscription will not be called until the next event.

Warning

Recursively pushing and/or popping events from within IEventListener::onEvent() is not recommended and can lead to undefined behavior.

Parameters

listener – The listener to subscribe. IEventListener::onEvent() will be called for each popped event. If an event listener calls IEvent::consume() on the given event, propagation of the event will stop and no more event listeners will receive the event.
order – An optional value used to specify the order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.
subscriptionName – An optional name for the subscription for debugging purposes. Names do not need to be unique. If nullptr, an internal name will be determined.

Returns

A ISubscription pointer. The subscription is valid as long as the ISubscription pointer is referenced. Alternately, the IEventListener can be unsubscribed by calling ISubscription::unsubscribe().

inline ObjectPtr<ISubscription> createSubscriptionToPopByType(EventType eventType, IEventListener *listener, Order order = kDefaultOrder, const char *subscriptionName = nullptr)

Subscribe to receive notification when event stream is popped.

See also

pump() pop() tryPop()

Note

Adding or removing a subscription from IEventListener::onEvent() is perfectly valid. The newly added subscription will not be called until the next event.

Warning

Recursively pushing and/or popping events from within IEventListener::onEvent() is not recommended and can lead to undefined behavior.

Parameters

listener – The listener to subscribe. IEventListener::onEvent() will be called for each popped event. If an event listener calls IEvent::consume() on the given event, propagation of the event will stop and no more event listeners will receive the event.
order – An optional value used to specify the order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.
subscriptionName – An optional name for the subscription for debugging purposes. Names do not need to be unique. If nullptr, an internal name will be determined.
eventType – A specific event to listen for.

Returns

A ISubscription pointer. The subscription is valid as long as the ISubscription pointer is referenced. Alternately, the IEventListener can be unsubscribed by calling ISubscription::unsubscribe().

virtual ISubscription *createSubscriptionToPopPtr(IEventListener *listener, Order order = kDefaultOrder, const char *subscriptionName = nullptr) = 0

Subscribe to receive notification when event stream is popped.

See also

pump() pop() tryPop()

Note

Adding or removing a subscription from IEventListener::onEvent() is perfectly valid. The newly added subscription will not be called until the next event.

Warning

Recursively pushing and/or popping events from within IEventListener::onEvent() is not recommended and can lead to undefined behavior.

Parameters

listener – The listener to subscribe. IEventListener::onEvent() will be called for each popped event. If an event listener calls IEvent::consume() on the given event, propagation of the event will stop and no more event listeners will receive the event.
order – An optional value used to specify the order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.
subscriptionName – An optional name for the subscription for debugging purposes. Names do not need to be unique. If nullptr, an internal name will be determined.

Returns

A ISubscription pointer. The subscription is valid as long as the ISubscription pointer is referenced. Alternately, the IEventListener can be unsubscribed by calling ISubscription::unsubscribe().

virtual ISubscription *createSubscriptionToPopByTypePtr(EventType eventType, IEventListener *listener, Order order = kDefaultOrder, const char *subscriptionName = nullptr) = 0

Subscribe to receive notification when event stream is popped.

See also

pump() pop() tryPop()

Note

Adding or removing a subscription from IEventListener::onEvent() is perfectly valid. The newly added subscription will not be called until the next event.

Warning

Recursively pushing and/or popping events from within IEventListener::onEvent() is not recommended and can lead to undefined behavior.

Parameters

listener – The listener to subscribe. IEventListener::onEvent() will be called for each popped event. If an event listener calls IEvent::consume() on the given event, propagation of the event will stop and no more event listeners will receive the event.
order – An optional value used to specify the order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.
subscriptionName – An optional name for the subscription for debugging purposes. Names do not need to be unique. If nullptr, an internal name will be determined.
eventType – A specific event to listen for.

Returns

A ISubscription pointer. The subscription is valid as long as the ISubscription pointer is referenced. Alternately, the IEventListener can be unsubscribed by calling ISubscription::unsubscribe().

inline ObjectPtr<ISubscription> createSubscriptionToPush(IEventListener *listener, Order order = kDefaultOrder, const char *subscriptionName = nullptr)

Subscribe to receive notification when an event is pushed into the event stream.

See also

push() pushBlocked()

Note

Adding or removing a subscription from IEventListener::onEvent() is perfectly valid. The newly added subscription will not be called until the next event.

Warning

Recursively pushing and/or popping events from within IEventListener::onEvent() is not recommended and can lead to undefined behavior.

Parameters

listener – The listener to subscribe. IEventListener::onEvent() will be called for each pushed event. The IEvent::consume() function has no effect for notifications of push events.
order – An optional value used to specify the order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.
subscriptionName – An optional name for the subscription for debugging purposes. Names do not need to be unique. If nullptr, an internal name will be determined.

Returns

A ISubscription pointer. The subscription is valid as long as the ISubscription pointer is referenced. Alternately, the IEventListener can be unsubscribed by calling ISubscription::unsubscribe().

inline ObjectPtr<ISubscription> createSubscriptionToPushByType(EventType eventType, IEventListener *listener, Order order = kDefaultOrder, const char *subscriptionName = nullptr)

Subscribe to receive notification when an event is pushed into the event stream.

See also

push() pushBlocked()

Note

Adding or removing a subscription from IEventListener::onEvent() is perfectly valid. The newly added subscription will not be called until the next event.

Warning

Recursively pushing and/or popping events from within IEventListener::onEvent() is not recommended and can lead to undefined behavior.

Parameters

listener – The listener to subscribe. IEventListener::onEvent() will be called for each pushed event. The IEvent::consume() function has no effect for notifications of push events.
order – An optional value used to specify the order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.
subscriptionName – An optional name for the subscription for debugging purposes. Names do not need to be unique. If nullptr, an internal name will be determined.
eventType – A specific event to listen for.

Returns

A ISubscription pointer. The subscription is valid as long as the ISubscription pointer is referenced. Alternately, the IEventListener can be unsubscribed by calling ISubscription::unsubscribe().

virtual ISubscription *createSubscriptionToPushPtr(IEventListener *listener, Order order = kDefaultOrder, const char *subscriptionName = nullptr) = 0

Subscribe to receive notification when an event is pushed into the event stream.

See also

push() pushBlocked()

Note

Adding or removing a subscription from IEventListener::onEvent() is perfectly valid. The newly added subscription will not be called until the next event.

Warning

Recursively pushing and/or popping events from within IEventListener::onEvent() is not recommended and can lead to undefined behavior.

Parameters

listener – The listener to subscribe. IEventListener::onEvent() will be called for each pushed event. The IEvent::consume() function has no effect for notifications of push events.
order – An optional value used to specify the order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.
subscriptionName – An optional name for the subscription for debugging purposes. Names do not need to be unique. If nullptr, an internal name will be determined.

Returns

A ISubscription pointer. The subscription is valid as long as the ISubscription pointer is referenced. Alternately, the IEventListener can be unsubscribed by calling ISubscription::unsubscribe().

virtual ISubscription *createSubscriptionToPushByTypePtr(EventType eventType, IEventListener *listener, Order order = kDefaultOrder, const char *subscriptionName = nullptr) = 0

Subscribe to receive notification when an event is pushed into the event stream.

See also

push() pushBlocked()

Note

Adding or removing a subscription from IEventListener::onEvent() is perfectly valid. The newly added subscription will not be called until the next event.

Warning

Recursively pushing and/or popping events from within IEventListener::onEvent() is not recommended and can lead to undefined behavior.

Parameters

listener – The listener to subscribe. IEventListener::onEvent() will be called for each pushed event. The IEvent::consume() function has no effect for notifications of push events.
order – An optional value used to specify the order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.
subscriptionName – An optional name for the subscription for debugging purposes. Names do not need to be unique. If nullptr, an internal name will be determined.
eventType – A specific event to listen for.

Returns

A ISubscription pointer. The subscription is valid as long as the ISubscription pointer is referenced. Alternately, the IEventListener can be unsubscribed by calling ISubscription::unsubscribe().

virtual bool setSubscriptionToPopOrder(const char *subscriptionName, Order order) = 0

Sets the notification order for named subscriptions.

Note

If multiple subscriptions exist with the same name, all are updated.

Parameters

subscriptionName – the name previously assigned when the subscription was created.
order – The new order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.

Returns

true if the subscription was found and updated; false otherwise.

virtual bool setSubscriptionToPushOrder(const char *subscriptionName, Order order) = 0

Sets the notification order for named subscriptions.

Note

If multiple subscriptions exist with the same name, all are updated.

Parameters

subscriptionName – the name previously assigned when the subscription was created.
order – The new order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.

Returns

true if the subscription was found and updated; false otherwise.

virtual bool getSubscriptionToPopOrder(const char *subscriptionName, Order *order) = 0

Retrieves the notification order for a named subscription.

Parameters

subscriptionName – the name previously assigned when the subscription was created.
order – Must be a valid pointer that will receive the current order tier.

Returns

true if the subscription was found; false if the subscription was not found or order is nullptr.

virtual bool getSubscriptionToPushOrder(const char *subscriptionName, Order *order) = 0

Sets the notification order for named subscriptions.

Note

If multiple subscriptions exist with the same name, all are updated.

Parameters

subscriptionName – the name previously assigned when the subscription was created.
order – The new order tier. Lower order tiers will be notified first. Multiple IEventListener objects at the same order tier are notified in an undefined order.

Returns

true if the subscription was found and updated; false otherwise.

virtual const char *getName() const noexcept = 0

Returns the name of the IEventStream.

Note

If a name was not given when IEvents::createEventStream() was called, a name is generated based on the function that called IEvents::createEventStream().

Returns: The name of the IEventStream.

template<typename ...ValuesT> inline IEvent *createEventPtr(EventType eventType, SenderId sender, ValuesT&&... values)

Create new event of certain type.

Parameters

eventType – The type of event to create.
sender – The sender of the event, or carb::events::kGlobalSenderId.
values – Key/value pairs as passed to IEvent::setValues().

Returns

A pointer to a newly created event.

inline void pushWithSender(EventType eventType, SenderId sender)

Helper function that combines createEvent() with push().

Parameters

eventType – The type of event to create.
sender – The sender of the event, or carb::events::kGlobalSenderId.

template<typename ...ValuesT> inline void pushWithSender(EventType eventType, SenderId sender, ValuesT&&... values)

Helper function that combines createEvent() with push().

Parameters

eventType – The type of event to create.
sender – The sender of the event, or carb::events::kGlobalSenderId.
values – Key/value pairs as passed to IEvent::setValues().

template<typename ...ValuesT> inline void push(EventType eventType, ValuesT&&... values)

Helper function that combines createEvent() with push().

Parameters

eventType – The type of event to create.
values – Key/value pairs as passed to IEvent::setValues().

inline void pushBlockedWithSender(EventType eventType, SenderId sender)

Helper function that combines createEvent() with pushBlocked().

Parameters

eventType – The type of event to create.
sender – The sender of the event, or carb::events::kGlobalSenderId.

template<typename ...ValuesT> inline void pushBlockedWithSender(EventType eventType, SenderId sender, ValuesT&&... values)

Helper function that combines createEvent() with pushBlocked().

Parameters

eventType – The type of event to create.
sender – The sender of the event, or carb::events::kGlobalSenderId.
values – Key/value pairs as passed to IEvent::setValues().

template<typename ...ValuesT> inline void pushBlocked(EventType eventType, ValuesT&&... values)

Helper function that combines createEvent() with pushBlocked().

Parameters

eventType – The type of event to create.
values – Key/value pairs as passed to IEvent::setValues().

template<typename ...ValuesT> inline void dispatch(EventType eventType, SenderId sender, ValuesT&&... values)

Helper function that combines createEvent() with dispatch().

Parameters

eventType – The type of event to create.
sender – The sender of the event, or carb::events::kGlobalSenderId.
values – Key/value pairs as passed to IEvent::setValues().

inline void dispatch(EventType eventType, SenderId sender)

Helper function that combines createEvent() with dispatch().

Parameters

eventType – The type of event to create.
sender – The sender of the event, or carb::events::kGlobalSenderId.

virtual size_t addRef() = 0

Atomically add one to the reference count.

Returns: The current reference count after one was added, though this value may change before read if other threads are also modifying the reference count. The return value is guaranteed to be non-zero.

virtual size_t release() = 0

Atomically subtracts one from the reference count.

If the result is zero, carb::deleteHandler() is called for this.

Returns: The current reference count after one was subtracted. If zero is returned, carb::deleteHandler() was called for this.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.