Class DeviceAgentVector_impl

Nested Relationships

Nested Types

Inheritance Relationships

Base Type

Class Documentation

class DeviceAgentVector_impl : protected flamegpu::AgentVector

This class provides an AgentVector interface to agent data currently stored on the device during execution of a CUDASimulation

It attempts to prevent unnecessary memory transfers, as copying all agent variable buffers to only use 1 Would result in a large number of redundant but costly memcpys between host and device

See also

HostAgentAPI::getPopulationData()

Note

This class cannot be created directly, you should use one created by HostAgentAPI

Public Types

typedef AgentVector_Agent Agent

View into the AgentVector to provide mutable access to a specific Agent’s data

typedef AgentVector_CAgent CAgent

View into the AgentVector to provide immutable access to a specific Agent’s data

Public Functions

DeviceAgentVector_impl(detail::CUDAAgent &_cuda_agent, const std::string &cuda_agent_state, const VarOffsetStruct &_agentOffsets, std::vector<NewAgentStorage> &_newAgentData, detail::CUDAScatter &scatter, unsigned int streamId, cudaStream_t stream)

Construct a DeviceAgentVector interface to the on-device data of cuda_agent

Parameters:

  • _cuda_agent – CUDAAgent instance holding pointers to the desired agent data

  • cuda_agent_state – Name of the state within cuda_agent to represent.

  • _agentOffsets – Agent offset metadata for storing variable data into NewAgentStorage

  • _newAgentData – Vector of NewAgentStorage to automatically perform host agent birth when appropriate to save later host-device memcpys

  • 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

void syncChanges()

Copy operations are disabled Copies changed agent data back to device

void purgeCache()

Clears the local cache, so data is re-downloaded from the device when next required

Agent at(size_type pos)

Access specified element with bounds checking

Parameters:

pos – position of the element to return

Throws:

std::out_of_range – if !(pos < size())

Returns:

Reference to the requested element.

CAgent at(size_type pos) const

Access specified element with bounds checking

Parameters:

pos – position of the element to return

Throws:

std::out_of_range – if !(pos < size())

Returns:

Reference to the requested element.

Agent front()

Returns a reference to the first element in the container.

Throws:

std::out_of_range – if empty()

Returns:

Reference to the first element

CAgent front() const

Returns a reference to the first element in the container.

Throws:

std::out_of_range – if empty()

Returns:

Reference to the first element

Agent back()

Returns a reference to the last element in the container.

Throws:

std::out_of_range – if empty()

Returns:

Reference to the last element

CAgent back() const

Returns a reference to the last element in the container.

Throws:

std::out_of_range – if empty()

Returns:

Reference to the last element

iterator begin() noexcept

Forward iterator access to the start of the vector

const_iterator begin() const noexcept

Forward iterator access to the start of the vector

iterator end() noexcept

Forward iterator to position after the last element

const_iterator end() const noexcept

Forward iterator to position after the last element

const_iterator cbegin() const noexcept

Forward iterator const access to the start of the vector

const_iterator cend() const noexcept

Forward iterator to position after the last element (Const version of end())

reverse_iterator rbegin() noexcept

Reverse iterator access to the last element of the vector

const_reverse_iterator rbegin() const noexcept

Reverse iterator access to the last element of the vector

reverse_iterator rend() noexcept

Reverse iterator to position before the first element

const_reverse_iterator rend() const noexcept

Reverse iterator to position before the first element

const_reverse_iterator crbegin() const noexcept

Reverse iterator const access to the last element of the vector

const_reverse_iterator crend() const noexcept

Reverse iterator to position before the first element (Const version of rend())

bool empty() const

Checks if the container has no elements, i.e. whether begin() == end()

Returns:

true if the container is empty, false otherwise

size_type size() const

Returns the number of elements in the container, i.e. std::distance(begin(), end())

Returns:

The number of elements in the container.

void reserve(size_type new_cap)

Pre-allocates buffer space for this host vector This does not affect the device allocated buffer, that is updated if necessary when agents are returned to device.

size_type capacity() const

Returns the current capacity of the host vector This does not reflect the capacity of the device allocated buffer

void shrink_to_fit()

Reduces the current capacity to fit the size of the host vector This does not affect the capacity of the device allocated buffer, that is updated if necessary when agents are returned to device.

void clear()

Erases all elements from the container. After this call, size() returns zero.

Invalidates any references, pointers, or iterators referring to contained elements. Any past-the-end iterators are also invalidated.

Leaves the capacity() of the vector unchanged

iterator insert(const_iterator pos, const AgentInstance &value)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

iterator insert(size_type pos, const AgentInstance &value)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

iterator insert(const_iterator pos, const Agent &value)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

iterator insert(size_type pos, const Agent &value)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

iterator insert(const_iterator pos, size_type count, const AgentInstance &value)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

iterator insert(size_type pos, size_type count, const AgentInstance &value)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

iterator insert(const_iterator pos, size_type count, const Agent &value)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

iterator insert(size_type pos, size_type count, const Agent &value)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

template<class InputIt>
iterator insert(const_iterator pos, InputIt first, InputIt last)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

template<class InputIt>
iterator insert(size_type pos, InputIt first, InputIt last)

Inserts elements at the specified location in the container a) Inserts value before pos b) Inserts count copies of the value before pos c) Inserts elements from range [first, last) before pos. The behavior is undefined if first and last are iterators into *this

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Note

Inserted agents will be assigned a new unique ID

Throws:

exception::InvalidAgent – If agent type of value does not match

iterator erase(const_iterator pos)

Erases the specified elements from the container. a) Removes the element at pos. b) Removes the elements in the range [first, last).

Invalidates iterators and references at or after the point of the erase, including the end() iterator.

The iterator pos must be valid and dereferenceable. Thus the end() iterator (which is valid, but is not dereferenceable) cannot be used as a value for pos.

Parameters:

pos – iterator to the element to remove

Throws:

exception::OutOfBoundsException – pos >= size()

Returns:

Iterator following the last removed element

Returns:

If pos refers to the last element, then the end() iterator is returned

iterator erase(size_type pos)

Erases the specified elements from the container. a) Removes the element at pos. b) Removes the elements in the range [first, last).

Invalidates iterators and references at or after the point of the erase, including the end() iterator.

The iterator pos must be valid and dereferenceable. Thus the end() iterator (which is valid, but is not dereferenceable) cannot be used as a value for pos.

Parameters:

pos – iterator to the element to remove

Throws:

exception::OutOfBoundsException – pos >= size()

Returns:

Iterator following the last removed element

Returns:

If pos refers to the last element, then the end() iterator is returned

iterator erase(const_iterator first, const_iterator last)

Erases the specified elements from the container. a) Removes the element at pos. b) Removes the elements in the range [first, last).

Invalidates iterators and references at or after the point of the erase, including the end() iterator.

The iterator pos must be valid and dereferenceable. Thus the end() iterator (which is valid, but is not dereferenceable) cannot be used as a value for pos.

Parameters:

pos – iterator to the element to remove

Throws:

exception::OutOfBoundsException – pos >= size()

Returns:

Iterator following the last removed element

Returns:

If pos refers to the last element, then the end() iterator is returned

iterator erase(size_type first, size_type last)

Erases the specified elements from the container. a) Removes the element at pos. b) Removes the elements in the range [first, last).

Invalidates iterators and references at or after the point of the erase, including the end() iterator.

The iterator pos must be valid and dereferenceable. Thus the end() iterator (which is valid, but is not dereferenceable) cannot be used as a value for pos.

Parameters:

pos – iterator to the element to remove

Throws:

exception::OutOfBoundsException – pos >= size()

Returns:

Iterator following the last removed element

Returns:

If pos refers to the last element, then the end() iterator is returned

void push_back(const AgentInstance &value)

Appends a default initialised agent to the end of the container

Note

Inserted agent will be assigned a new unique ID

void push_back()

Appends a default initialised agent to the end of the container

Note

Inserted agent will be assigned a new unique ID

void pop_back()

Removes the last agent of the container. Calling pop_back on an empty container results in undefined behavior. Iterators and references to the last element, as well as the end() iterator, are invalidated.

void resize(size_type count)

Resizes the vector to contain count agents.

If the current size is greater than count, the container is reduced to its first count elements.

If the current size is less than count, additional default agents are appended

Parameters:

count – size of the container

Public Static Functions

static size_type max_size()

Returns the max theoretical size of this host vector This does not reflect the device allocated buffer

Protected Functions

virtual void _insert(size_type pos, size_type count) override

Triggered when insert() has been called

virtual void _erase(size_type pos, size_type count) override

Triggered when erase() has been called

virtual void _changed(const std::string &variable_name, size_type pos) override

Useful for notifying changes due when a single agent variable has been updated (AgentVector::Agent::setVariable())

Parameters:

  • variable_name – Name of the variable that has been changed

  • pos – The index of the agent that’s variable has been changed

virtual void _changedAfter(const std::string &variable_name, size_type pos) override

Useful for notifying changes due to inserting/removing items, which essentially move all trailing items

Parameters:

  • variable_name – Name of the variable that has been changed

  • pos – The first index that has been changed

virtual void _require(const std::string &variable_name) const override

Notify this that a variable is about to be accessed, to allow it’s data to be synced Should be called by operations which update variables (e.g. AgentVector::Agent::getVariable())

Parameters:

variable_name – Name of the variable that has been changed

virtual void _requireAll() const override

Notify this that all variables are about to be accessed Should be called by operations which move agents (e.g. insert/erase)

Note

This is not called in conjunction with _insert() or _erase()

virtual void _requireLength() const override

Notify that the size is about to be accessed This reflects both whether size is accessed directly or indirectly This will poll HostNewAgent for creations and apply them to the data structure

Protected Attributes

std::map<std::string, std::pair<size_type, size_type>> change_detail

Store information regarding which variables have been changed This map is built as changes come in, it is empty if no changes have been made

mutable std::set<std::string> invalid_variables

Variables included here require data to be updated from the device

Note

Mutable, because it must be updated by _requires(), _requiresAll() which are const as they can be called by const user methods

bool unbound_buffers_has_changed

Store information regarding which variables have been changed This map is built as changes come in, it is empty if no changes have been made