Template Class DeviceAPI

Nested Relationships

Nested Types

Class Documentation

template<typename MsgIn, typename MsgOut>
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.

tparam MsgIn

Input message type (the form found in flamegpu/runtime/messaging.h, MsgNone etc)

tparam MsgOut

Output message type (the form found in flamegpu/runtime/messaging.h, MsgNone etc)

Public Functions

__device__ inline DeviceAPI(const Curve::NamespaceHash &instance_id_hash, const Curve::NamespaceHash &agentfuncname_hash, const Curve::NamespaceHash &_agent_output_hash, id_t *&d_agent_output_nextID, curandState *&d_rng, unsigned int *&scanFlag_agentOutput, typename MsgIn::In &&msg_in, typename MsgOut::Out &&msg_out)

Constructs the device-only API class instance.

Parameters
  • instance_id_hash – CURVE hash of the CUDASimulation’s instance id

  • agentfuncname_hash – Combined CURVE hashes of agent name and func name

  • _agent_output_hash – Combined CURVE hashes for agent output

  • 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

  • msg_in – Input message handler

  • msg_out – Output message handler

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
  • DeviceError – If name is not a valid variable within the agent (flamegpu must be built with SEATBELTS enabled for device error checking)

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

template<typename T, unsigned int N, unsigned int M>
__device__ void setVariable(const char (&variable_name)[M], const unsigned int &index, const 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 velement

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_namelength, this should be ignored as it is implicitly set

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

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

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

Public Members

const MsgIn::In message_in

Provides access to message read functionality inside agent functions

const MsgOut::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

class AgentOut

Public Functions

__device__ inline AgentOut(const Curve::NamespaceHash &aoh, id_t *&d_agent_output_nextID, unsigned int *&scan_flag_agentOutput)
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

  • NVariable name length, this should be ignored as it is implicitly set

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

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

template<typename T, unsigned int N, unsigned int M>
__device__ void setVariable(const char (&variable_name)[M], const 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

  • MVariable name length, this should be ignored as it is implicitly set

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

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

  • DeviceError – If index is out of bounds for the variable array specified by name (flamegpu must be built with 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