Class EnvironmentManager

Class Documentation

class flamegpu::EnvironmentManager

Singleton manager for managing environment properties storage in constant memory This is an internal class, that should not be accessed directly by modellers

Note

Not thread-safe

See

EnvironmentDescription For describing the initial state of a model’s environment properties

See

AgentEnvironment For reading environment properties during agent functions on the device

See

HostEnvironment For accessing environment properties during host functions

Public Types

enum OL

Gives names to indices of OffsetLen

Values:

enumerator OFFSET
enumerator LEN
typedef unsigned int size_type

Offset relative to c_buffer Length in bytes

typedef std::pair<ptrdiff_t, size_t> OffsetLen

Used to group items required by freeFragments

typedef std::multimap<std::pair<size_t, const NamePair>, DefragProp, std::less<>> DefragMap

Typedef for the map used for defragementation The map is ordered by key of type size, therefore a reverse sort creates aligned data Specify a transparent operator, to allow us to operate only over size_t part of key

Public Functions

void init(const unsigned int &instance_id, const EnvironmentDescription &desc, bool isPureRTC)

Activates a models environment properties, by adding them to constant cache

Parameters
  • instance_id – instance_id of the CUDASimulation instance the properties are attached to

  • desc – environment properties description to use

  • isPureRTC – If true, Curve collision warnings (debug build only) will be suppressed as they are irrelevant to RTC models

void init(const unsigned int &instance_id, const EnvironmentDescription &desc, bool isPureRTC, const unsigned int &master_instance_id, const SubEnvironmentData &mapping)

Submodel variant of init() Activates a models unmapped environment properties, by adding them to constant cache Maps a models mapped environment properties to their master property

Parameters
  • instance_id – instance_id of the CUDASimulation instance the properties are attached to

  • desc – environment properties description to use

  • isPureRTC – If true, Curve collision warnings (debug build only) will be suppressed as they are irrelevant to RTC models

  • master_instance_id – instance_id of the CUDASimulation instance of the parent of the submodel

  • mapping – Metadata for which environment properties are mapped between master and submodels

void initRTC(const CUDASimulation &cudaSimulation)

RTC functions hold their own unique constants for environment variables. This function copies all environment variable to the RTC copies. It can not be incorporated into init() as init will be called before RTC functions have been compiled. Uses the already populated Environment data from the cudaSimulation rather than environmentDescription.

Parameters

cudaSimulation – the cuda model being initialised.

void free(detail::curve::Curve &curve, const unsigned int &instance_id)

Deactives all environmental properties linked to the named model from constant cache

Parameters
  • curve – The Curve singleton instance to use, it is important that we purge curve for the correct device

  • instance_id – instance_id of the CUDASimulation instance the properties are attached to

template<typename T>
void newProperty(const NamePair &name, const T &value, const bool &isConst = false)

Adds a new environment property

Constructors

Parameters
  • name – name used for accessing the property

  • value – stored value of the property

  • isConst – If set to true, it is not possible to change the value

Template Parameters

T – Type of the environmental property to be created

Throws

exception::DuplicateEnvProperty – If a property of the same name already exists

template<typename T>
void newProperty(const unsigned int &instance_id, const std::string &var_name, const T &value, const bool &isConst = false)

Convenience method: Adds a new environment property

See

add(const NamePair &, const T &, const bool &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

  • value – stored value of the property

  • isConst – If set to true, it is not possible to change the value

Template Parameters

T – Type of the environmental property to be created

Throws

exception::DuplicateEnvProperty – If a property of the same name already exists

template<typename T, size_type N>
void newProperty(const NamePair &name, const std::array<T, N> &value, const bool &isConst = false)

Adds a new environment property array

Parameters
  • name – name used for accessing the property

  • value – stored value of the property

  • isConst – If set to true, it is not possible to change the value

Template Parameters
  • T – Type of the environmental property array to be created

  • N – Length of the environmental property array to be created

Throws

exception::DuplicateEnvProperty – If a property of the same name already exists

template<typename T, size_type N>
void newProperty(const unsigned int &instance_id, const std::string &var_name, const std::array<T, N> &value, const bool &isConst = false)

Convenience method: Adds a new environment property array

See

add(const NamePair &, const std::array<T, N> &, const bool &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

  • value – stored value of the property

  • isConst – If set to true, it is not possible to change the value

Template Parameters
  • T – Type of the environmental property array to be created

  • N – Length of the environmental property array to be created

Throws

exception::DuplicateEnvProperty – If a property of the same name already exists

template<typename T>
T setProperty(const NamePair &name, const T &value)

Sets an environment property

Setters

Parameters
  • name – name used for accessing the property

  • value – value to set the property

Template Parameters

T – Type of the environmental property array to be created

Throws
Returns

Returns the previous value

template<typename T>
T setProperty(const unsigned int &instance_id, const std::string &var_name, const T &value)

Convenience method: Sets an environment property

See

add(const NamePair &, const T &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

  • value – value to set the property

Template Parameters

T – Type of the environmental property array to be created

Throws
Returns

Returns the previous value

template<typename T, size_type N>
std::array<T, N> setProperty(const NamePair &name, const std::array<T, N> &value)

Sets an environment property array

Parameters
  • name – name used for accessing the property array

  • value – value to set the property array

Template Parameters
  • T – Type of the environmental property array to be created

  • N – Length of the environmental property array to be created

Throws
Returns

Returns the previous value

template<typename T, size_type N>
std::array<T, N> setProperty(const unsigned int &instance_id, const std::string &var_name, const std::array<T, N> &value)

Convenience method: Sets an environment property array

See

set(const NamePair &, const std::array<T, N> &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

  • value – value to set the property array

Template Parameters
  • T – Type of the environmental property array to be created

  • N – Length of the environmental property array to be created

Throws
Returns

Returns the previous value

template<typename T>
T setProperty(const NamePair &name, const size_type &index, const T &value)

Sets an element of an environment property array

Parameters
  • name – name used for accessing the property array

  • index – Index of the element within the array

  • value – value to set the element of the property array

Template Parameters

T – Type of the environmental property array to be created

Throws
Returns

Returns the previous value

template<typename T>
T setProperty(const unsigned int &instance_id, const std::string &var_name, const size_type &index, const T &value)

Convenience method: Sets an element of an environment property array

See

set(const NamePair &, const size_type &, const T &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

  • index – Index of the element within the array

  • value – value to set the element of the property array

Template Parameters

T – Type of the environmental property array to be created

Throws
Returns

Returns the previous value

template<typename T>
T getProperty(const NamePair &name)

Gets an environment property

Getters

See

get(const NamePair &)

Parameters

name – name used for accessing the property

Template Parameters

T – Type of the environmental property array to be created

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

template<typename T>
T getProperty(const unsigned int &instance_id, const std::string &var_name)

Convenience method: Gets an environment property

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

Template Parameters

T – Type of the environmental property array to be created

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

template<typename T, size_type N>
std::array<T, N> getProperty(const NamePair &name)

Gets an environment property array

Parameters

name – name used for accessing the property array

Template Parameters
  • T – Type of the environmental property array to be created

  • N – Length of the environmental property array to be created

Throws

exception::InvalidEnvProperty – If a property array of the name does not exist

template<typename T, size_type N>
std::array<T, N> getProperty(const unsigned int &instance_id, const std::string &var_name)

Convenience method: Gets an environment property array

See

get(const NamePair &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

Template Parameters
  • T – Type of the environmental property array to be created

  • N – Length of the environmental property array to be created

Throws

exception::InvalidEnvProperty – If a property array of the name does not exist

template<typename T>
T getProperty(const NamePair &name, const size_type &index)

Gets an element of an environment property array

Parameters
  • name – name used for accessing the property array

  • index – Index of the element within the array

Template Parameters

T – Type of the value to be returned

Throws
template<typename T>
T getProperty(const unsigned int &instance_id, const std::string &var_name, const size_type &index)

Convenience method: Gets an element of an environment property array

See

get(const NamePair &, const size_type &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

  • index – The index of the element within the environment property array

Template Parameters

T – Type of the value to be returned

Throws
util::Any getPropertyAny(const unsigned int &instance_id, const std::string &var_name) const

Returns the current value of an environment property as an Any object This method should not be exposed to users

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

void removeProperty(const NamePair &name)

Removes an environment property

Note

This may be used to remove and recreate environment properties (and arrays) marked const

Parameters

name – name used for accessing the property

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

void removeProperty(const unsigned int &instance_id, const std::string &var_name)

Convenience method: Removes an environment property

See

remove(const NamePair &)

Note

This may be used to remove and recreate environment properties (and arrays) marked const

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

void resetModel(const unsigned int &instance_id, const EnvironmentDescription &desc)

Returns all environment properties owned by a model to their default values This means that properties inherited by a submodel will not be reset to their default values

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • desc – The environment description (this is where the defaults are pulled from)

inline bool containsProperty(const NamePair &name) const

Returns whether the named env property exists

Parameters

name – name used for accessing the property

inline bool containsProperty(const unsigned int &instance_id, const std::string &var_name) const

Convenience method: Returns whether the named env property exists

See

contains(const NamePair &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

inline bool isConst(const NamePair &name) const

Returns whether the named env property is marked as const

Parameters

name – name used for accessing the property

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

Returns

true if the var is marked as constant (cannot be changed during simulation)

inline bool isConst(const unsigned int &instance_id, const std::string &var_name) const

Convenience method: Returns whether the named env property is marked as const

See

isConst(const NamePair &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

Returns

true if the var is marked as constant (cannot be changed during simulation)

inline size_type length(const NamePair &name) const

Returns the number of elements of the named env property (1 if not an array)

Parameters

name – name used for accessing the property

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

inline size_type length(const unsigned int &instance_id, const std::string &var_name) const

Convenience method: Returns the number of elements of the named env property (1 if not an array)

See

length(const NamePair &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

inline std::type_index type(const NamePair &name) const

Returns the variable type of named env property

Parameters

name – name used for accessing the property

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

inline std::type_index type(const unsigned int &instance_id, const std::string &var_name) const

Convenience method: Returns the variable type of named env property

See

type(const NamePair &)

Parameters
  • instance_id – instance_id of the CUDASimulation instance the property is attached to

  • var_name – name used for accessing the property

Throws

exception::InvalidEnvProperty – If a property of the name does not exist

inline size_t freeSpace() const

Returns the available space remaining (bytes) for storing environmental properties

inline const std::unordered_map<NamePair, EnvProp, NamePairHash> &getPropertiesMap() const

Returns read-only access to the properties map

Note

You must acquire a lock on mutex before calling this method

inline const std::unordered_map<NamePair, MappedProp, NamePairHash> &getMappedProperties() const

Returns readonly access to mapped properties

Note

You must acquire a lock on mutex before calling this method

inline const void *getHostBuffer() const

Used by IO methods to efficiently access environment

Note

You must acquire a lock on mutex before calling this method

void updateDevice(const unsigned int &instance_id)

Updates the copy of the environment property cache on the device

Parameters

instance_id – Used to update the specified instance’s rtc too

EnvironmentManager(EnvironmentManager const&) = delete
void operator=(EnvironmentManager const&) = delete

Public Members

const detail::curve::Curve::NamespaceHash CURVE_NAMESPACE_HASH

Hash never changes, so we store a copy at creation Also ensure the device constexpr version matches

Public Static Attributes

static const size_t MAX_BUFFER_SIZE = 10 * 1024

Max amount of space that can be used for storing environmental properties

static const char CURVE_NAMESPACE_STRING[23] = "ENVIRONMENT_PROPERTIES"

This is the string used to generate CURVE_NAMESPACE_HASH

Protected Functions

const CUDASimulation &getCUDASimulation(const unsigned int &instance_id)
void updateRTCValue(const NamePair &name)

Update the copy of the env var that exists in the rtc_cache to match the main cache

Parameters

name – namepair of the variable to be updated

Protected Static Functions

static EnvironmentManager &getInstance()

Returns the EnvironmentManager singleton instance

Protected Static Attributes

static std::mutex instance_mutex

Friends

friend class io::XMLStateWriter
friend class io::XMLStateReader
friend class io::JSONStateWriter
friend class io::JSONStateReader
friend class io::JSONStateReader_impl
inline friend friend bool operator< (const std::pair< size_t, const NamePair > &fk, const size_t &lk)

Transparent operators for DefragMap This allows them to be secondarily ordered based on NamePair if size is equal

inline friend friend bool operator< (const size_t &lk, const std::pair< size_t, const NamePair > &fk)
inline friend friend bool operator< (const std::pair< size_t, const NamePair > &fk1, const std::pair< size_t, const NamePair > &fk2)
struct DefragProp

This structure is a clone of EnvProp However, instead of offset (which points to an offset into hc_buffer) data is available, which points to host memory

Public Functions

inline explicit DefragProp(const EnvProp &ep)

Note

ep.offset is converted to a host pointer by adding to hc_buffer

Parameters

ep – Environment property to clone

inline DefragProp(void *_data, const size_t &_length, const bool &_isConst, const size_type &_elements, const std::type_index &_type, const ptrdiff_t &_rtc_offset = 0)
Parameters
  • _data – Pointer to the data in host memory

  • _length – Length of associated storage

  • _isConst – Is the stored data constant

  • _elements – How many elements does the stored data contain (1 if not array)

  • _type – Type of propert (from typeid())

  • _rtc_offset – Offset into the instances rtc cache, this can be skipped if the relevant rtc cache has not yet been built

Public Members

void *data
size_t length
bool isConst
size_type elements
const std::type_index type
ptrdiff_t rtc_offset
struct EnvProp

Used to group items required by properties

Public Functions

inline EnvProp(const ptrdiff_t &_offset, const size_t &_length, const bool &_isConst, const size_type &_elements, const std::type_index &_type, const ptrdiff_t &_rtc_offset = 0)
Parameters
  • _offset – Offset into c_buffer/hc_buffer

  • _length – Length of associated storage

  • _isConst – Is the stored data constant

  • _elements – How many elements does the stored data contain (1 if not array)

  • _type – Type of property (from typeid())

  • _rtc_offset – Offset into the instances rtc cache, this can be skipped if the relevant rtc cache has not yet been built

Public Members

ptrdiff_t offset
size_t length
bool isConst
size_type elements
const std::type_index type
ptrdiff_t rtc_offset
struct MappedProp

Used to represent properties of a mapped environment property

Public Functions

inline MappedProp(const NamePair &_masterProp, const bool &_isConst)
Parameters
  • _masterProp – Master property of mapping

  • _isConst – Is the stored data constant

Public Members

const NamePair masterProp
const bool isConst
struct RTCEnvPropCache

Struct used by rtc_caches Represents a personalised constant cache buffer for a single CUDASimulation instance These are shared by submodels

Public Members

char hc_buffer[MAX_BUFFER_SIZE]

Host copy of the device memory pointed to by c_buffer

ptrdiff_t nextFree = 0

Offset relative to c_buffer, where no more data has been stored