Open 3D Engine AzCore API Reference  22.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
Public Types | Static Public Attributes | Protected Member Functions | List of all members
AZ::EBusTraits Struct Reference

#include <EBus.h>

Inherited by AZ::AssetTypeInfo, AZ::BehaviorContextEvents, AZ::BehaviorObjectSignalsInterface, AZ::ComponentApplicationRequestsEBusTraits, AZ::ComponentBus, AZ::ComponentDescriptorBusTraits, AZ::Data::AssetCatalogRequests, AZ::Data::AssetEvents, AZ::Data::AssetLoadEvents, AZ::Data::AssetManagerEvents, AZ::Data::AssetManagerNotifications, AZ::DataOverlayInstanceMsgs, AZ::DataOverlayProviderMsgs, AZ::DataPatchNotifications, AZ::Debug::ProfilerNotifications, AZ::Debug::TraceMessageEvents, AZ::EBusSharedDispatchTraits< BusType >, AZ::EntitySystemEvents, AZ::IEventSchedulerRequests, AZ::ILoggerRequests, AZ::IO::Compression, AZ::ITimeRequests, AZ::JobManagerEvents, AZ::ModuleManagerRequests, AZ::NativeUI::NativeUIEBusTraits, AZ::ScriptPropertyWatcherInterface, AZ::ScriptSystemRequests, AZ::SliceAssetSerializationNotifications, AZ::SliceEvents, AZ::SliceInstanceEvents, AZ::SystemTickEvents, AZ::TickEvents, AZ::TickRequests, AZ::UserSettingsComponentRequests, AZ::UserSettingsFileLocator, AZ::UserSettingsMessages, AZ::UserSettingsNotifications, AZ::UserSettingsOwnerRequests, and AZStd::ThreadEvents.

Public Types

using AllocatorType = AZ::Internal::EBusEnvironmentAllocator
 
using BusIdType = NullBusId
 
using BusIdOrderCompare = NullBusIdCompare
 
using BusHandlerOrderCompare = BusHandlerCompareDefault
 
using MutexType = NullMutex
 
using EventQueueMutexType = NullMutex
 
template<class Bus >
using ConnectionPolicy = EBusConnectionPolicy< Bus >
 
template<class Context >
using StoragePolicy = EBusEnvironmentStoragePolicy< Context >
 
template<class Bus >
using RouterPolicy = EBusRouterPolicy< Bus >
 
using EventProcessingPolicy = EBusEventProcessingPolicy
 
template<typename DispatchMutex , bool IsLocklessDispatch>
using DispatchLockGuard = AZStd::conditional_t< IsLocklessDispatch, AZ::Internal::NullLockGuard< DispatchMutex >, AZStd::scoped_lock< DispatchMutex > >
 
template<typename ContextMutex >
using ConnectLockGuard = AZStd::conditional_t< AZStd::is_same_v< ContextMutex, AZ::NullMutex >, AZ::Internal::NullLockGuard< ContextMutex >, AZStd::unique_lock< ContextMutex > >
 
template<typename ContextMutex >
using BindLockGuard = AZStd::scoped_lock< ContextMutex >
 
template<typename ContextMutex >
using CallstackTrackerLockGuard = AZStd::conditional_t< AZStd::is_same_v< ContextMutex, AZ::NullMutex >, AZ::Internal::NullLockGuard< ContextMutex >, AZStd::unique_lock< ContextMutex > >
 

Static Public Attributes

static constexpr EBusHandlerPolicy HandlerPolicy = EBusHandlerPolicy::Multiple
 
static constexpr EBusAddressPolicy AddressPolicy = EBusAddressPolicy::Single
 
static constexpr bool EnableEventQueue = false
 
static constexpr bool EventQueueingActiveByDefault = true
 
static constexpr bool EnableQueuedReferences = false
 
static constexpr bool LocklessDispatch = false
 

Protected Member Functions

 ~EBusTraits ()=default
 

Detailed Description

EBusTraits are properties that you use to configure an EBus.

The key EBusTraits to understand are AddressPolicy, which defines how many addresses the EBus contains, HandlerPolicy, which describes how many handlers can connect to each address, and BusIdType, which is the type of ID that is used to address the EBus if addresses are used.

For example, if you want an EBus that makes requests of game objects that each have a unique integer identifier, then define an EBus with the following traits:

// The EBus has multiple addresses and each event is addressed to a
// specific ID (the game object's ID), which corresponds to an address
// on the bus.
// Each event is received by a single handler (the game object).
// Events are addressed by this type of ID (the game object's ID).
using BusIdType = int;

For more information about EBuses, see EBus in this guide and Event Bus in the Open 3D Engine Developer Guide.

Member Typedef Documentation

◆ AllocatorType

using AZ::EBusTraits::AllocatorType = AZ::Internal::EBusEnvironmentAllocator

Allocator used by the EBus. The default setting is Internal EBusEnvironmentAllocator EBus code stores their Context instances in static memory Therfore the configured allocator must last as long as the EBus in a module

◆ BindLockGuard

template<typename ContextMutex >
using AZ::EBusTraits::BindLockGuard = AZStd::scoped_lock<ContextMutex>

Template Lock Guard class to use for EBus bind calls. By default it will use a scoped_lock. This can be overridden to provide a different locking policy with custom EBus MutexType settings.

◆ BusHandlerOrderCompare

using AZ::EBusTraits::BusHandlerOrderCompare = BusHandlerCompareDefault

Sorting function for EBus event handlers. Used only when the HandlerPolicy is AZ::EBusHandlerPolicy::MultipleAndOrdered. This function determines the order in which handlers at an address receive an event.

By default, the function requires the handler to implement the following comparison function.

// Returns whether 'this' should precede 'other'.
bool Compare(const Interface* other) const;

◆ BusIdOrderCompare

using AZ::EBusTraits::BusIdOrderCompare = NullBusIdCompare

Sorting function for EBus address IDs. Used only when the AddressPolicy is AZ::EBusAddressPolicy::ByIdAndOrdered. If an event is dispatched without an ID, this function determines the order in which each address receives the event.

The following example shows a sorting function that meets these requirements.

using BusIdOrderCompare = AZStd::less<BusIdType>; // Lesser IDs first.

◆ BusIdType

The type of ID that is used to address the EBus. Used only when the AddressPolicy is AZ::EBusAddressPolicy::ById or AZ::EBusAddressPolicy::ByIdAndOrdered. The type must support AZStd::hash<ID> and bool operator==(const ID&, const ID&).

◆ CallstackTrackerLockGuard

template<typename ContextMutex >
using AZ::EBusTraits::CallstackTrackerLockGuard = AZStd::conditional_t< AZStd::is_same_v<ContextMutex, AZ::NullMutex>, AZ::Internal::NullLockGuard<ContextMutex>, AZStd::unique_lock<ContextMutex> >

Template Lock Guard class to use for EBus callstack tracking. By default it will use a unique_lock if the ContextMutex is anything but a NullMutex. This can be overridden to provide a different locking policy with custom EBus MutexType settings.

◆ ConnectionPolicy

template<class Bus >
using AZ::EBusTraits::ConnectionPolicy = EBusConnectionPolicy<Bus>

Enables custom logic to run when a handler connects or disconnects from the EBus. For example, you can make a handler execute an event immediately upon connecting to the EBus by modifying the EBusConnectionPolicy of the bus. By default, no extra logic is run.

◆ ConnectLockGuard

template<typename ContextMutex >
using AZ::EBusTraits::ConnectLockGuard = AZStd::conditional_t< AZStd::is_same_v<ContextMutex, AZ::NullMutex>, AZ::Internal::NullLockGuard<ContextMutex>, AZStd::unique_lock<ContextMutex> >

Template Lock Guard class to use during connection / disconnection. By default it will use a unique_lock if the ContextMutex is anything but a NullMutex. This can be overridden to provide a different locking policy with custom EBus MutexType settings. Also, some specialized policies execute handler methods which can cause unnecessary delays holding the context mutex, such as performing blocking waits. These methods must unlock the context mutex before doing so to prevent deadlocks, especially when the wait is for an event in another thread which is trying to connect to the same bus before it can complete.

◆ DispatchLockGuard

template<typename DispatchMutex , bool IsLocklessDispatch>
using AZ::EBusTraits::DispatchLockGuard = AZStd::conditional_t<IsLocklessDispatch, AZ::Internal::NullLockGuard<DispatchMutex>, AZStd::scoped_lock<DispatchMutex> >

The following Lock Guard classes are exposed so that it's possible to redefine them with custom lock/unlock functionality when using custom types for the EBus MutexType. Template Lock Guard class to use during event dispatches. By default it will use a scoped_lock, but IsLocklessDispatch=true will cause it to use a NullLockGuard. The IsLocklessDispatch bool is there to defer evaluation of the LocklessDispatch constant Otherwise the value above in EBusTraits.h is always used and not the value that the derived trait class sets.

◆ EventQueueMutexType

Locking primitive that is used when adding and removing events from the queue. Not used for connection or event execution. Used only when EnableEventQueue is true. If left unspecified, it will use the MutexType.

◆ MutexType

Locking primitive that is used when connecting handlers to the EBus or executing events. By default, all access is assumed to be single threaded and no locking occurs. For multithreaded access, specify a mutex of the following type.

  • For simple multithreaded cases, use AZStd::mutex.
  • For multithreaded cases where an event handler sends a new event on the same bus or connects/disconnects while handling an event on the same bus, use AZStd::recursive_mutex.
  • For specialized multithreading cases, such as allowing events to execute in parallel with each other but not with connects / disconnects, use custom mutex types along with custom LockGuard policies to control the specific locking requirements for each mutex use case (connection, dispatch, binding, callstack tracking).

◆ RouterPolicy

template<class Bus >
using AZ::EBusTraits::RouterPolicy = EBusRouterPolicy<Bus>

Controls the flow of EBus events. Enables an event to be forwarded, and possibly stopped, before reaching the normal event handlers. Use cases for routing include tracing, debugging, and versioning an EBus. The default EBusRouterPolicy forwards the event to each connected EBusRouterNode before sending the event to the normal handlers. Each node can stop the event or let it continue.

◆ StoragePolicy

template<class Context >
using AZ::EBusTraits::StoragePolicy = EBusEnvironmentStoragePolicy<Context>

Specifies where EBus data is stored. This drives how many instances of this EBus exist at runtime. Available storage policies include the following:

Note
Make sure you carefully consider the implication of switching this policy. If your code use EBusEnvironments and your storage policy is not complaint in the best case you will cause contention and unintended communication across environments, separation is a goal of environments. In the worst case when you have listeners, you can receive messages when you environment is NOT active, potentially causing all kinds of havoc especially if you execute environments in parallel.

Constructor & Destructor Documentation

◆ ~EBusTraits()

AZ::EBusTraits::~EBusTraits ( )
protecteddefault

Note - the destructor is intentionally not virtual to avoid adding vtable overhead to every EBusTraits derived class.

Member Data Documentation

◆ AddressPolicy

constexpr EBusAddressPolicy AZ::EBusTraits::AddressPolicy = EBusAddressPolicy::Single
staticconstexpr

Defines how many addresses exist on the EBus. For available settings, see AZ::EBusAddressPolicy. By default, an EBus uses a single address.

◆ EnableEventQueue

constexpr bool AZ::EBusTraits::EnableEventQueue = false
staticconstexpr

Specifies whether the EBus supports an event queue. You can use the event queue to execute events at a later time. To execute the queued events, you must call <BusName>::ExecuteQueuedEvents(). By default, the event queue is disabled.

◆ EnableQueuedReferences

constexpr bool AZ::EBusTraits::EnableQueuedReferences = false
staticconstexpr

Specifies whether the EBus supports queueing functions which take reference arguments. This means that the sender is responsible for the lifetime of the arguments (they should be static or class members or otherwise persistently stored). You should only use this if you know that the data being passed as arguments will outlive the dispatch of the queued event.

◆ EventQueueingActiveByDefault

constexpr bool AZ::EBusTraits::EventQueueingActiveByDefault = true
staticconstexpr

Specifies whether the bus should accept queued messages by default or not. If set to false, Bus::AllowFunctionQueuing(true) must be called before events are accepted. Used only when EnableEventQueue is true.

◆ HandlerPolicy

constexpr EBusHandlerPolicy AZ::EBusTraits::HandlerPolicy = EBusHandlerPolicy::Multiple
staticconstexpr

Defines how many handlers can connect to an address on the EBus and the order in which handlers at each address receive events. For available settings, see AZ::EBusHandlerPolicy. By default, an EBus supports any number of handlers.

◆ LocklessDispatch

constexpr bool AZ::EBusTraits::LocklessDispatch = false
staticconstexpr

Determines whether the bus will lock during dispatch On buses where handlers are attached at startup and removed at shutdown, or where connect/disconnect are not done from within handlers, this is safe to do. By default, the standard policy is used, which locks around all dispatches


The documentation for this struct was generated from the following file:
AZStd::less
Definition: TypeInfo.h:31
AZ::EBusAddressPolicy
EBusAddressPolicy
Definition: Policies.h:29
AZ::EBusTraits::BusIdType
NullBusId BusIdType
Definition: EBus.h:113
AZ::EBusHandlerPolicy
EBusHandlerPolicy
Definition: Policies.h:63
AZ::EBusHandlerPolicy::Single
@ Single
AZ::EBusTraits::HandlerPolicy
static constexpr EBusHandlerPolicy HandlerPolicy
Definition: EBus.h:97
AZ::EBusAddressPolicy::ById
@ ById
AZ::EBusTraits::AddressPolicy
static constexpr EBusAddressPolicy AddressPolicy
Definition: EBus.h:104
AZ::EBusTraits::BusIdOrderCompare
NullBusIdCompare BusIdOrderCompare
Definition: EBus.h:126