AZ::EBus< Interface, BusTraits > Class Template Reference

#include <EBus.h>

Inherits AZ::BusInternal::EBusImpl< AZ::EBus< Interface, Interface >, BusInternal::EBusImplTraits< Interface, Interface >, BusTraits::BusIdType >.

Public Types
using	ImplTraits = BusInternal::EBusImplTraits< Interface, BusTraits >
using	BaseImpl = BusInternal::EBusImpl< AZ::EBus< Interface, BusTraits >, BusInternal::EBusImplTraits< Interface, BusTraits >, typename BusTraits::BusIdType >
using	Traits = typename ImplTraits::Traits
using	ThisType = AZ::EBus< Interface, Traits >
using	AllocatorType = typename ImplTraits::AllocatorType
using	InterfaceType = typename ImplTraits::InterfaceType
using	Events = typename ImplTraits::Events
using	BusIdType = typename ImplTraits::BusIdType
using	BusIdOrderCompare = typename ImplTraits::BusIdOrderCompare
using	MutexType = typename ImplTraits::MutexType
using	BusesContainer = typename ImplTraits::BusesContainer
using	EventQueueMutexType = typename ImplTraits::EventQueueMutexType
using	BusPtr = typename ImplTraits::BusPtr
using	HandlerNode = typename ImplTraits::HandlerNode
using	QueuePolicy = EBusQueuePolicy< Traits::EnableEventQueue, ThisType, EventQueueMutexType >
using	ConnectionPolicy = typename Traits::template ConnectionPolicy< ThisType >
using	CallstackEntry = AZ::Internal::CallstackEntry< Interface, Traits >
using	Router = AZ::Internal::EBusRouter< ThisType >
using	NestedVersionRouter = AZ::Internal::EBusNestedVersionRouter< ThisType >
using	RouterPolicy = typename Traits::template RouterPolicy< ThisType >
using	RouterProcessingState = typename RouterPolicy::EventProcessingState
template<typename DispatchMutex >
using	DispatchLockGuardTemplate = typename ImplTraits::template DispatchLockGuard< DispatchMutex >
template<typename ContextMutexType >
using	ConnectLockGuardTemplate = typename ImplTraits::template ConnectLockGuard< ContextMutexType >
template<typename ContextMutexType >
using	BindLockGuardTemplate = typename ImplTraits::template BindLockGuard< ContextMutexType >
template<typename ContextMutexType >
using	CallstackTrackerLockGuardTemplate = typename ImplTraits::template CallstackTrackerLockGuard< ContextMutexType >
using	StoragePolicy = typename Traits::template StoragePolicy< Context >
using	ConnectLockGuard = typename Context::ConnectLockGuard

Static Public Member Functions
static size_t	GetTotalNumOfEventHandlers ()
static bool	HasHandlers ()
static bool	HasHandlers (const BusIdType &id)
static bool	HasHandlers (const BusPtr &ptr)
static const BusIdType *	GetCurrentBusId ()
static bool	HasReentrantEBusUseThisThread (const BusIdType *busId=GetCurrentBusId())
static const char *	GetName ()
static Context *	GetContext (bool trackCallstack=true)
static Context &	GetOrCreateContext (bool trackCallstack=true)
static bool	IsInDispatch (Context *context=GetContext(false))
static bool	IsInDispatchThisThread (Context *context=GetContext(false))

Static Public Attributes
static const bool	EnableEventQueue = ImplTraits::EnableEventQueue
static const bool	HasId = Traits::AddressPolicy != EBusAddressPolicy::Single

Detailed Description

template<class Interface, class BusTraits = Interface>
class AZ::EBus< Interface, BusTraits >

Event buses (EBuses) are a general-purpose communication system that Open 3D Engine uses to dispatch notifications and receive requests.

Template Parameters

Interface	A class whose virtual functions define the events dispatched or received by the EBus.
Traits	A class that inherits from EBusTraits and configures the EBus. This parameter may be left unspecified if the Interface class inherits from EBusTraits.

EBuses are configurable and support many different use cases. For more information about EBuses, see Event Bus and Components and EBuses: Best Practices in the Open 3D Engine Developer Guide.

How Components Use EBuses

Components commonly use EBuses in two ways: to dispatch events or to handle requests. A bus that dispatches events is a notification bus. A bus that receives requests is a request bus. Some components provide one type of bus, and some components provide both types. Some components do not provide an EBus at all. You use the EBus class for both EBus types, but you configure the EBuses differently. The following sections show how to set up and configure notification buses, event handlers, and request buses.

Notification Buses

Notification buses dispatch events. The events are received by handlers, which implement a function to handle the event. Handlers first connect to the bus. When the bus dispatches an event, the handler's function executes. This section shows how to set up a notification bus to dispatch an event and a handler to receive the event.

Setting up a Notification Bus

To set up a bus to dispatch events, do the following:

1. Define a class that inherits from EBusTraits. This class will be the interface for the EBus.
2. Override individual EBusTraits properties to define the behavior of your bus. Three EBusTraits that notification buses commonly override 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, notification buses often need to have multiple addresses, with the addresses identified by entity ID. To do so, they override the default AddressPolicy with EBusAddressPolicy::ById and set the BusIdType to EntityId.
3. Declare a function for each event that the EBus will dispatch. Handler classes will implement these functions to handle the events.
4. Declare an EBus that takes your class as a template parameter.
5. Send events. The function that you use to send the event depends on which addresses you want to send the event to, whether to return a value, the order in which to call the handlers, and whether to queue the event.
   • To send an event to all handlers connected to the EBus, use Broadcast(). If an EBus has multiple addresses, you can use Event() to send the event only to handlers connected at the specified ID. For performance-critical code, you can avoid an address lookup by using Event() variants that take a pointer instead of an ID.
   • If an event returns a value, use BroadcastResult() or EventResult() to get the result.
   • If you want handlers to receive the events in reverse order, use BroadcastReverse() or EventReverse().
   • To send events asynchronously, queue the event. Queued events are not executed until the queue is flushed. To support queuing, set the EnableEventQueue trait. To queue events, use QueueBroadcast() or QueueEvent(). To flush the event queue, use ExecuteQueuedEvents().

Setting up a Handler

To enable a handler class to handle the events dispatched by a notification bus, do the following:

1. Derive your handler class from <BusName>::Handler. For example, a class that needs to handle tick requests should derive from TickRequestBus::Handler.
2. Implement the EBus interface to define how the handler class should handle the events. In the tick bus example, a handler class would implement OnTick().
3. Connect and disconnect from the bus at the appropriate places within your handler class's code. Use <BusName>:Handler::BusConnect() to connect to the bus and <BusName>:Handler::BusDisconnect() to disconnect from the bus. If the handler class is a component, connect to the bus in Activate() and disconnect from the bus in Deactivate(). Non-components typically connect in the constructor and disconnect in the destructor.

Request Buses

A request bus receives and handles requests. Typically, only one class handles requests for a request bus.

Setting up a Request Bus

The first several steps for setting up a request bus are similar to setting up a notification bus. After that you also need to implement the handlers for handling the requests. To set up a request bus, do the following:

1. Define a class that inherits from EBusTraits. This class will be the interface for requests made to the EBus.
2. Override individual EBusTraits properties to define the behavior of your bus. Two EBusTraits that request buses commonly override are AddressPolicy, which defines how many addresses the EBus contains, and HandlerPolicy, which describes how many handlers can connect to each address. For example, because there is typically only one handler class for each request bus, request buses typically override the default handler policy with EBusHandlerPolicy::Single.
3. Declare a function for each event that the handler class will receive requests about. These are the functions that other classes will use to make requests of the handler class.
4. Declare an EBus that takes your class as a template parameter.
5. Implement a handler for the events as described in the previous section ("Setting up a Handler").

Member Typedef Documentation

AllocatorType

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::AllocatorType = typename ImplTraits::AllocatorType

Allocator used by the EBus. The default setting is AZStd::allocator, which uses AZ::SystemAllocator.

BaseImpl

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::BaseImpl = BusInternal::EBusImpl<AZ::EBus<Interface, BusTraits>, BusInternal::EBusImplTraits<Interface, BusTraits>, typename BusTraits::BusIdType>

Represents an EBus with certain broadcast, event, and routing functionality.

BindLockGuardTemplate

template<class Interface , class BusTraits = Interface>

template<typename ContextMutexType >

using AZ::EBus< Interface, BusTraits >::BindLockGuardTemplate = typename ImplTraits::template BindLockGuard<ContextMutexType>

Template Lock Guard class that wraps around the Mutex the EBus uses for Bus Bind calls.

BusesContainer

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::BusesContainer = typename ImplTraits::BusesContainer

Contains all of the addresses on the EBus.

BusIdOrderCompare

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::BusIdOrderCompare = typename ImplTraits::BusIdOrderCompare

Sorting function for EBus address IDs. Used only when the address policy 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

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::BusIdType = typename ImplTraits::BusIdType

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

BusPtr

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::BusPtr = typename ImplTraits::BusPtr

Pointer to an address on the bus.

CallstackEntry

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::CallstackEntry = AZ::Internal::CallstackEntry<Interface, Traits>

Used to manually create a callstack entry for a call (often used by ConnectionPolicy)

CallstackTrackerLockGuardTemplate

template<class Interface , class BusTraits = Interface>

template<typename ContextMutexType >

using AZ::EBus< Interface, BusTraits >::CallstackTrackerLockGuardTemplate = typename ImplTraits::template CallstackTrackerLockGuard<ContextMutexType>

Template Lock Guard class that wraps around the Mutex the EBus uses for Bus callstack tracking.

ConnectionPolicy

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::ConnectionPolicy = typename Traits::template ConnectionPolicy<ThisType>

Enables custom logic to run when a handler connects to or disconnects from the EBus. For example, you can make a handler execute an event immediately upon connecting to the EBus. For available settings, see AZ::EBusConnectionPolicy. By default, no extra logic is run.

ConnectLockGuardTemplate

template<class Interface , class BusTraits = Interface>

template<typename ContextMutexType >

using AZ::EBus< Interface, BusTraits >::ConnectLockGuardTemplate = typename ImplTraits::template ConnectLockGuard<ContextMutexType>

Template Lock Guard class that wraps around the Mutex the EBus uses for Bus Connects / Disconnects.

DispatchLockGuardTemplate

template<class Interface , class BusTraits = Interface>

template<typename DispatchMutex >

using AZ::EBus< Interface, BusTraits >::DispatchLockGuardTemplate = typename ImplTraits::template DispatchLockGuard<DispatchMutex>

Template Lock Guard class that wraps around the Mutex The EBus uses for Dispatching Events. This is not EBus Context Mutex when LocklessDispatch is set

EventQueueMutexType

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::EventQueueMutexType = typename ImplTraits::EventQueueMutexType

Locking primitive that is used when executing events in the event queue.

Events

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::Events = typename ImplTraits::Events

The events that are defined by the EBus interface.

HandlerNode

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::HandlerNode = typename ImplTraits::HandlerNode

Pointer to a handler node.

ImplTraits

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::ImplTraits = BusInternal::EBusImplTraits<Interface, BusTraits>

Contains data about EBusTraits.

InterfaceType

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::InterfaceType = typename ImplTraits::InterfaceType

The class that defines the interface of the EBus.

MutexType

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::MutexType = typename ImplTraits::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.

NestedVersionRouter

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::NestedVersionRouter = AZ::Internal::EBusNestedVersionRouter<ThisType>

Class that implements an EBus version router.

QueuePolicy

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::QueuePolicy = EBusQueuePolicy<Traits::EnableEventQueue, ThisType, EventQueueMutexType>

Policy for the function queue.

Router

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::Router = AZ::Internal::EBusRouter<ThisType>

Class that implements EBus routing functionality.

RouterPolicy

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::RouterPolicy = typename Traits::template RouterPolicy<ThisType>

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.

RouterProcessingState

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::RouterProcessingState = typename RouterPolicy::EventProcessingState

State that indicates whether to continue routing the event, skip all handlers but notify other routers, or stop processing the event.

StoragePolicy

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::StoragePolicy = typename Traits::template StoragePolicy<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.
• 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.

ThisType

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::ThisType = AZ::EBus<Interface, Traits>

The type of EBus, which is defined by the interface and the EBusTraits.

Traits

template<class Interface , class BusTraits = Interface>

using AZ::EBus< Interface, BusTraits >::Traits = typename ImplTraits::Traits

Alias for EBusTraits.

Member Function Documentation

GetContext()

template<class Interface , class Traits >

EBus< Interface, Traits >::Context * AZ::EBus< Interface, Traits >::GetContext ( bool  trackCallstack = true )

static

Returns the global bus data (if it was created). Depending on the storage policy, there might be one or multiple instances of the bus data.

Returns

A reference to the bus context.

GetCurrentBusId()

template<class Interface , class Traits >

const EBus< Interface, Traits >::BusIdType * AZ::EBus< Interface, Traits >::GetCurrentBusId

static

Gets the ID of the address that is currently receiving an event. You can use this function while handling an event to determine which ID the event concerns. This is especially useful for handlers that connect to multiple address IDs.

Returns

Pointer to the address ID that is currently receiving an event. Returns a null pointer if the EBus is not currently sending an event or the EBus does not use an AZ::EBusAddressPolicy that has multiple addresses.

GetName()

template<class Interface , class Traits >

const char * AZ::EBus< Interface, Traits >::GetName

static

Returns a unique signature for the EBus.

Returns

A unique signature for the EBus.

GetOrCreateContext()

template<class Interface , class Traits >

EBus< Interface, Traits >::Context & AZ::EBus< Interface, Traits >::GetOrCreateContext ( bool  trackCallstack = true )

static

Returns the global bus data. Creates it if it wasn't already created. Depending on the storage policy, there might be one or multiple instances of the bus data.

Returns

A reference to the bus context.

GetTotalNumOfEventHandlers()

template<class Interface , class Traits >

AZ_POP_DISABLE_WARNING size_t AZ::EBus< Interface, Traits >::GetTotalNumOfEventHandlers

static

Returns the total number of handlers that are connected to the EBus.

Returns

The total number of handlers that are connected to the EBus.

HasHandlers() [1/3]

template<class Interface , class Traits >

bool AZ::EBus< Interface, Traits >::HasHandlers

inlinestatic

Returns whether any handlers are connected to the EBus.

Returns

True if there are any handlers connected to the EBus. Otherwise, false.

HasHandlers() [2/3]

template<class Interface , class Traits >

bool AZ::EBus< Interface, Traits >::HasHandlers ( const BusIdType &  id )

inlinestatic

Returns whether handlers are connected to this specific address.

Returns

True if there are any handlers connected at the address. Otherwise, false.

HasHandlers() [3/3]

template<class Interface , class Traits >

bool AZ::EBus< Interface, Traits >::HasHandlers ( const BusPtr &  ptr )

inlinestatic

Returns whether handlers are connected to the specific cached address.

Returns

True if there are any handlers connected at the cached address. Otherwise, false.

HasReentrantEBusUseThisThread()

template<class Interface , class Traits >

bool AZ::EBus< Interface, Traits >::HasReentrantEBusUseThisThread ( const BusIdType *  busId = GetCurrentBusId() )

static

Checks to see if an EBus with a given Bus ID appears twice in the callstack. This can be used to detect infinite recursive loops and other reentrancy problems. This method only checks EBus and ID, not the specific EBus event, so two different nested event calls on the same EBus and ID will still return true.

Parameters

busId

The bus ID to check for reentrancy on this thread.

Returns

true if the EBus has been called more than once on this thread's callstack, false if not.

IsInDispatchThisThread()

template<class Interface , class Traits >

bool AZ::EBus< Interface, Traits >::IsInDispatchThisThread ( Context *  context = GetContext(false) )

static

Returns whether the EBus context is in the middle of a dispatch on the current thread

Member Data Documentation

EnableEventQueue

template<class Interface , class BusTraits = Interface>

const bool AZ::EBus< Interface, BusTraits >::EnableEventQueue = ImplTraits::EnableEventQueue

static

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.

HasId

template<class Interface , class BusTraits = Interface>

const bool AZ::EBus< Interface, BusTraits >::HasId = Traits::AddressPolicy != EBusAddressPolicy::Single

static

True if the EBus supports more than one address. Otherwise, false.

---

The documentation for this class was generated from the following file:

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