Class MessageBucket

• Defined in File MessageBucket.h

Nested Relationships

Nested Types

• Class MessageBucket::CUDAModelHandler

• Struct MessageBucket::Data

• Class MessageBucket::Description

• Class MessageBucket::In

• Class In::Filter

• Class Filter::Message

• Class Filter::iterator

• Struct MessageBucket::MetaData

• Class MessageBucket::Out

Class Documentation

class flamegpu::MessageBucket

Bucket messaging functionality

User specifies an integer upper and lower bound, these form a set of consecutive indices which act as keys to buckets. Each bucket may contain 0 to many messages, however an index is generated such that empty bins still consume a small amount of space. As such, this is similar to a multi-map, however the key space must be a set of consecutive integers.

By using your own hash function you can convert non-integer keys to suitable integer keys.

Public Types

typedef MessageNone::size_type size_type

Common size type

class CUDAModelHandler : public flamegpu::MessageSpecialisationHandler

CUDA host side handler of bucket messages Allocates memory for and constructs PBM

Public Functions

explicit CUDAModelHandler(CUDAMessage &a)

Constructor

Initialises metadata, decides PBM size etc

Parameters

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

~CUDAModelHandler() override

Destructor Frees all allocated memory

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

Allocates memory for the constructed index. Sets data asthough message list is empty

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

Reconstructs the partition boundary matrix This should be called before reading newly output messages

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 – CUDA stream to be used for async CUDA operations

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 flamegpu::MessageBruteForce::Data

Internal data representation of Bucket messages within model description hierarchy

See

Description

Public Functions

virtual ~Data() = default

virtual std::unique_ptr<MessageSpecialisationHandler> getSpecialisationHander(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

IntT lowerBound

Initially set to 0 Min must be set to the first valid key

IntT upperBound

Initially set to std::numeric_limits<IntT>::max(), which acts as flag to say it has not been set Max must be set to the last valid key

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 flamegpu::MessageBruteForce::Description

User accessible interface to Bucket messages within mode description hierarchy

See

Data

Public Functions

void setLowerBound(const IntT &key)

Set the (inclusive) minimum bound, this is the first valid key

void setUpperBound(const IntT &key)

Set the (inclusive) maximum bound, this is the last valid key

void setBounds(const IntT &min, const IntT &max)

IntT getLowerBound() const

Return the currently set (inclusive) lower bound, this is the first valid key

IntT getUpperBound() const

Return the currently set (inclusive) upper bound, this is the last valid key

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 MessageBucket is specified in FLAMEGPU_AGENT_FUNCTION It gives access to functionality for reading bucket

Public Functions

__device__ inline In(detail::curve::Curve::NamespaceHash agentfn_hash, detail::curve::Curve::NamespaceHash message_hash, const void *_metadata)

Constructor Initialises member variables

Parameters

• agentfn_hash – Added to message_hash to produce combined_hash

• message_hash – Added to agentfn_hash to produce combined_hash

• _metadata – Reinterpreted as type MessageBucket::MetaData

__device__ inline Filter operator()(const IntT &key) const

Returns a Filter object which provides access to message iterator for iterating a subset of messages stored within the specified bucket

Parameters

key – The bucket to access

__device__ inline Filter operator()(const IntT &beginKey, const IntT &endKey) const

Returns a Filter object which provides access to message iterator for iterating a subset of messages within the [begin, end) range of buckets specified.

Parameters

• beginKey – The first bin to access messages from

• endKey – The bin beyond the last bin to access messages from

class Filter

This class is created when a search origin is provided to MessageBucket::In::operator()(IntT) It provides iterator access to the subset of messages found within the specified bucket

See

MessageBucket::In::operator()(IntT)

Public Functions

__device__ inline Filter(const MetaData *_metadata, const detail::curve::Curve::NamespaceHash &combined_hash, const IntT &beginKey, const IntT &endKey)

Constructor, takes the search parameters required Begin key and end key specify the [begin, end) contiguous range of bucket. (inclusive begin, exclusive end)

Parameters

• _metadata – Pointer to message list metadata

• combined_hash – agentfn+message hash for accessing message data

• beginKey – Inclusive first bucket of range to access

• endKey – Exclusive final bucket of range to access, this is the final bucket + 1

__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

__device__ inline IntT size(void) const

Returns the number of messages in the filtered bucket

class iterator

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

Public Functions

__device__ inline iterator(const Filter &parent, const IntT &cell_index)

Constructor This iterator is constructed by MessageBucket::In::Filter::begin()(IntT)

See

MessageBucket::In::Operator()(IntT)

__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 IntT &_cell_index)

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 message in the message list

Returns

Returns itself

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

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

struct MetaData

MetaData required by bucket messaging during message reads

Public Members

IntT min

The inclusive minimum environment bound

IntT max

The exclusive maximum environment bound

unsigned int *PBM

Pointer to the partition boundary matrix in device memory The PBM is never stored on the host

class Out : public flamegpu::MessageBruteForce::Out

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

Public Functions

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

Constructor Initialises member variables

Parameters

• agentfn_hash – Added to message_hash to produce combined_hash

• message_hash – Added to agentfn_hash to produce combined_hash

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

• scan_flag_messageOutput – Scan flag array for optional message output

__device__ inline void setKey(const IntT &key) const

Sets the location for this agents message

Note

Convenience wrapper for setVariable()

Parameters

key – Key of the bucket to store the message

Public Members

const MetaData *const metadata

Metadata struct for accessing messages