Class AgentVector

Nested Relationships

Nested Types

Inheritance Relationships

Derived Type

Class Documentation

class AgentVector

Vector of agent data for a single type of Agent The interface is designed to work similar to std::vector AgentVector has no concept of agent states, if you wish to represent agents in two states, you need two AgentVectors

Subclassed by flamegpu::DeviceAgentVector_impl

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

typedef std::map<std::string, std::unique_ptr<detail::GenericMemoryVector>> AgentDataMap

Public Functions

explicit AgentVector(const CAgentDescription &agent_desc, size_type count = 0)

Constructs the container with count copies of the agent described by agent_desc initialised with the default values specified by agent_desc.

Parameters:

  • agent_desc – agent_desc Agent description specifying the agent variables to be represented

  • count – The size of the container

explicit AgentVector(const AgentData &agent_desc, size_type count = 0)
AgentVector(const AgentVector &other)

Copy constructor. Constructs the container with the copy of the contents of other

Note

The newly created agent copies will have their IDs updated to new unique values

Parameters:

other – another container to be used as source to initialize the elements of the container with

AgentVector(AgentVector &&other) noexcept

Move constructor Constructs the container with the contents of other using move semantics. other is left in an empty but functional state.

Parameters:

other – another container to be used as source to initialize the elements of the container with

AgentVector &operator=(const AgentVector &other)

Copy assignment operator. Replaces the contents with a copy of the contents of other

AgentVector &operator=(AgentVector &&other) noexcept

Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is left in an empty but functional state.

virtual ~AgentVector() = default

Default destructor, all memory should be automatically managed.

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
Agent operator[](size_type pos)

Returns a reference to the element at specified location pos.

Parameters:

pos – position of the element to return

Throws:

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

Returns:

Reference to the requested element.

CAgent operator[](size_type pos) const
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
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
template<typename T>
T *data(const std::string &variable_name)

Returns pointer to the underlying array serving as element storage for the named variable.

Note

Returns nullptr if vector is has not yet allocated buffers.

Parameters:

variable_name – Name of the variable array to return

Throws:

  • exception::InvalidAgentVar – Agent does not contain variable variable_name

  • exception::InvalidVarType – Agent variable variable_name is not of type T

template<typename T>
const T *data(const std::string &variable_name) const
void *data(const std::string &variable_name)
const void *data(const std::string &variable_name) const
iterator begin() noexcept

Forward iterator access to the start of the vector

const_iterator begin() const noexcept

Forward iterator const access to the start of the vector

const_iterator cbegin() const noexcept

Forward iterator const 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 version of end())

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 const access to the last element of the vector

const_reverse_iterator crbegin() const noexcept

Reverse iterator const 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 version of rend())

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)

Increase the capacity of the vector to a value that’s greater or equal to new_cap. If new_cap is greater than the current capacity(), new storage is allocated, otherwise the method does nothing.

reserve() does not change the size of the vector.

If new_cap is greater than capacity(), all iterators, including the past-the-end iterator, and all AgentViews are invalidated. Otherwise, no iterators or references are invalidated.

Parameters:

new_cap – new capacity of the vector

Throws:

std::length_error – if new_cap > max_size().

size_type capacity() const

Returns the number of elements that the container has currently allocated space for.

Returns:

Capacity of the currently allocated storage.

void shrink_to_fit()

Requests the removal of unused capacity.

If reallocation occurs, all iterators, including the past the end iterator, and all references to the elements are invalidated. If no reallocation takes place, no iterators or references are invalidated.

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

void resetAllIDs()

Sets the ID of all agents currently inside the vector to the unset flag

Note

The ID will only not have the unset flag, if the agents have been taken from a simulation which has executed

iterator insert(const_iterator pos, const AgentInstance &value)

Inserts elements at the specified location in the container Inserts value before pos

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

The newly insert agent will have their ID updated to a new unique value

Throws:

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

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

Inserts elements at the specified location in the container Inserts count copies of the value before pos

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

The newly inserted agent copies will have their IDs updated to new unique values

Throws:

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

iterator insert(size_type pos, size_type count, const AgentInstance &value)
iterator insert(const_iterator pos, size_type count, const Agent &value)
iterator insert(size_type pos, size_type count, const Agent &value)
template<class InputIt>
iterator insert(const_iterator pos, InputIt first, InputIt last)

Inserts elements at the specified location in the container 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

The newly inserted agents will have their IDs updated to new unique values

Throws:

exception::InvalidAgent – If agent type of first or last does not match

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

Erases the specified elements from the container. Removes the element at pos.

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)
iterator erase(const_iterator first, const_iterator last)

Erases the specified elements from the container. 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 first does not need to be dereferenceable if first==last: erasing an empty range is a no-op.

Parameters:

  • first – Iterator to the first item of the range of elements to remove

  • last – Iterator to after the last item of the range of elements to remove

Throws:
Returns:

Iterator following the last removed element

Returns:

if last==end() prior to removal,then the updated end() iterator is returned.

Returns:

if [first, last) is an empty range, then last is returned

iterator erase(size_type first, size_type last)
void push_back(const AgentInstance &value)

Appends the given agent to the end of the container. The new element is initialized as a copy of value

If the new size() is greater than capacity() then all iterators and references (including the past-the-end iterator) are invalidated. Otherwise only the past-the-end iterator is invalidated.

Note

The newly inserted agent will have a unique ID generated

Parameters:

value – the value of the agent to append

Throws:

exception::InvalidAgent – If the agent type of the AgentInstance doesn’t match the agent type of the AgentVector

void push_back()

Appends a default initialised agent to the end of the container

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

void swap(AgentVector &other) noexcept

Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.

bool operator==(const AgentVector &other) const

Checks if the contents of lhs and rhs are equal, that is, they have the same number of elements and each element in lhs compares equal with the element in rhs at the same position.

bool operator!=(const AgentVector &other) const
inline std::string getAgentName() const

Returns the agent name from the internal agent description

bool matchesAgentType(const AgentData &other) const

Returns true, if the provided agent description matches the internal agent description of the vector

bool matchesAgentType(const CAgentDescription &other) const
std::type_index getVariableType(const std::string &variable_name) const

Returns the type_index of the named variable

Throws:

exception::InvalidAgentVar – When variable_name is not valid

const VariableMap &getVariableMetaData() const

Returns the full map of variable metadata from the internal agent description

std::string getInitialState() const

Returns the initial state of the internal agent description

Public Static Functions

static size_type max_size()

Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the largest container.

Note

This value typically reflects the theoretical limit on the size of the container, at most std::numeric_limits<difference_type>::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available.

Returns:

Maximum number of elements.

Protected Functions

inline virtual void _insert(size_type pos, size_type count)

This is called after insert operations to notify sub-classes of data movement.

Parameters:

  • pos – Index in the array that first agent was inserts

  • count – Number of agents inserted

inline virtual void _erase(size_type pos, size_type count)

This is called after erase operations to notify sub-classes of data movement.

Parameters:

  • pos – Index in the array of first agent that was erased

  • count – Number of agents erased

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

This is called to notify sub-classes that a variable (may have/) has been changed

Parameters:

  • variable_name – Name of the affected variable

  • pos – Index of the variables agent

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

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

Note

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

Parameters:

  • variable_name – Name of the variable that has been changed

  • pos – The first index that has been changed

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

Notify any subclasses 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

inline virtual void _requireAll() const

Notify any subclasses 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()

inline virtual void _requireLength() const

Notify that the size is about to be accessed This reflects both whether size is accessed directly or indirectly

Note

This exists so DeviceAgentVector can poll HostNewAgent for creations and apply them to the data structure

void internal_resize(size_type count, bool init)

Notify any subclasses 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()

void init(size_type first, size_type last)

Overwrite all variable buffers in the specified range with default values

Parameters:

  • first – Index to first index to overwrite

  • last – Index after the last index to overwrite

Throws:

Protected Attributes

std::shared_ptr<const AgentData> agent
mutable size_type _size
mutable size_type _capacity
std::shared_ptr<AgentDataMap> _data

Friends

friend class detail::CUDAAgentStateList
class const_iterator

Basic AgentVectors forward const iterator Provides const access to members of the vector, in front-to-back order.

See also

AgentVector::cbegin()

See also

AgentVector::cend()

Public Functions

inline const_iterator(AgentVector *parent, const std::shared_ptr<const AgentData> &agent, std::weak_ptr<AgentDataMap> data, size_type pos = 0)
inline const_iterator &operator++()
inline const_iterator operator++(int)
inline bool operator==(const_iterator other) const
inline bool operator!=(const_iterator other) const
CAgent operator*() const
class const_reverse_iterator

Basic AgentVectors reverse const iterator Provides const access to members of the vector, in back-to-front order.

See also

AgentVector::crbegin()

See also

AgentVector::crend()

Public Functions

inline explicit const_reverse_iterator(AgentVector *parent, const std::shared_ptr<const AgentData> &agent, std::weak_ptr<AgentDataMap> data, size_type pos = 0)
inline const_reverse_iterator &operator++()
inline const_reverse_iterator operator++(int)
inline bool operator==(const_reverse_iterator other) const
inline bool operator!=(const_reverse_iterator other) const
CAgent operator*() const
class iterator

Basic AgentVectors forward iterator Provides access to members of the vector, in front-to-back order.

See also

AgentVector::begin()

See also

AgentVector::end()

Public Functions

inline operator AgentVector::const_iterator() const
inline iterator(AgentVector *parent, const std::shared_ptr<const AgentData> &agent, std::weak_ptr<AgentDataMap> data, size_type pos = 0)
inline iterator &operator++()
inline iterator operator++(int)
inline bool operator==(iterator other) const
inline bool operator!=(iterator other) const
Agent operator*() const
class reverse_iterator

Basic AgentVectors reverse iterator Provides access to members of the vector, in back-to-front order.

See also

AgentVector::rbegin()

See also

AgentVector::rend()

Public Functions

inline operator AgentVector::const_reverse_iterator() const
inline explicit reverse_iterator(AgentVector *parent, const std::shared_ptr<const AgentData> &agent, std::weak_ptr<AgentDataMap> data, size_type pos = 0)
inline reverse_iterator &operator++()
inline reverse_iterator operator++(int)
inline bool operator==(reverse_iterator other) const
inline bool operator!=(reverse_iterator other) const
Agent operator*() const