IEventStream1_3#

Fully qualified name: carb::events::IEventStream1_3

Defined in carb/events/IEvents.h

class IEventStream1_3 : public carb::events::IEventStream1_0#

Version 1.3 IEventStream.

Subclassed by carb::events::IEventStream1_5

Public Functions

virtual size_t getSubscriptionToPopCount() const = 0#

Returns the number of subscriptions.

Returns:

the number of subscriptions

virtual size_t getSubscriptionToPushCount() const = 0#

Returns the number of subscriptions.

Returns:

the number of subscriptions

virtual bool walkSubscriptionsToPop(
SubscriptionCallback callback,
void *userData,
) const = 0#

Calls a callback with all of the pop-side subscriptions.

The order is unspecified.

Warning

An internal lock is held while calling the callback. The callback must not call any other IEventStream functions or undefined behavior occurs.

Parameters:

  • callback – The callback to call with each subscription.

  • userData – An opaque pointer to pass to the callback.

Returns:

true if the callback was called for all subscriptions; false if the callback returned false to terminate iteration.

virtual bool walkSubscriptionsToPush(
SubscriptionCallback callback,
void *userData,
) const = 0#

Calls a callback with all of the push-side subscriptions.

The order is unspecified.

Warning

An internal lock is held while calling the callback. The callback must not call any other IEventStream functions or undefined behavior occurs.

Parameters:

  • callback – The callback to call with each subscription.

  • userData – An opaque pointer to pass to the callback.

Returns:

true if the callback was called for all subscriptions; false if the callback returned false to terminate iteration.

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

Create new event of certain type.

Parameters:
Returns:

A pointer to a newly created event.

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

Create new event of certain type.

Parameters:
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:
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.

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

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

Parameters:
inline void dispatch(EventType eventType, SenderId sender)#

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

Parameters:
virtual void push(IEvent *e) = 0#

Push event into the stream.

Parameters:

e – The event to push.

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().

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.

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().

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,
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 are notified in the order in which they subscribed.

  • 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,
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 are notified in the order in which they subscribed.

  • 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 ISubscription *createSubscriptionToPopPtr(
IEventListener *listener,
Order order,
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 are notified in the order in which they subscribed.

  • 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 ISubscription *createSubscriptionToPopByTypePtr(
EventType eventType,
IEventListener *listener,
Order order,
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 are notified in the order in which they subscribed.

  • 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,
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 are notified in the order in which they subscribed.

  • 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,
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 are notified in the order in which they subscribed.

  • 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 ISubscription *createSubscriptionToPushByTypePtr(
EventType eventType,
IEventListener *listener,
Order order,
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 are notified in the order in which they subscribed.

  • 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 ISubscription *createSubscriptionToPushPtr(
IEventListener *listener,
Order order,
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 are notified in the order in which they subscribed.

  • 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 bool setSubscriptionToPopOrder(
const char *subscriptionName,
Order order,
)#

Sets the notification order for named subscriptions (deprecated template version).

Deprecated:

Use setSubscriptionToPopOrder() with string_view instead

Parameters:

  • subscriptionName – the name previously assigned when the subscription was created.

  • order – The new order tier.

Returns:

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

inline bool setSubscriptionToPushOrder(
const char *subscriptionName,
Order order,
)#

Sets the notification order for named push subscriptions (deprecated template version).

Deprecated:

Use setSubscriptionToPushOrder() with string_view instead

Parameters:

  • subscriptionName – the name previously assigned when the subscription was created.

  • order – The new order tier.

Returns:

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

inline bool getSubscriptionToPopOrder(
const char *subscriptionName,
Order *order,
)#

Retrieves the notification order for a named subscription (deprecated template version).

Deprecated:

Use getSubscriptionToPopOrder() with string_view instead

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 otherwise.

inline bool getSubscriptionToPushOrder(
const char *subscriptionName,
Order *order,
)#

Retrieves the notification order for a named push subscription (deprecated template version).

Deprecated:

Use getSubscriptionToPushOrder() with string_view instead

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 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.

inline void pushWithSender(EventType eventType, SenderId sender)#

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

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

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

Parameters:
inline void pushBlockedWithSender(
EventType eventType,
SenderId sender,
)#

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

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

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

Parameters:
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.