Class MsgArray3D

Class Documentation

class MsgArray3D

Array messaging functionality

Like an array, each message is assigned an index within a known range Only one message may exist at each index Agent functions can access individual messages by requesting them with their index

Algorithm: Every agent outputs a message to the array based on their thread index They also set the __index variable with the intended output bin When buildIndex() is called, messages are sorted and errors (multiple messages per bin) are detected

Public Types

typedef MsgNone::size_type size_type

Common size type

class CUDAModelHandler : public MsgSpecialisationHandler

Blank handler, brute force requires no index or special allocations Only stores the length on device

Public Functions

explicit CUDAModelHandler(CUDAMessage &a)

Constructor Allocates memory on device for message list length

Parameters

a – Parent CUDAMessage, used to access message settings, data ptrs etc

inline ~CUDAModelHandler()

Destructor. Should free any local host memory (device memory cannot be freed in destructors)

virtual void init(CUDAScatter &scatter, const unsigned int &streamId) override

Allocates memory for the constructed index. Allocates message buffers, and memsets data to 0

Parameters
  • scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)

  • streamId – Index of stream specific structures used

virtual void buildIndex(CUDAScatter &scatter, const unsigned int &streamId, const cudaStream_t &stream) override

Sort messages according to index Detect and report any duplicate indicies/gaps

Parameters
  • scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)

  • streamId – Index of stream specific structures used

virtual void allocateMetaDataDevicePtr() override

Allocates memory for the constructed index. The memory allocation is checked by build index.

virtual void freeMetaDataDevicePtr() override

Releases memory for the constructed index.

inline virtual const void *getMetaDataDevicePtr() const override

Returns a pointer to the metadata struct, this is required for reading the message data

struct Data : public MsgBruteForce::Data

Internal data representation of Array messages within model description hierarchy

See

Description

Public Functions

virtual ~Data() = default
virtual std::unique_ptr<MsgSpecialisationHandler> getSpecialisationHander(CUDAMessage &owner) const override
virtual std::type_index getType() const override

Used internally to validate that the corresponding Msg type is attached via the agent function shim.

Returns

The std::type_index of the Msg type which must be used.

Public Members

std::array<size_type, 3> dimensions

Protected Functions

virtual Data *clone(const std::shared_ptr<const ModelData> &newParent) override
Data(const std::shared_ptr<const ModelData>&, const Data &other)

Copy constructor This is unsafe, should only be used internally, use clone() instead

Data(const std::shared_ptr<const ModelData>&, const std::string &message_name)

Normal constructor, only to be called by ModelDescription

Friends

friend class ModelDescription
friend struct ModelData
class Description : public MsgBruteForce::Description

User accessible interface to Array messages within mode description hierarchy

See

Data

Public Functions

void setDimensions(const size_type &len_x, const size_type &len_y, const size_type &len_Z)
void setDimensions(const std::array<size_type, 3> &dims)
std::array<size_type, 3> getDimensions() const
size_type getDimX() const
size_type getDimY() const
size_type getDimZ() const

Protected Functions

Description(const std::shared_ptr<const ModelData> &_model, Data *const data)

Constructors

Description(const Description &other_message) = delete

Default copy constructor, not implemented

Description(Description &&other_message) noexcept = delete

Default move constructor, not implemented

Description &operator=(const Description &other_message) = delete

Default copy assignment, not implemented

Description &operator=(Description &&other_message) noexcept = delete

Default move assignment, not implemented

class In

This class is accessible via DeviceAPI.message_in if MsgArray3D is specified in FLAMEGPU_AGENT_FUNCTION It gives access to functionality for reading array messages

Public Functions

__device__ inline In(Curve::NamespaceHash agentfn_hash, Curve::NamespaceHash msg_hash, const void *_metadata)

Constructer Initialises member variables

Parameters
  • agentfn_hash – Added to msg_hash to produce combined_hash

  • msg_hash – Added to agentfn_hash to produce combined_hash

  • _metadata – Reinterpreted as type MsgArray3D::MetaData

__device__ inline Filter operator()(const size_type &x, const size_type &y, const size_type &z, const size_type &radius = 1) const

Returns a Filter object which provides access to message iterator for iterating a subset of messages including those within the radius of the search origin this excludes the message at the search origin

Note

radius 1 is 26 cells in 3x3x3

Note

radius 2 is 124 cells in 5x5x5

Note

If radius is >= half of the array dimensions, cells will be doubly read

Note

radius of 0 is unsupported

Parameters
  • x – Search origin x coord

  • y – Search origin y coord

  • z – Search origin y coord

  • radius – Search radius

__device__ inline size_type getDimX() const

Returns the x dimension size of the message list

__device__ inline size_type getDimY() const

Returns the y dimension size of the message list

__device__ inline size_type getDimZ() const

Returns the z dimension size of the message list

__device__ inline size_type size(void) const

Returns the length of the message list. xDim x yDim x zDim

__device__ inline Message at(const size_type &x, const size_type &y, const size_type &z) const
class Filter

This class is created when a search origin is provided to MsgArray2D::In::operator()(size_type, size_type, size_type = 1) It provides iterator access to a subset of the full message list, according to the provided search origin and radius

See

MsgArray2D::In::operator()(size_type, size_type, size_type)

Public Functions

__device__ inline Filter(const MetaData *_metadata, const Curve::NamespaceHash &_combined_hash, const size_type &x, const size_type &y, const size_type &z, const size_type &_radius)

Constructor, takes the search parameters requried

Parameters
  • _metadata – Pointer to message list metadata

  • _combined_hash – agentfn+message hash for accessing message data

  • x – Search origin x coord

  • y – Search origin y coord

  • z – Search origin z coord

  • _radius – Search radius

__device__ inline iterator begin(void) const

Returns an iterator to the start of the message list subset about the search origin

__device__ inline iterator end(void) const

Returns an iterator to the position beyond the end of the message list subset

Note

This iterator is the same for all message list subsets

class iterator

Stock iterator for iterating MsgSpatial3D::In::Filter::Message objects

Public Functions

__device__ inline iterator(const Filter &parent, const int &relative_x, const int &relative_y, const int &relative_z)

Constructor This iterator is constructed by MsgArray3D::In::Filter::begin()(size_type, size_type, size_type, size_type)

See

MsgArray3D::In::Operator()(size_type, size_type, size_type, size_type)

__device__ inline iterator &operator++()

Moves to the next message (Prefix increment operator)

__device__ inline iterator operator++(int)

Moves to the next message (Postfix increment operator, returns value prior to increment)

__device__ inline bool operator==(const iterator &rhs) const

Equality operator Compares message

__device__ inline bool operator!=(const iterator &rhs) const

Inequality operator Compares message

__device__ inline Message &operator*()

Dereferences the iterator to return the message object, for accessing variables

__device__ inline Message *operator->()

Dereferences the iterator to return the message object, for accessing variables

class Message

Provides access to a specific message Returned by the iterator

See

In::Filter::iterator

Public Functions

__device__ inline Message(const Filter &parent, const int &relative_x, const int &relative_y, const int &relative_z)

Constructs a message and directly initialises all of it’s member variables

Note

See member variable documentation for their purposes

__device__ inline bool operator==(const Message &rhs) const

Equality operator Compares all internal member vars for equality

Note

Does not compare _parent

__device__ inline bool operator!=(const Message &rhs) const

Inequality operator Returns inverse of equality operator

See

operator==(const Message&)

__device__ inline Message &operator++()

Updates the message to return variables from the next cell in the Moore neighbourhood

Returns

Returns itself

__device__ inline size_type getX() const

Returns x array index of message

__device__ inline size_type getY() const

Returns y array index of message

__device__ inline size_type getZ() const

Returns z array index of message

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

Returns the value for the current message attached to the named variable

Parameters

variable_name – Name of the variable

Template Parameters
  • T – type of the variable

  • N – Length of variable name (this should be implicit if a string literal is passed to variable name)

Returns

The specified variable, else 0x0 if an error occurs

class Message

Provides access to a specific message Returned by In::at(size_type)

See

In::at(size_type)

Public Functions

__device__ inline Message(const MsgArray3D::In &parent, const size_type &_index)

Constructs a message and directly initialises all of it’s member variables index is always init to 0

Note

See member variable documentation for their purposes

__device__ inline bool operator==(const Message &rhs) const

Equality operator Compares all internal member vars for equality

Note

Does not compare _parent

__device__ inline bool operator!=(const Message &rhs) const

Inequality operator Returns inverse of equality operator

See

operator==(const Message&)

__device__ inline size_type getIndex() const

Returns the index of the message within the full message list

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

Returns the value for the current message attached to the named variable

Parameters

variable_name – Name of the variable

Template Parameters
  • T – type of the variable

  • N – Length of variable name (this should be implicit if a string literal is passed to variable name)

Returns

The specified variable, else 0x0 if an error occurs

struct MetaData

MetaData required by brute force during message reads

Public Members

size_type dimensions[3]

Dimensions of array

size_type length

Total number of elements

class Out

This class is accessible via DeviceAPI.message_out if MsgArray3D is specified in FLAMEGPU_AGENT_FUNCTION It gives access to functionality for outputting array messages

Public Functions

__device__ inline Out(Curve::NamespaceHash agentfn_hash, Curve::NamespaceHash msg_hash, const void *_metadata, unsigned int *scan_flag_messageOutput)

Constructer Initialises member variables

Parameters
  • agentfn_hash – Added to msg_hash to produce combined_hash

  • msg_hash – Added to agentfn_hash to produce combined_hash

  • scan_flag_messageOutput – Scan flag array for optional message output

__device__ inline void setIndex(const size_type &x, const size_type &y, const size_type &z) const

Sets the array index to store the message in

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

Sets the specified variable for this agents message

Parameters

variable_name – Name of the variable

Template Parameters
  • T – type of the variable

  • N – Length of variable name (this should be implicit if a string literal is passed to variable name)

Returns

The specified variable, else 0x0 if an error occurs

Protected Attributes

Curve::NamespaceHash combined_hash

CURVE hash for accessing message data agentfn_hash + msg_hash

unsigned int *scan_flag

Scan flag array for optional message output

const MetaData *const metadata

Metadata struct for accessing messages