Template Class DeviceAPI

Nested Relationships

Nested Types

Class Documentation

template<typename MessageIn, typename MessageOut>
class DeviceAPI

A flame gpu api class for the device runtime only.

This class provides access to model variables/state inside agent functions

This class should only be used by the device and never created on the host. It is safe for each agent function to create a copy of this class on the device. Any singleton type behaviour is handled by the curveInstance class. This will ensure that initialisation of the curve (C) library is done only once.

Template Parameters:

  • MessageIn – Input message type (the form found in flamegpu/runtime/messaging.h, MessageNone etc)

  • MessageOut – Output message type (the form found in flamegpu/runtime/messaging.h, MessageNone etc)

Public Functions

__device__ inline DeviceAPI(id_t *&d_agent_output_nextID, detail::curandState *&d_rng, unsigned int *&scanFlag_agentOutput, typename MessageIn::In &&message_in, typename MessageOut::Out &&message_out)

Constructs the device-only API class instance.

Parameters:

  • d_agent_output_nextID – If agent birth is enabled, a pointer to the next available ID in global memory. Device agent birth will atomically increment this value to allocate IDs.

  • d_rng – Device pointer to curand state for this kernel, index 0 should for TID()==0

  • scanFlag_agentOutput – Array for agent output scan flag

  • message_in – Input message handler

  • message_out – Output message handler

template<typename T, unsigned int N>
__device__ T getVariable(const char (&variable_name)[N]) const

Returns the specified variable from the currently executing agent

Parameters:

variable_name – name used for accessing the variable, this value should be a string literal e.g. “foobar”

Template Parameters:

  • T – Type of the agent variable being accessed

  • N – Length of variable name, this should always be implicit if passing a string literal

Throws:

  • exception::DeviceError – If name is not a valid variable within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

  • exception::DeviceError – If T is not the type of variable ‘name’ within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

template<typename T, unsigned int N, unsigned int M>
__device__ T getVariable(const char (&variable_name)[M], unsigned int index) const

Returns the specified variable array element from the currently executing agent

Parameters:

  • variable_name – name used for accessing the variable, this value should be a string literal e.g. “foobar”

  • index – Index of the element within the variable array to return

Template Parameters:

  • T – Type of the agent variable being accessed

  • N – The length of the array variable, as set within the model description hierarchy

  • M – Length of variable_name, this should always be implicit if passing a string literal

Throws:

  • exception::DeviceError – If name is not a valid variable within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

  • exception::DeviceError – If T is not the type of variable ‘name’ within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

  • exception::DeviceError – If index is out of bounds for the variable array specified by name (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

template<typename T, unsigned int N>
__device__ void setVariable(const char (&variable_name)[N], T value)

Sets a variable within the currently executing agent

Parameters:

  • variable_name – The name of the variable

  • value – The value to set the variable

Template Parameters:

  • T – The type of the variable, as set within the model description hierarchy

  • N – variable_name length, this should be ignored as it is implicitly set

Throws:

  • exception::DeviceError – If name is not a valid variable within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

  • exception::DeviceError – If T is not the type of variable ‘name’ within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

template<typename T, unsigned int N, unsigned int M>
__device__ void setVariable(const char (&variable_name)[M], unsigned int index, T value)

Sets an element of an array variable within the currently executing agent

Parameters:

  • variable_name – The name of the array variable

  • index – The index to set within the array variable

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

Template Parameters:

  • T – The type of the variable, as set within the model description hierarchy

  • N – The length of the array variable, as set within the model description hierarchy

  • M – variable_name length, this should be ignored as it is implicitly set

Throws:

  • exception::DeviceError – If name is not a valid variable within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

  • exception::DeviceError – If T is not the type of variable ‘name’ within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

  • exception::DeviceError – If index is out of bounds for the variable array specified by name (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

__device__ inline id_t getID()

Returns the agent’s unique identifier

__forceinline__ __device__ inline unsigned int getStepCounter() const

Access the current stepCount

Returns:

the current step count, 0 indexed unsigned.

__forceinline__ __device__ inline bool isAgent(const char *agent_name)

When passed an agent name, returns a boolean to confirm whether it matches the name of the current agent

This function may be useful if an agent function is shared between multiple agents

Note

The performance of this function is unlikely to be cheap unless used as part of an RTC agent function.

__forceinline__ __device__ inline bool isState(const char *agent_state)

When passed an agent state, returns a boolean to confirm whether it matches the name of the agent input state of the current agent function

This function may be useful if an agent function is shared between multiple agent states

Note

The performance of this function is unlikely to be cheap unless used as part of an RTC agent function (whereby it can be processed at compile time).

Public Members

const MessageIn::In message_in

Provides access to message read functionality inside agent functions

const MessageOut::Out message_out

Provides access to message write functionality inside agent functions

const AgentOut agent_out

Provides access to agent output functionality inside agent functions

const AgentRandom random

Provides access to random functionality inside agent functions

Note

random state isn’t stored within the object, so it can be const

const DeviceEnvironment environment

Provides access to environment variables inside agent functions

Public Static Functions

__forceinline__ __device__ static inline unsigned int getIndex()

Returns the current index of the agent within the state list population. As agents are mapped linearly to a unique thread this is in effect the thread index within the execution grid block. The index may change between agent functions as a result of state list transitions or other internal algorithms which effect order. Thread indices begin at 0 and continue to 1 below the number of agents executing

class AgentOut

Collection of DeviceAPI functions related to agent birth

Public Functions

__device__ inline AgentOut(id_t *&d_agent_output_nextID, unsigned int *&scan_flag_agentOutput)

Constructor

Parameters:

  • d_agent_output_nextID – Pointer to global memory holding the IDs to be assigned to new agents (selected via atomic inc)

  • scan_flag_agentOutput – Pointer to (the start of) buffer of scan flags to be set true if this thread outputs an agent

template<typename T, unsigned int N>
__device__ void setVariable(const char (&variable_name)[N], T value) const

Sets a variable in a new agent to be output after the agent function has completed

Note

Any agent variables not set will remain as their default values

Note

Calling AgentOut::setVariable() or AgentOut::getID() will trigger agent output

Parameters:

  • variable_name – The name of the variable

  • value – The value to set the variable

Template Parameters:

  • T – The type of the variable, as set within the model description hierarchy

  • N – Variable name length, this should be ignored as it is implicitly set

Throws:

  • exception::DeviceError – If name is not a valid variable within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

  • exception::DeviceError – If T is not the type of variable ‘name’ within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

template<typename T, unsigned int N, unsigned int M>
__device__ void setVariable(const char (&variable_name)[M], unsigned int index, T value) const

Sets an element of an array variable in a new agent to be output after the agent function has completed

Note

Any agent variables not set will remain as their default values

Note

Calling AgentOut::setVariable() or AgentOut::getID() will trigger agent output

Parameters:

  • variable_name – The name of the array variable

  • index – The index to set within the array variable

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

Template Parameters:

  • T – The type of the variable, as set within the model description hierarchy

  • N – The length of the array variable, as set within the model description hierarchy

  • M – Variable name length, this should be ignored as it is implicitly set

Throws:

  • exception::DeviceError – If name is not a valid variable within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

  • exception::DeviceError – If T is not the type of variable ‘name’ within the agent (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

  • exception::DeviceError – If index is out of bounds for the variable array specified by name (flamegpu must be built with FLAMEGPU_SEATBELTS enabled for device error checking)

__device__ id_t getID() const

Return the ID of the agent to be created

Note

Calling AgentOut::setVariable() or AgentOut::getID() will trigger agent output