IMessageQueueFactory

Fully qualified name: carb::eventdispatcher::IMessageQueueFactory

Defined in carb/eventdispatcher/IMessageQueue.h

struct IMessageQueueFactory

The interface that functions as a message queue factory.

Public Functions

omni::expected<std::pair<IMessageQueuePtr, bool>, omni::core::Result> createMessageQueue(

RStringKey name,

const MessageQueueParams &params,

)

Creates a message queue with the given name and parameters, or returns an existing message queue with the given name.

Thread Safety

Safe to call while any thread is performing any operation against IMessageQueueFactory.

Errors

Accessible via the omni::unexpected return value.

• omni::core::kResultOutOfMemory - A new message queue could not be created.

• omni::core::kResultInvalidArgument - The sizeOf field of params is invalid, or name is empty.

Parameters:

• name – The unique name of the message queue. If the name already exists, the message queue will not be created but the previously-created message queue will be returned (params will be ignored). Since names must be unique, a scheme such as reverse-DNS is recommended. An empty name will create an anonymous message queue that will not be tracked in the internal lookup table and will be destroyed when all references to it expire.

• params – The parameters to use when creating the message queue. These are ignored if a message queue already exists with name.

Return values:

• std::pair<IMessageQueuePtr, bool> – A successful return produces a std::pair with first being a non-empty IMessageQueuePtr object, and second as a bool that is true if the message queue was newly created based on params, or false if the message queue previously existed.

• omni::core::Result – An error return produces a omni::unexpected containing an error code corresponding to the above list.

IMessageQueuePtr getMessageQueue(RStringKey name)

Retrieves a message queue with the given name.

If there is no message queue with the given name, an empty IMessageQueuePtr is returned.

Thread Safety

Safe to call while any thread is performing any operation against IMessageQueueFactory.

Parameters:

name – The unique name of the message queue, previously passed to createMessageQueue(). Empty names are not allowed.

Returns:

A IMessageQueuePtr containing the located message queue, or an empty object if no queue exists with the given name.

Public Members

bool (*addAlias)(RStringKey target, RStringKey alias)

Adds an alias that can be used to refer to a different message queue.

After a successful call, getMessageQueue called with alias will return the IMessageQueue instance created with name target. A message queue may have multiple aliases. The target message queue does not have to be created yet.

Thread Safety

Safe to call while any thread is performing any operation against IMessageQueueFactory.

Param target:

The target message queue name.

Param alias:

The alias name.

Retval true:

A new alias was created.

Retval false:

target and alias are the same, either target or alias are empty, target is already an alias, or alias is already used.

bool (*removeAlias)(RStringKey target, RStringKey alias)

Removes a previously-added message queue alias.

Removes an alias that was previously added with addAlias. Once removed, the alias is free to be used again as an alias for a different message queue or to create a new message queue.

Thread Safety

Safe to call while any thread is performing any operation against IMessageQueueFactory.

Param target:

The target message queue name.

Param alias:

The alias name previously added with addAlias.

Retval true:

The alias was removed successfully.

Retval false:

target and alias are the same, either target or alias are empty, target is not an alias target, or alias is not an alias of target.

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.