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.
static const EBusAddressPolicy AddressPolicy = EBusAddressPolicy::ById;
 
// Each event is received by a single handler (the game object).
static const EBusHandlerPolicy HandlerPolicy = EBusHandlerPolicy::Single;
 
// 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

using AZ::EBusTraits::BusIdType = NullBusId

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

using AZ::EBusTraits::EventQueueMutexType = NullMutex

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

using AZ::EBusTraits::MutexType = NullMutex

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:

• (Default) EBusEnvironmentStoragePolicy - EBus data is stored in the AZ::Environment. With this policy, a single EBus instance is shared across all modules (DLLs) that attach to the AZ::Environment. It also supports multiple EBus environments.
• EBusGlobalStoragePolicy - EBus data is stored in a global static variable. With this policy, each module (DLL) has its own instance of the EBus.
• EBusThreadLocalStoragePolicy - EBus data is stored in a thread_local static variable. With this policy, each thread has its own instance of the EBus.

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:

• Code/Framework/AzCore/AzCore/EBus/EBus.h