AZ::Environment Namespace Reference

Classes
class	AllocatorInterface

Functions
template<typename T , class... Args>
EnvironmentVariable< T >	CreateVariable (u32 guid, Args &&... args)
template<typename T , class... Args>
EnvironmentVariable< T >	CreateVariable (const char *uniqueName, Args &&... args)
template<typename T , class... Args>
EnvironmentVariable< T >	CreateVariableEx (u32 guid, bool isConstruct, bool isTransferOwnership, Args &&... args)
template<typename T , class... Args>
EnvironmentVariable< T >	CreateVariableEx (const char *uniqueName, bool isConstruct, bool isTransferOwnership, Args &&... args)
	Same as CreateVariableEx and CreateVariable with advanced control parameters.
template<typename T >
EnvironmentVariable< T >	FindVariable (u32 guid)
template<typename T >
EnvironmentVariable< T >	FindVariable (const char *uniqueName)
	Same as FindVariable but using a unique string as input. Please check CreateVariable for more information about hot strings are used internally.
EnvironmentInstance	GetInstance ()
	Returns the environment so you can share it with AttachEnvironment.
void *	GetModuleId ()
	Returns module id (non persistent)
bool	Create (AllocatorInterface *allocator)
void	Destroy ()
void	Attach (EnvironmentInstance sourceEnvironment, bool useAsGetFallback=false)
void	Detach ()
	Detaches the active environment (if one is attached)
bool	IsReady ()
	Returns true if an environment is attached to this module.

Detailed Description

Environment is a module "global variable" provider. It's used when you want to share globals (which should happen as little as possible) between modules/DLLs.

The environment is automatically created on demand. This is why if you want to share the environment between modules you should call AttachEnvironment before anything else that will use the environment. At a high level the environment is basically a hash table with variables<->guid. The environment doesn't own variables they are managed though reference counting.

All environment "internal" allocations are directly allocated from OS C heap, so we don't use any allocators as they use the environment themselves.

You can create/destroy variables from multiple threads, HOWEVER accessing the data of the environment is NOT. If you want to access your variable across threads you will need to add extra synchronization, which is the same if your global was "static".

Using the environment with POD types is straight and simple. On the other hand when your environment variable has virtual methods, things become more complex. We advice that you avoid this as much as possible. When a variable has virtual function, even if we shared environment and memory allocations, the variable will still be "bound" to the module as it's vtable will point inside the module. Which mean that if we unload the module we have to destroy your variable. The system handles this automatically if your class has virtual functions. You can still keep your variables, but if you try to access the data you will trigger an assert, unless you recreated the variable from one of the exiting modules.

Note

we use class for the Environment (instead of simple global function) so can easily friend it to create variables where the ctor/dtor are protected that way you need to add friend AZ::Environment and that's it.

Function Documentation

Attach()

void AZ::Environment::Attach	(	EnvironmentInstance	sourceEnvironment,
		bool	useAsGetFallback = false
	)

Attaches the current module environment from sourceEnvironment. note: this is not a copy it will actually reference the source environment, so any variables you add remove will be visible to all shared modules

Parameters

useAsFallback

if set to true a new environment will be created and only failures to GetVariable which check the shared environment. This way you can change the environment.

Create()

bool AZ::Environment::Create

(

AllocatorInterface *

allocator

)

Create Environment with customer allocator interface. You don't have to call create or destroy as they will created on demand, but is such case the module allocator will used. For example on Windows if you link the CRT two environments will end up on different heaps.

Returns

true if Create was successful, false if environment is already created/attached.

CreateVariable() [1/2]

template<typename T , class... Args>

EnvironmentVariable< T > AZ::Environment::CreateVariable	(	const char *	uniqueName,
		Args &&...	args
	)

Same as CreateVariable except it uses a unique string to identify the variable, this string will be converted to Crc32 and used a guid.

CreateVariable() [2/2]

template<typename T , class... Args>

EnvironmentVariable< T > AZ::Environment::CreateVariable	(	u32	guid,
		Args &&...	args
	)

Creates an environmental variable, if the variable already exists just returns the exiting variable. If not it will create one and return the new variable.

Parameters

guid	- unique persistent id for the variable. It will be matched between modules/different and compilations. The returned variable will be release and it's memory freed when the last reference to it is gone.

CreateVariableEx()

template<typename T , class... Args>

EnvironmentVariable< T > AZ::Environment::CreateVariableEx	(	u32	guid,
		bool	isConstruct,
		bool	isTransferOwnership,
		Args &&...	args
	)

Advanced CreateVariable where you have extra parameters to control the creation and life cycle of the variable.

Parameters

guid	- same as CreateVariable guid
isConstruct	- if we should actually "create" the variable. If false we will just register the variable holder, but EnvironmentVariable<T>::IsConstructed will return false. you will need to manually create it later with EnvironmentVariable<T>::Construct().
isTransferOwnership	- if we can transfer ownership of the variable across modules. For example Module_1 created the variable and Module_2 is using it. If is isTransferOwnership is true if you unload Module_1, Module_2 will get the ownership. If isTransferOwnership is false, it will destroy the variable and any attempt from Module_2 of using will trigger and error (until somebody else creates it again).

Destroy()

void AZ::Environment::Destroy

(

)

Explicit Destroy, you don't have to call it unless you want to control order. It will be called when the module is unloaded. Of course no order is guaranteed.

FindVariable()

template<typename T >

EnvironmentVariable< T > AZ::Environment::FindVariable

(

u32

guid

)

Check if a variable exist if so a valid variable is returned, otherwise the resulting variable pointer will be null.