Template Class DeviceAPI

Nested Relationships

Class Documentation

template<typename MessageIn, typename MessageOut>
class flamegpu::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 MessageIn

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

tparam MessageOut

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

Public Functions

__device__ inline DeviceAPI(const detail::curve::Curve::NamespaceHash &instance_id_hash, const detail::curve::Curve::NamespaceHash &agentfuncname_hash, const detail::curve::Curve::NamespaceHash &_agent_output_hash, id_t *&d_agent_output_nextID, 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
  • 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

  • message_in – Input message handler

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

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

class AgentOut

Collection of DeviceAPI functions related to agent birth

Public Functions

__device__ inline AgentOut(const detail::curve::Curve::NamespaceHash &aoh, id_t *&d_agent_output_nextID, unsigned int *&scan_flag_agentOutput)

Constructor

Parameters
  • aoh – Agent output hash (as required for accessing Curve)

  • 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

  • NVariable 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 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 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
  • exception::DeviceError – If name is not a valid variable within the agent (flamegpu must be built with 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 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 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