Menu
Lumberyard
C++ API Reference (Version 1.10)

Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE or visit the AWS Game Tech blog to learn more.

EBusTraits are properties that you use to configure an EBus . More...

Inherited by AZ::BehaviorContextEvents , AZ::ComponentApplicationEvents , AZ::ComponentApplicationRequests , AZ::ComponentBus , AZ::ComponentDescriptorBusTraits , AZ::EntitySystemEvents , AZ::SystemTickEvents , AZ::TickEvents , AZ::TickRequests , AzFramework::EntityContextEvents , AzFramework::EntityContextRequests , AzFramework::GameEntityContextEvents , AzFramework::GameEntityContextRequests , and AzFramework::SliceInstantiationResults .

Public Types

using AllocatorType
Allocator used by the EBus . 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 BusHandlerOrderCompare
Sorting function for EBus event handlers. More...
using MutexType
Locking primitive that is used when connecting handlers to the EBus or executing events. More...
using EventQueueMutexType
Locking primitive that is used when adding and removing events from the queue. More...
using ConnectionPolicy
Enables custom logic to run when a handler connects or disconnects from the EBus . More...
using StoragePolicy
Specifies where EBus data is stored. More...
using RouterPolicy
Controls the flow of EBus events. More...

Static Public Attributes

static const EBusHandlerPolicy HandlerPolicy
Defines how many handlers can connect to an address on the EBus and the order in which handlers at each address receive events. More...
static const EBusAddressPolicy AddressPolicy
Defines how many addresses exist on the EBus . More...
static const bool EnableEventQueue
Specifies whether the EBus supports an event queue. More...

Protected Member Functions

~EBusTraits ()=default
A destructor. More...

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 Working with the Event Bus (EBus) System in the Lumberyard User Guide .

Member Typedef Documentation

AllocatorType

using AZ::EBusTraits::AllocatorType = AZStd::allocator

Allocator used by the EBus .

The default setting is AZStd::allocator, which uses AZ::SystemAllocator.

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. The function must satisfy AZStd::binary_function<Interface*, Interface*, bool> .

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

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&) .

ConnectionPolicy

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.

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.

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

Constructor & Destructor Documentation

~EBusTraits()

AZ::EBusTraits::~EBusTraits ( )
protected default

A destructor.

Member Data Documentation

AddressPolicy

const EBusAddressPolicy AZ::EBusTraits::AddressPolicy
static

Defines how many addresses exist on the EBus .

For available settings, see AZ::EBusAddressPolicy . By default, an EBus uses a single address.

EnableEventQueue

const bool AZ::EBusTraits::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.

HandlerPolicy

const EBusHandlerPolicy AZ::EBusTraits::HandlerPolicy
static

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.


The documentation for this struct was generated from the following file:
  • C:/lumberyard-root/dev/Code/Framework/AzCore/AzCore/EBus/ EBus.h