Event buses (EBuses) are a general-purpose communication system that Lumberyard uses to dispatch notifications and receive requests. More...

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

Public Types
using	ImplTraits
	Contains data about EBusTraits . More...

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

using	Traits
	Alias for EBusTraits . More...

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

using	AllocatorType
	Allocator used by the EBus. More...

using	InterfaceType
	The class that defines the interface of the EBus. More...

using	Events
	The events that are defined by the EBus interface. More...

using	BusIdType
	The type of ID that is used to address the EBus. More...

using	BusIdOrderCompare
	Sorting function for EBus address IDs. More...

using	MutexType
	Locking primitive that is used when connecting handlers to the EBus or executing events. More...

using	EBNode
	An address on the EBus. More...

using	BusesContainer
	Contains all of the addresses on the EBus. More...

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

using	BusPtr
	Pointer to an address on the bus. More...

using	HandlerNode
	Pointer to a handler node. More...

using	Handler
	An event handler that can be attached to only one address at a time. More...

using	MultiHandler
	An event handler that can be attached to multiple addresses. More...

using	MessageQueuePolicy
	Policy for the message queue. More...

using	FunctionQueuePolicy
	Policy for the function queue. More...

using	ConnectionPolicy
	Enables custom logic to run when a handler connects to or disconnects from the EBus. More...

using	Router
	Class that implements EBus routing functionality. More...

using	NestedVersionRouter
	Class that implements an EBus version router. More...

using	RouterPolicy
	Controls the flow of EBus events. More...

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

typedef	StoragePolicy
	Specifies where EBus data is stored. More...

Public Types inherited from AZ::BusInternal::EBusBroadcaster< AZ::EBus< Interface, BusTraits >, BusInternal::EBusImplTraits< Interface, BusTraits > >
using	BusPtr
	Pointer to an address on the bus. More...

Public Types inherited from AZ::BusInternal::EBusEventer< AZ::EBus< Interface, BusTraits >, BusInternal::EBusImplTraits< Interface, BusTraits > >
using	BusIdType
	The type of ID that is used to address the EBus. More...

using	BusPtr
	Pointer to an address on the bus. More...

Public Types inherited from AZ::BusInternal::EBusEventEnumerator< AZ::EBus< Interface, BusTraits >, BusInternal::EBusImplTraits< Interface, BusTraits > >
using	BusIdType
	The type of ID that is used to address the EBus. More...

using	BusPtr
	Pointer to an address on the bus. More...

Static Public Member Functions
static void	Bind ( BusPtr &ptr, const BusIdType &id=0)
	Acquires a pointer to an EBus address. More...

static size_t	GetTotalNumOfEventHandlers ()
	Returns the total number of handlers that are connected to the EBus . More...

static bool	HasHandlers ()
	Returns whether any handlers are connected to the EBus . More...

static const BusIdType *	GetCurrentBusId ()
	Gets the ID of the address that is currently receiving an event. More...

static const char *	GetName ()
	Returns a unique signature for the EBus . More...

static Context &	GetContext ()
	Returns the global bus data. More...

Static Public Member Functions inherited from AZ::BusInternal::EBusBroadcaster< AZ::EBus< Interface, BusTraits >, BusInternal::EBusImplTraits< Interface, BusTraits > >
static void	Broadcast (Function func, InputArgs &&... args)
	Dispatches an event to all handlers. More...

static void	BroadcastResult (Results &results, Function func, InputArgs &&... args)
	Dispatches an event to all handlers and receives results. More...

static void	BroadcastReverse (Function func, InputArgs &&... args)
	Dispatches an event to all handlers in reverse order. More...

static void	BroadcastResultReverse (Results &results, Function func, InputArgs &&... args)
	Dispatches an event to all handlers in reverse order and receives results. More...

Static Public Member Functions inherited from AZ::BusInternal::EBusEventer< AZ::EBus< Interface, BusTraits >, BusInternal::EBusImplTraits< Interface, BusTraits > >
static void	Event (const BusIdType &id, Function func, InputArgs &&... args)
	Dispatches an event to handlers at a specific address. More...

static void	Event (const BusPtr &ptr, Function func, InputArgs &&... args)
	Dispatches an event to handlers at a cached address. More...

static void	EventResult (Results &results, const BusIdType &id, Function func, InputArgs &&... args)
	Dispatches an event to handlers at a specific address and receives results. More...

static void	EventResult (Results &results, const BusPtr &ptr, Function func, InputArgs &&... args)
	Dispatches an event to handlers at a cached address and receives results. More...

static void	EventReverse (const BusIdType &id, Function func, InputArgs &&... args)
	Dispatches an event to handlers at a specific address in reverse order. More...

static void	EventReverse (const BusPtr &ptr, Function func, InputArgs &&... args)
	Dispatches an event to handlers at a cached address in reverse order. More...

static void	EventResultReverse (Results &results, const BusIdType &id, Function func, InputArgs &&... args)
	Dispatches an event to handlers at a specific address in reverse order and receives results. More...

static void	EventResultReverse (Results &results, const BusPtr &ptr, Function func, InputArgs &&... args)
	Dispatches an event to handlers at a cached address in reverse order and receives results. More...

Static Public Member Functions inherited from AZ::BusInternal::EBusEventEnumerator< AZ::EBus< Interface, BusTraits >, BusInternal::EBusImplTraits< Interface, BusTraits > >
static void	EnumerateHandlers (Callback callback)
	Calls a user-defined function on all handlers that are connected to the EBus. More...

static void	EnumerateHandlersId (const BusIdType &id, Callback callback)
	Calls a user-defined function on handlers that are connected to a specific address on the EBus. More...

static void	EnumerateHandlersPtr (const BusPtr &ptr, Callback callback)
	Calls a user-defined function on handlers at a cached address. More...

static BusInternal::EBusImplTraits < Interface, BusTraits > ::InterfaceType *	FindFirstHandler (const BusIdType &id)
	Finds the first handler that is connected to a specific address on the EBus. More...

static BusInternal::EBusImplTraits < Interface, BusTraits > ::InterfaceType *	FindFirstHandler (const BusPtr &ptr)
	Finds the first handler at a cached address on the EBus. More...

static size_t	GetNumOfEventHandlers (const BusIdType &id)
	Returns the total number of event handlers that are connected to a specific address on the EBus. More...

Static Public Attributes
static const bool	EnableEventQueue
	Specifies whether the EBus supports an event queue. More...

static const bool	HasId
	True if the EBus supports more than one address. More...

Detailed Description

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

Event buses (EBuses) are a general-purpose communication system that Lumberyard 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 Working with the Event Bus (EBus) System and Components and EBuses: Best Practices in the Lumberyard User 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:

Define a class that inherits from EBusTraits . This class will be the interface for the EBus.
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 .
Declare a function for each event that the EBus will dispatch. Handler classes will implement these functions to handle the events.
Declare an EBus that takes your class as a template parameter.
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:

Derive your handler class from <BusName>::Handler . For example, a class that needs to handle tick requests should derive from TickRequestBus::Handler .
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() .
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:

Define a class that inherits from EBusTraits . This class will be the interface for requests made to the EBus.
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 .
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.
Declare an EBus that takes your class as a template parameter.
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.

◆ 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 function must satisfy AZStd::binary_function<BusIdType, BusIdType, bool> .

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.

◆ 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.

◆ EBNode

template<class Interface , class BusTraits = Interface>

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

An address on the EBus.

◆ 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.

◆ FunctionQueuePolicy

template<class Interface , class BusTraits = Interface>

using AZ::EBus < Interface, BusTraits >:: FunctionQueuePolicy = EBusFunctionQueuePolicy<Traits::EnableEventQueue, ThisType , EventQueueMutexType >

Policy for the function queue.

◆ Handler

template<class Interface , class BusTraits = Interface>

using AZ::EBus < Interface, BusTraits >:: Handler = Internal::EBusEventHandler< ThisType >

An event handler that can be attached to only one address at a time.

◆ 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.

◆ MessageQueuePolicy

template<class Interface , class BusTraits = Interface>

using AZ::EBus < Interface, BusTraits >:: MessageQueuePolicy = EBusMessageQueuePolicy<Traits::EnableEventQueue, ThisType , EventQueueMutexType >

Policy for the message queue.

◆ MultiHandler

template<class Interface , class BusTraits = Interface>

using AZ::EBus < Interface, BusTraits >:: MultiHandler = Internal::EBusMultiEventHandler< ThisType >

An event handler that can be attached to multiple addresses.

◆ 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 = Internal::EBusNestedVersionRouter< ThisType >

Class that implements an EBus version router.

◆ Router

template<class Interface , class BusTraits = Interface>

using AZ::EBus < Interface, BusTraits >:: Router = 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>

typedef Traits::template StoragePolicy <Context> AZ::EBus < Interface, BusTraits >:: StoragePolicy

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

◆ Bind()

template<class Interface , class Traits >

void AZ::EBus < Interface, Traits >::Bind	(	BusPtr &	ptr ,
		const BusIdType &	id = `0`
	)

inline static

Acquires a pointer to an EBus address.

Parameters

[out]	ptr	A pointer that will point to the specified address on the EBus . An address lookup can be avoided by calling Event() with this pointer rather than by passing an ID, but that is only recommended for performance-critical code.
	id	The ID of the EBus address that the pointer will be bound to.

◆ GetContext()

template<class Interface , class BusTraits = Interface>

static Context& AZ::EBus < Interface, BusTraits >::GetContext ( )

inline static

Returns the global bus data.

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 BusTraits = Interface>

static const char* AZ::EBus < Interface, BusTraits >::GetName ( )

inline static

Returns a unique signature for the EBus .

Returns: A unique signature for the EBus .

◆ GetTotalNumOfEventHandlers()

template<class Interface , class Traits >

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()

template<class Interface , class BusTraits = Interface>

static bool AZ::EBus < Interface, BusTraits >::HasHandlers ( )

inline static

Returns whether any handlers are connected to the EBus .

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

Member Data Documentation

◆ EnableEventQueue

template<class Interface , class BusTraits = Interface>

const bool AZ::EBus < Interface, BusTraits >::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

static

True if the EBus supports more than one address.

Otherwise, false.

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

C:/lumberyard-root/dev/Code/Framework/AzCore/AzCore/EBus/ EBus.h

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

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

How Components Use EBuses

Notification Buses

Setting up a Notification Bus

Setting up a Handler

Request Buses

Setting up a Request Bus

Member Typedef Documentation

◆ AllocatorType

◆ BaseImpl

◆ BusesContainer

◆ BusIdOrderCompare

◆ BusIdType

◆ BusPtr

◆ ConnectionPolicy

◆ EBNode

◆ EventQueueMutexType

◆ Events

◆ FunctionQueuePolicy

◆ Handler

◆ HandlerNode

◆ ImplTraits

◆ InterfaceType

◆ MessageQueuePolicy

◆ MultiHandler

◆ MutexType

◆ NestedVersionRouter

◆ Router

◆ RouterPolicy

◆ RouterProcessingState

◆ StoragePolicy

◆ ThisType

◆ Traits

Member Function Documentation

◆ Bind()

◆ GetContext()

◆ GetCurrentBusId()

◆ GetName()

◆ GetTotalNumOfEventHandlers()

◆ HasHandlers()

Member Data Documentation

◆ EnableEventQueue

◆ HasId

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