Class MessageArray

Nested Relationships

Nested Types

Class Documentation

class MessageArray

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

class CDescription : public flamegpu::MessageBruteForce::CDescription

Subclassed by flamegpu::MessageArray::Description

Public Functions

explicit CDescription(std::shared_ptr<Data> data)

CDescription.

Constructor, creates an interface to the MessageData

Parameters:

data – Data store of this message’s data

explicit CDescription(std::shared_ptr<const Data> data)
CDescription(const CDescription &other_agent) = default

Copy constructor Creates a new interface to the same MessageData/ModelData

CDescription(CDescription &&other_agent) = default
CDescription &operator=(const CDescription &other_agent) = default

Assignment operator Assigns this interface to the same MessageData/ModelData

CDescription &operator=(CDescription &&other_agent) = default
bool operator==(const CDescription &rhs) const

Equality operator, checks whether message Description hierarchies are functionally the same

Note

Instead compare pointers if you wish to check that they are the same instance

Parameters:

rhs – right hand side

Returns:

True when messages are the same

bool operator!=(const CDescription &rhs) const

Equality operator, checks whether message Description hierarchies are functionally different

Note

Instead compare pointers if you wish to check that they are not the same instance

Parameters:

rhs – right hand side

Returns:

True when messages are not the same

size_type getLength() const

Const accessors

class CUDAModelHandler : public flamegpu::MessageSpecialisationHandler

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

Public Functions

explicit CUDAModelHandler(detail::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(detail::CUDAScatter &scatter, unsigned int streamId, cudaStream_t stream) 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 – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers

  • stream – The CUDAStream to use for CUDA operations

virtual void buildIndex(detail::CUDAScatter &scatter, unsigned int streamId, 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 – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers

  • stream – The CUDAStream to use for CUDA operations

virtual void allocateMetaDataDevicePtr(cudaStream_t stream) 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 flamegpu::MessageBruteForce::Data

Internal data representation of Array messages within model description hierarchy

See also

Description

Public Functions

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

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

Returns:

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

Public Members

size_type length

Protected Functions

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

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

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

Data.

Normal constructor, only to be called by ModelDescription

Friends

friend class ModelDescription
friend struct ModelData
class Description : public flamegpu::MessageArray::CDescription

User accessible interface to Array messages within mode description hierarchy

See also

Data

Public Functions

explicit Description(std::shared_ptr<Data> data)

Description.

Constructor, creates an interface to the MessageData

Parameters:

data – Data store of this agent’s data

Description(const Description &other_message) = default

Copy constructor Creates a new interface to the same MessageData/ModelData

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

Assignment operator Assigns this interface to the same MessageData/ModelData

Description &operator=(Description &&other_message) = default
void setLength(size_type len)

Accessors

class In

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

Public Functions

__device__ inline In(const void *metadata)

Constructer Initialises member variables

Parameters:

metadata – Reinterpreted as type MessageArray::MetaData to extract length

__device__ inline WrapFilter wrap(const size_type x, 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 The radius will wrap over environment bounds

Note

radius 1 is 2 cells

Note

radius 2 is 4 cells

Note

radius which produce a message read dimension (radius*2 + 1) greater than the length of the messagelist are unsupported

Note

radius of 0 is unsupported

Note

The location x must be within the bounds of the message list

Parameters:

  • x – Search origin x coord

  • radius – Search radius

__device__ inline Filter operator()(const size_type x, 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 The radius will not wrap over environment bounds

Note

radius 1 is 2 cells in 3

Note

radius 2 is 4 cells in 5

Note

radius of 0 is unsupported

Note

The location x must be within the bounds of the message list

Parameters:

  • x – Search origin x coord

  • radius – Search radius

__device__ inline size_type size(void) const

Returns the length of the message list.

__device__ inline Message at(const size_type index) const
class Filter

This class is created when a search origin is provided to MessageArray::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 The radius does not wrap the message list bounds

See also

MessageArray::In::operator()(size_type, size_type)

Public Functions

__device__ inline Filter(size_type _length, size_type x, size_type _radius)

Constructor, takes the search parameters required

Parameters:

  • _length – Pointer to message list length

  • x – Search origin x coord

  • _radius – Search radius

__device__ inline Filter()

A null filter which always returns 0 messages

__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 MessageSpatial3D::In::Filter::Message objects

Public Functions

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

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

See also

MessageArray::In::Operator()(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 also

In::Filter::iterator

Public Functions

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

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 also

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 int getOffsetX() const

Returns the x array offset of message relative to the search origin

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

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

Returns the specified variable array element from the current message attached to the named variable

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 message 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 message (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)

class Message

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

See also

In::at(size_type)

Public Functions

__device__ inline Message(const MessageArray::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 Message(const MessageArray::In &parent)

A null message which always returns the message at index 0

__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 also

operator==(const Message&)

__device__ inline size_type getIndex() const

Returns the index of the message within the full message list

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

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

Returns the specified variable array element from the current message attached to the named variable

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 message 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 message (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)

class WrapFilter

This class is created when a search origin is provided to MessageArray::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 also

MessageArray::In::wrap(size_type, size_type)

Public Functions

__device__ inline WrapFilter(const size_type _length, const size_type x, const size_type _radius)

Constructor, takes the search parameters required

Parameters:

  • _length – Pointer to message list length

  • x – Search origin x coord

  • _radius – Search radius

__device__ inline WrapFilter()

A null filter which always returns 0 messages

__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 MessageSpatial3D::In::WrapFilter::Message objects

Public Functions

__device__ inline iterator(const WrapFilter &parent, const int relative_x)

Constructor This iterator is constructed by MessageArray::In::WrapFilter::begin()(size_type, size_type)

See also

MessageArray::In::wrap(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 also

In::WrapFilter::iterator

Public Functions

__device__ inline Message(const WrapFilter &parent, const int relative_x)

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 also

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 getOffsetX() const

Returns the x array offset of message relative to the search origin

Note

This value is unwrapped, so will always return a value within the search radius

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

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

Returns the specified variable array element from the current message attached to the named variable

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 message 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 message (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)

struct MetaData

MetaData required by brute force during message reads

Public Members

size_type length

Length

class Out

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

Public Functions

__device__ inline Out(const void *_metadata, unsigned int *scan_flag_messageOutput)

Constructer Initialises member variables

Parameters:

  • _metadata – Message specialisation specific metadata struct (of type MessageArray::MetaData)

  • scan_flag_messageOutput – Scan flag array for optional message output

__device__ inline void setIndex(const size_type id) 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

  • value – The value to set the specified 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

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 for this agents message

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 message (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 message (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)

Protected Attributes

unsigned int *scan_flag

Scan flag array for optional message output

const MetaData *const metadata

Metadata struct for accessing messages