Class MessageBucket¶

Defined in File MessageBucket.h

Nested Relationships¶

Nested Types¶

Class Documentation¶

class 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.

class CDescription : public flamegpu::MessageBruteForce::CDescription ¶

Subclassed by flamegpu::MessageBucket::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

IntT getLowerBound() const¶

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

Const accessors

IntT getUpperBound() const¶: Return the currently set (inclusive) upper bound, this is the last valid key

class CUDAModelHandler : public flamegpu::MessageSpecialisationHandler ¶

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

Public Functions

explicit CUDAModelHandler(detail::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(detail::CUDAScatter &scatter, unsigned int streamId, cudaStream_t stream) 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
stream – The CUDAStream to use for CUDA operations

virtual void buildIndex(detail::CUDAScatter &scatter, unsigned int streamId, 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 – 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 Bucket 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

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(std::shared_ptr<const ModelData>, const Data &other)¶: Copy constructor This is unsafe, should only be used internally, use clone() instead

Data(std::shared_ptr<const ModelData>, 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::MessageBucket::CDescription ¶

User accessible interface to Bucket 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 setLowerBound(IntT key)¶

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

Accessors

void setUpperBound(IntT key)¶: Set the (inclusive) maximum bound, this is the last valid key

void setBounds(IntT min, const IntT max)¶

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(const void *_metadata)¶

Constructor Initialises member variables

Parameters:: _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 also

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

Public Functions

__device__ inline Filter(const MetaData *_metadata, 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
beginKey – Inclusive first bucket of range to access
endKey – Exclusive final bucket of range to access, this is the final bucket + 1

__device__ inline Filter()¶: Creates 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

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

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 also

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 also

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, 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 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(const void *_metadata, unsigned int *scan_flag_messageOutput)¶

Constructor Initialises member variables

Parameters:

_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