IMessageQueue#

Fully qualified name: carb::eventdispatcher::IMessageQueue

Defined in carb/eventdispatcher/IMessageQueue.h

class IMessageQueue : public carb::IObject#

An instance of a message queue.

A message queue is a one-way weak coupling device that allows “messages” to be sent from a variety of senders and received by a specific target. A message queue has a push-side and a pop-side. The push-side can be accessed by any thread. The pop-side can only be accessed by the owning thread, or a group of threads if no owning thread is specified. Violations of this policy are enforced by omni::unexpected return values containing an error code.

Can be created with IMessageQueueFactory::createMessageQueue(), or an existing message queue can be found with IMessageQueueFactory::getMessageQueue().

Public Types

using ExpectedType = omni::expected<void, omni::core::Result>#

The omni::expected type returned by IMessageQueue functions.

using UnexpectedType = omni::unexpected<omni::core::Result>#

The omni::unexpected type representing an error by IMessageQueue functions.

Public Functions

virtual RStringKey getName() const = 0#

Retrieves the unique name of this message queue.

Thread Safety

May be called by any thread at any time without requiring synchronization.

Returns:

The unique name of this message queue.

virtual thread::ThreadId getOwningThread() const = 0#

Retrieves the thread ID of the thread which owns this message queue.

Thread Safety

May be called by any thread at any time without requiring synchronization.

Returns:

The thread ID of the thread which owns this message queue, or zero if no one thread owns this message queue.

virtual bool hasMessages() const = 0#

Returns whether this message queue has pending messages.

Thread Safety

Though this is a pop-side function, it can be called by any thread. However, the value may be stale by the time it is read unless called by the owning thread in a single-owner-thread situation.

Returns:

true if the message queue appears to have messages, false otherwise.

template<class Func>
ExpectedType peek(Func &&func) const#

Inspects the message at the front of the queue, if any, without removing it.

The message is not removed when this function is called. Call pop() to process and remove the message.

Errors

Accessible via the omni::unexpected return value.

Warning

This function only works in a single-owner-thread situation. Otherwise the function will always return omni::unexpected with omni::core::kResultNotSupported.

Parameters:

func – An invocable that is called as void(const Event&).

Returns:

a omni::expected with void if func was called with the first item in the queue, otherwise a omni::unexpected with an above-listed error.

template<class Func>
ExpectedType pop(Func &&func)#

Pops the message at the front of the queue and calls a function with the message.

The message is removed from the queue atomically before processing. In a single-owner-thread situation, this function must be called within the context of the owning thread.

Errors

Accessible via the omni::unexpected return value.

Parameters:

func – An invocable that is called as void(const Event&).

Returns:

a omni::expected with void if func was called with the popped first item in the queue, otherwise a omni::unexpected with an above-listed error.

omni::expected<void, omni::core::Result> awaitMessage() const#

Blocks the current thread or task until a message is available in the queue.

Note, if carb::tasking::ITasking is available and started when this is called, this function will wait in a task-safe manner.

Thread Safety

Though this is a pop-side function, it can be called by any thread.

Errors

Accessible via the omni::unexpected return value.

Returns:

a omni::expected with void when a message becomes available, or a omni::unexpected with an above-listed error.

template<class Rep, class Period>
omni::expected<void, omni::core::Result> awaitMessageFor(
const std::chrono::duration<Rep, Period> &duration,
) const#

Blocks the current thread or task until a message is available in the queue, or a timeout duration expires.

Note, if carb::tasking::ITasking is available and started when this is called, this function will wait in a task-safe manner.

Thread Safety

Though this is a pop-side function, it can be called by any thread.

Errors

Accessible via the omni::unexpected return value.

Parameters:

duration – The time period to wait.

Returns:

a omni::expected with void when a message becomes available, or a omni::unexpected with an above-listed error.

template<class Clock, class Duration>
omni::expected<void, omni::core::Result> awaitMessageUntil(
const std::chrono::time_point<Clock, Duration> &when,
) const#

Blocks the current thread or task until a message is available in the queue, or a timeout time arrives.

Note, if carb::tasking::ITasking is available and started when this is called, this function will wait in a task-safe manner.

Thread Safety

Though this is a pop-side function, it can be called by any thread.

Errors

Accessible via the omni::unexpected return value.

Parameters:

when – The clock time to timeout at.

Returns:

a omni::expected with void when a message becomes available, or a omni::unexpected with an above-listed error.

ExpectedType stop()#

Stops the message queue before destruction.

This is a one-time, irreversible command to a message queue that the queue is no longer processing messages. It is not required to call this function before the last reference is removed and *this is destroyed.

When stop() returns it is guaranteed that:

Subsequent calls to this function have no effect.

Errors

Accessible via the omni::unexpected return value.

Warning

It is undefined behavior to call this from within the invocable objects passed to pop() or peek(). Instead, it is recommended that the handlers for pop() or peek() set a flag that can be checked after the pop() or peek() returns which then calls stop().

Returns:

a omni::expected with void if the stop was successful, or a omni::unexpected with an above-listed error.

template<class ...Args>
ExpectedType pushAsync(
RString eventName,
Args&&... payload,
)#

Sends a message to the message queue recipient, without waiting.

This function can handle a series of immediate key/value pairs. In order to provide a variable number of key/value pairs, use pushAsyncIter().

Thread Safety

Safe to call concurrently. Messages pushed by a given thread will always be received in the same order as pushed (first-in-first-out). Messages pushed simultaneously in parallel by different threads are serialized in the queue and may be interlaced.

Errors

Accessible via the omni::unexpected return value.

Parameters:

  • eventName – The name of the event for the message.

  • payload – Zero or more key/value pairs that are used as the payload for the message and may be queried by the message queue owner(s) when the message is popped from the queue. Each argument must be of type std::pair<RStringKey, T> where the first parameter is the key and the second is the value. The value must be a type understood by a variant::Translator specialization. Each key must be unique, otherwise it is not defined which non-unique value is obtained when the key is queried.

Returns:

a omni::expected with void if the stop was successful, or a omni::unexpected with an above-listed error. 

mq->pushAsync(RString("My event"), std::make_pair(RStringKey("param1"), 7));

template<class InIter>
ExpectedType pushAsyncIter(
RString eventName,
InIter begin,
InIter end,
)#

Sends a message to the message queue recipient, without waiting.

Thread Safety

Safe to call concurrently. Messages by all threads are serialized in the queue and received by the owner(s) in order pushed.

Errors

Accessible via the omni::unexpected return value.

Template Parameters:

InIter – An InputIterator that is forward-iterable and resolves to a NamedVariant when dereferenced. The entries are used as the message payload and may be queried by observers. Each key must be unique, otherwise it is not defined which non-unique value is obtained when the key is queried.

Parameters:

  • eventName – The name of the event for the message.

  • begin – An InputIterator that, with end, forms the range [begin, end) of the message key/value pairs.

  • end – An InputIterator that, with begin, forms the range [begin, end) of the message key/value pairs.

Returns:

a omni::expected with void if the stop was successful, or a omni::unexpected with an above-listed error. 

std::vector fields{ NamedVariant{ RStringKey("param1"), Variant(7) } };
mq->pushAsyncIter(RString("My event"), fields.begin(), fields.end());

template<class R>
inline ExpectedType pushAsyncRange(
RString eventName,
R &&range,
)#

Sends a message to the message queue recipient, without waiting.

Thread Safety

Safe to call concurrently. Messages by all threads are serialized in the queue and received by the owner(s) in order pushed.

Errors

Accessible via the omni::unexpected return value.

Template Parameters:

R – A range type. Since this implementation is for pre-C++20 and C++20 ranges are not available, this is an approximation: this type must work with std::begin() and std::end() to produce an iterator type that conforms to InputIterator. The iterator must resolve to a std::pair<RStringKey, T> when dereferenced, where the first parameter is the key and the second parameter is the value and must be a type understood by a variant::Translator specialization. Each key must be unique, otherwise it is not defined which non-unique value is obtained when the key is queried.

Parameters:

  • eventName – The name of the event for the message.

  • range – The range to use as message parameters. See explanation of the R type above.

Returns:

a omni::expected with void if the stop was successful, or a omni::unexpected with an above-listed error. 

mq->pushAsyncRange(RString("My event"), { { RStringKey("param1"), 7 } });

template<class ...Args>
ExpectedType pushAndWait(
RString eventName,
Args&&... payload,
)#

Sends a message to the message queue recipient and blocks the current thread or task until it has been popped and processed.

This function can handle a series of immediate key/value pairs. In order to provide a variable number of key/value pairs, use pushAndWaitIter(). If carb::tasking::ITasking is available and started when this is called, this function will wait in a task-safe manner.

Thread Safety

Safe to call concurrently. Messages by all threads are serialized in the queue and received by the owner(s) in order pushed.

Errors

Accessible via the omni::unexpected return value.

Warning

If this is called by the owning thread, the message will be pushed asynchronously, but the function will return omni::unexpected with omni::core::kResultWouldBlock.

Parameters:

  • eventName – The name of the event for the message.

  • payload – Zero or more key/value pairs that are used as the payload for the message and may be queried by the message queue owner(s) when the message is popped from the queue. Each argument must be of type std::pair<RStringKey, T> where the first parameter is the key and the second is the value. The value must be a type understood by a variant::Translator specialization. Each key must be unique, otherwise it is not defined which non-unique value is obtained when the key is queried.

Returns:

a omni::expected with void when the message has been processed, or a omni::unexpected with an above-listed error. 

mq->pushAndWait(RString("My event"), std::make_pair(RStringKey("param1"), 7));

template<class R>
inline ExpectedType pushAndWaitRange(
RString eventName,
R &&range,
)#

Sends a message to the message queue recipient and blocks the current thread or task until it has been popped and processed.

If carb::tasking::ITasking is available and started when this is called, this function will wait in a task-safe manner.

Thread Safety

Safe to call concurrently. Messages by all threads are serialized in the queue and received by the owner(s) in order pushed.

Errors

Accessible via the omni::unexpected return value.

Warning

If this is called by the owning thread, the message will be pushed asynchronously, but the function will return omni::unexpected with omni::core::kResultWouldBlock.

Template Parameters:

R – A range type. Since this implementation is for pre-C++20 and C++20 ranges are not available, this is an approximation: this type must work with std::begin() and std::end() to produce an iterator type that conforms to InputIterator. The iterator must resolve to a std::pair<RStringKey, T> when dereferenced, where the first parameter is the key and the second parameter is the value and must be a type understood by a variant::Translator specialization. Each key must be unique, otherwise it is not defined which non-unique value is obtained when the key is queried.

Parameters:

  • eventName – The name of the event for the message.

  • range – The range to use as message parameters. See explanation of the R type above.

Returns:

a omni::expected with void when the message has been processed, or a omni::unexpected with an above-listed error. 

mq->pushAndWaitRange(RString("My event"), { std::make_pair(RStringKey("param1"), 7) });

template<class InIter>
ExpectedType pushAndWaitIter(
RString eventName,
InIter begin,
InIter end,
)#

Sends a message to the message queue recipient and blocks the current thread or task until it has been popped and processed.

If carb::tasking::ITasking is available and started when this is called, this function will wait in a task-safe manner.

Thread Safety

Safe to call concurrently. Messages by all threads are serialized in the queue and received by the owner(s) in order pushed.

Errors

Accessible via the omni::unexpected return value.

Warning

If this is called by the owning thread, the message will be pushed asynchronously, but the function will return omni::unexpected with omni::core::kResultWouldBlock.

Template Parameters:

InIter – An InputIterator that is forward-iterable and resolves to a NamedVariant when dereferenced. The entries are used as the message payload and may be queried by observers. Each key must be unique, otherwise it is not defined which non-unique value is obtained when the key is queried.

Parameters:

  • eventName – The name of the event for the message.

  • begin – An InputIterator that, with end, forms the range [begin, end) of the message key/value pairs.

  • end – An InputIterator that, with begin, forms the range [begin, end) of the message key/value pairs.

Returns:

a omni::expected with void when the message has been processed, or a omni::unexpected with an above-listed error. 

std::vector fields{ NamedVariant{ RStringKey("param1"), Variant(7) } };
mq->pushAndWaitIter(RString("My event"), fields.begin(), fields.end());

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.

On this page