Open 3D Engine AzCore API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
AZ::EBusEnvironment Class Reference

#include <Environment.h>

Public Member Functions

 AZ_CLASS_ALLOCATOR (EBusEnvironment, AZ::OSAllocator)
 
void ActivateOnCurrentThread ()
 
void DeactivateOnCurrentThread ()
 
template<class Context >
Context * GetBusContext (int tlsKey)
 
AZ::Internal::ContextBase * FindContext (int tlsKey)
 
bool InsertContext (int tlsKey, AZ::Internal::ContextBase *context, bool isTakeOwnership)
 
template<class Bus >
bool RedirectToGlobalContext ()
 

Static Public Member Functions

static EBusEnvironmentCreate ()
 
static void Destroy (EBusEnvironment *environment)
 

Protected Attributes

EnvironmentVariable< Internal::EBusEnvironmentTLSAccessors > m_tlsAccessor
 
EBusEnvironmentm_stackPrevEnvironment
 Pointer to the previous environment on the TLS stack. This is valid only when the context is in use. Each BusEnvironment can only be active on a single thread at a time.
 
AZStd::vector< AZStd::pair< Internal::ContextBase *, bool >, OSStdAllocatorm_busContexts
 Array with all EBus<T>::Context for this environment.
 

Friends

template<class Context >
struct EBusEnvironmentStoragePolicy
 

Detailed Description

EBusEnvironment defines a separate EBus execution context. All EBuses will have unique instances in each environment, unless specially configured to not do that (not supported yet as it's tricky and will likely create contention and edge cases). If you want EBusEnvinronments to communicate you should use a combination of listeners/routers and event queuing to implement that. This is by design as the whole purpose of having a separate environment is to cut any possible sharing by default, think of it as a separate VM. When communication is needed it should be explicit and considering the requirements you had in first place when you created separate environment. Otherwise you will start having contention issues or even worse execute events (handlers) when the environment is not active. EBusEnvironment is very similar to the way OpenGL contexts operate. You can manage their livecycle from any thread at anytime by calling EBusEnvironment::Create/Destroy. You can activate/deactivate an environment by calling ActivateOnCurrentThread/DeactivateOnCurrentThread. Every EBusEnvironment can be activated to only one thread at a time.

Member Function Documentation

◆ Create()

static EBusEnvironment * AZ::EBusEnvironment::Create ( )
static

Create and Destroy are provided for consistency and writing code with explicitly set Create/Destroy location. You can also just use it as any other class: EBusEnvironment* myEBusEnvironmnet = aznew EBusEnvironment; and later delete myEBusEnvironment.

◆ FindContext()

AZ::Internal::ContextBase * AZ::EBusEnvironment::FindContext ( int  tlsKey)

Finds an EBus Internal::ContextBase in the current environment.

Returns
Pointer to the context base class, or null if context for this doesn't exists.

◆ InsertContext()

bool AZ::EBusEnvironment::InsertContext ( int  tlsKey,
AZ::Internal::ContextBase *  context,
bool  isTakeOwnership 
)

Inserts an existing context for a specific bus id. When using this function make sure the provided context is alive while this environment is operational.

Parameters
busIdis of the bus
contextcontext to insert
isTakeOwnershiptrue if want this environment to delete the context when destroyed, or false is this context is owned somewhere else
Returns
true if the insert was successful, false if there is already a context for this id and the insert did not happen.

◆ RedirectToGlobalContext()

template<class Bus >
bool AZ::EBusEnvironment::RedirectToGlobalContext

This is a helper function that will insert that global bus context Bus::GetContext and use it for this environment. Currently this function requires that the Bus uses EBusEnvironmentStoragePolicy, otherwise you will get a compile error. Once we have a way to have a BusId independent of the storage policy, we can remove that restriction.

Returns
true if the insert/redirect was successful, false if there is already a context for this bus and the insert did not happen.

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