Stable handle to a generic value. More...

#include <data_handle.hpp>

Public Member Functions
	data_handle ()=default

	data_handle (T *raw_ptr)
	Construct a data_handle from a plain pointer. More...

	data_handle (do_not_search_t, T *raw_ptr)
	Create a data_handle<T> wrapping the raw T*. More...

data_handle	next_array_element (int shift=1) const
	Get a data handle to a different element of the same array variable. More...

bool	refers_to_a_modern_data_structure () const
	Query whether this data handle is in "modern" mode. More...

	data_handle (non_owning_identifier_without_container offset, T const container, int array_dim, int array_index)

	operator bool () const

template<typename Tag , typename Container >
bool	refers_to (Container const &container) const
	Query whether this generic handle points to a value from the `Tag` field of the given container. More...

std::size_t	current_row () const
	Get the current logical row number. More...

T &	operator* ()

T const &	operator* () const

	operator T* ()

	operator T const * () const

non_owning_identifier_without_container	identifier () const
	Get the identifier used by this handle. More...

Private Member Functions
T *	raw_ptr ()

T const *	raw_ptr () const

T *	container_data ()

T const *	container_data () const

Static Private Member Functions
template<typename This >
static auto	get_ptr_helper (This &this_ref)

Private Attributes
non_owning_identifier_without_container	m_offset {}

void *	m_container_or_raw_ptr {}

int	m_array_dim {1}

int	m_array_index {}

Friends
struct	generic_data_handle

struct	std::hash< data_handle >

std::ostream &	operator<< (std::ostream &os, data_handle const &dh)

bool	operator== (data_handle const &lhs, data_handle const &rhs)

bool	operator!= (data_handle const &lhs, data_handle const &rhs)

Detailed Description

template<typename T>
struct neuron::container::data_handle< T >

Stable handle to a generic value.

Without this type one can already hold a Node::handle foo and call something like foo.v() to get that Node's voltage in a way that is stable against permutations of the underlying data. The data_handle concept is intended to be used if we want to erase the detail that the quantity is a voltage, or that it belongs to a Node, and simply treat it as a floating-point value that we may want to dereference later – essentially a substitute for double*.

Implementation: like Node::handle we can store a std::size_t* that we dereference to find out either:

the current offset in the underlying container, or
that the object being referred to (e.g. a Node) no longer exists

Assuming nothing has been invalidated, we have an offset, a type, and the fundamental assumption behind all of this that the underlying data are contiguous – we "just" need to know the address of the start of the underlying storage vector without adding specific type information (like Node) to this class. The simplest way of doing this is to assume that the underlying storage is always std::vector<T> (or a custom allocator that is always the same type in neuron::container::*). Note that storing T* or span<T> would not work if the underlying storage is reallocated.

Todo:: Const correctness – data_handle should be like span: data_handle<double> can read + write the value, data_handle<double const> can only read the value. const applied to the data_handle itself should just control whether or not it can be rebound to refer elsewhere.

Definition at line 61 of file data_handle.hpp.

Constructor & Destructor Documentation

◆ data_handle() [1/4]

template<typename T >

neuron::container::data_handle< T >::data_handle ( )

default

◆ data_handle() [2/4]

template<typename T >

neuron::container::data_handle< T >::data_handle ( T * raw_ptr )

inlineexplicit

Construct a data_handle from a plain pointer.

Definition at line 66 of file data_handle.hpp.

◆ data_handle() [3/4]

template<typename T >

neuron::container::data_handle< T >::data_handle	(	do_not_search_t	,
		T *	raw_ptr
	)

inline

Create a data_handle<T> wrapping the raw T*.

Unlike the constructor taking T*, this does not attempt to promote raw pointers to modern data_handles.

Definition at line 91 of file data_handle.hpp.

◆ data_handle() [4/4]

template<typename T >

neuron::container::data_handle< T >::data_handle	(	non_owning_identifier_without_container	offset,
		T const	container,
		int	array_dim,
		int	array_index
	)

inline

Definition at line 134 of file data_handle.hpp.

Member Function Documentation

◆ container_data() [1/2]

template<typename T >

T* neuron::container::data_handle< T >::container_data ( )

inlineprivate

Definition at line 190 of file data_handle.hpp.

◆ container_data() [2/2]

template<typename T >

T const* neuron::container::data_handle< T >::container_data ( ) const

inlineprivate

Definition at line 193 of file data_handle.hpp.

◆ current_row()

template<typename T >

std::size_t neuron::container::data_handle< T >::current_row ( ) const

inline

Get the current logical row number.

Definition at line 175 of file data_handle.hpp.

◆ get_ptr_helper()

template<typename T >

template<typename This >

static auto neuron::container::data_handle< T >::get_ptr_helper ( This & this_ref )

inlinestaticprivate

Definition at line 197 of file data_handle.hpp.

◆ identifier()

template<typename T >

non_owning_identifier_without_container neuron::container::data_handle< T >::identifier ( ) const

inline

Get the identifier used by this handle.

This is likely to only be useful for the (hopefully temporary) method neuron::container::notify_when_handle_dies.

Definition at line 311 of file data_handle.hpp.

◆ next_array_element()

template<typename T >

data_handle neuron::container::data_handle< T >::next_array_element ( int shift = 1 ) const

inline

Get a data handle to a different element of the same array variable.

Given an array variable a[N], this method allows a handle to a[i] to yield a handle to a[j] within the same logical row. If the handle is wrapping a raw pointer T*, the shift is applied to that raw pointer.

Definition at line 101 of file data_handle.hpp.

◆ operator bool()

template<typename T >

neuron::container::data_handle< T >::operator bool ( ) const

inlineexplicit

Definition at line 143 of file data_handle.hpp.

◆ operator T const *()

template<typename T >

neuron::container::data_handle< T >::operator T const * ( ) const

inlineexplicit

Definition at line 247 of file data_handle.hpp.

◆ operator T*()

template<typename T >

neuron::container::data_handle< T >::operator T* ( )

inlineexplicit

Definition at line 243 of file data_handle.hpp.

◆ operator*() [1/2]

template<typename T >

T& neuron::container::data_handle< T >::operator* ( )

inline

Definition at line 221 of file data_handle.hpp.

◆ operator*() [2/2]

template<typename T >

T const& neuron::container::data_handle< T >::operator* ( ) const

inline

Definition at line 232 of file data_handle.hpp.

◆ raw_ptr() [1/2]

template<typename T >

T* neuron::container::data_handle< T >::raw_ptr ( )

inlineprivate

Definition at line 184 of file data_handle.hpp.

◆ raw_ptr() [2/2]

template<typename T >

T const* neuron::container::data_handle< T >::raw_ptr ( ) const

inlineprivate

Definition at line 187 of file data_handle.hpp.

◆ refers_to()

template<typename T >

template<typename Tag , typename Container >

bool neuron::container::data_handle< T >::refers_to ( Container const & container ) const

inline

Query whether this generic handle points to a value from the Tag field of the given container.

Definition at line 160 of file data_handle.hpp.

◆ refers_to_a_modern_data_structure()

template<typename T >

bool neuron::container::data_handle< T >::refers_to_a_modern_data_structure ( ) const

inline

Query whether this data handle is in "modern" mode.

Returns: true if the handle was created as a permutation-stable handle to an soa<...> data structure, otherwise false.

Note that this does not mean that the handle is still valid. The referred-to row and/or column may have gone away in the meantime.

Definition at line 126 of file data_handle.hpp.

Friends And Related Function Documentation

◆ generic_data_handle

template<typename T >

friend struct generic_data_handle

friend

Definition at line 316 of file data_handle.hpp.

◆ operator!=

template<typename T >

bool operator!=	(	data_handle< T > const &	lhs,
		data_handle< T > const &	rhs
	)

friend

Definition at line 301 of file data_handle.hpp.

◆ operator<<

template<typename T >

std::ostream& operator<<	(	std::ostream &	os,
		data_handle< T > const &	dh
	)

friend

Definition at line 251 of file data_handle.hpp.

◆ operator==

template<typename T >

bool operator==	(	data_handle< T > const &	lhs,
		data_handle< T > const &	rhs
	)

friend

Definition at line 295 of file data_handle.hpp.

◆ std::hash< data_handle >

template<typename T >

friend struct std::hash< data_handle >

friend

Definition at line 316 of file data_handle.hpp.

Member Data Documentation

◆ m_array_dim

template<typename T >

int neuron::container::data_handle< T >::m_array_dim {1}

private

Definition at line 326 of file data_handle.hpp.

◆ m_array_index

template<typename T >

int neuron::container::data_handle< T >::m_array_index {}

private

Definition at line 326 of file data_handle.hpp.

◆ m_container_or_raw_ptr

template<typename T >

void* neuron::container::data_handle< T >::m_container_or_raw_ptr {}

private

Definition at line 322 of file data_handle.hpp.

◆ m_offset

template<typename T >

non_owning_identifier_without_container neuron::container::data_handle< T >::m_offset {}

private

Definition at line 318 of file data_handle.hpp.

The documentation for this struct was generated from the following file:

/home/docs/checkouts/readthedocs.org/user_builds/nrn/checkouts/latest/src/neuron/container/data_handle.hpp

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Detailed Description

template<typename T> struct neuron::container::data_handle< T >

Constructor & Destructor Documentation

◆ data_handle() [1/4]

◆ data_handle() [2/4]

◆ data_handle() [3/4]

◆ data_handle() [4/4]

Member Function Documentation

◆ container_data() [1/2]

◆ container_data() [2/2]

◆ current_row()

◆ get_ptr_helper()

◆ identifier()

◆ next_array_element()

◆ operator bool()

◆ operator T const *()

◆ operator T*()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ raw_ptr() [1/2]

◆ raw_ptr() [2/2]

◆ refers_to()

◆ refers_to_a_modern_data_structure()

Friends And Related Function Documentation

◆ generic_data_handle

◆ operator!=

◆ operator<<

◆ operator==

◆ std::hash< data_handle >

Member Data Documentation

◆ m_array_dim

◆ m_array_index

◆ m_container_or_raw_ptr

◆ m_offset

template<typename T>
struct neuron::container::data_handle< T >