Menu
Lumberyard
C++ API Reference (Version 1.10)

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

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 BusIdTypeGetCurrentBusId ()
 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
InterfaceA class whose virtual functions define the events dispatched or received by the EBus.
TraitsA 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:

  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.

◆ 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 
)
inlinestatic

Acquires a pointer to an EBus address.

Parameters
[out]ptrA 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.
idThe 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 ( )
inlinestatic

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

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

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