SG::AuxVectorData Class Reference

Manage lookup of vectors of auxiliary data. More...

#include <AuxVectorData.h>

Inheritance diagram for SG::AuxVectorData:

Classes
class	Cache
	Manage cache of pointers to aux element vectors.
Public Member Functions
	AuxVectorData ()
	Constructor.
virtual	~AuxVectorData ()
	Destructor.
virtual size_t	size_v () const =0
	Return the size of the container.
virtual size_t	capacity_v () const =0
	Return the capacity of the container.
Other operations.

void	swap (AuxVectorData &other)
	Swap this instance with another.
void	clearCache ()
	Clear the cached aux data pointers.
virtual void	lock () ATH_OVERRIDE
	Lock the container.
void	clearDecorations () const
	Clear all decorations.
Friends
class	Cache
class	SG::AuxElement
Data access.

static size_t	s_minCacheLen = 1024
	Minimum length to use for the cache vector.
const SG::auxid_set_t &	getAuxIDs () const
	Return a set of identifiers for existing data items in store associated with this object.
const SG::auxid_set_t &	getWritableAuxIDs () const
	Return a set of identifiers for writable data items in this store.
bool	isAvailable (auxid_t id) const
	Test to see if a variable exists in the store.
template<class T >
bool	isAvailable (const std::string &name, const std::string &clsname="") const
	Test to see if a variable exists in the store.
bool	isAvailableWritable (auxid_t id) const
	Test to see if a variable is available for writing.
template<class T >
bool	isAvailableWritable (const std::string &name, const std::string &clsname="") const
	Test to see if a variable is available for writing.
bool	isAvailableWritableAsDecoration (auxid_t id) const
	Test to see if a variable is available for writing as a decoration.
template<class T >
bool	isAvailableWritableAsDecoration (const std::string &name, const std::string &clsname="") const
	Test to see if a variable is available for writing as a decoration.
template<class T >
AuxDataTraits< T >::reference_type	getData (SG::auxid_t auxid, size_t ndx)
	Return reference to an aux data item.
template<class T >
AuxDataTraits< T > ::const_reference_type	getData (SG::auxid_t auxid, size_t ndx) const
	Return const reference to an aux data item.
template<class T >
AuxDataTraits< T >::reference_type	getDecoration (SG::auxid_t auxid, size_t ndx) const
	Return reference to an aux decoration item.
const void *	getDataArray (SG::auxid_t auxid) const
	Return a const pointer to the start of an aux data vector.
const void *	getDataArrayAllowMissing (SG::auxid_t auxid) const
	Return a const pointer to the start of an aux data vector.
void *	getDataArray (SG::auxid_t auxid)
	Return a pointer to the start of an aux data vector.
void *	getDecorationArray (SG::auxid_t auxid) const
	Return a pointer to the start of an aux data vector for a decoration.
Aux store management.

const SG::IConstAuxStore *	getConstStore () const
	Return the current store, as a const interface.
SG::IAuxStore *	getStore () const
	Return the current store, as a non-const interface.
bool	hasStore () const
	Return true if this object has an associated store.
bool	hasNonConstStore () const
	Return true if this object has an associated non-const store.
bool	setOption (auxid_t id, const AuxDataOption &option)
	Set an option for an auxiliary data variable.
bool	setOption (const std::string &name, const AuxDataOption &option)
	Set an option for an auxiliary data variable.
bool	setOption (const std::string &name, const std::string &clsname, const AuxDataOption &option)
	Set an option for an auxiliary data variable.
template<class T >
bool	setOption (auxid_t id, const std::string &optname, T arg)
	Set an option for an auxiliary data variable.
bool	setOption (const std::string &name, const std::string &optname, int arg)
	Set an option for an auxiliary data variable.
bool	setOption (const std::string &name, const std::string &optname, float arg)
bool	setOption (const std::string &name, const std::string &optname, double arg)
template<class T >
bool	setOption (const std::string &name, const std::string &clsname, const std::string &optname, T arg)
	Set an option for an auxiliary data variable.
void	setStore (const SG::IConstAuxStore *store)
	Set the store associated with this object.
void	setStore (SG::IAuxStore *store)
	Set the store associated with this object.
void	setStore (const DataLink< SG::IConstAuxStore > &store)
	Set the store associated with this object.

Detailed Description

Manage lookup of vectors of auxiliary data.

An object, usually a DataVector, can have vectors of auxiliary data associated with it. This class manages this association.

An auxiliary data item is identified by an integer of type SG::auxid_t. The getData methods can be used to get a reference to one auxiliary data element given the auxid and the vector index. However, getData does not do type checking, so it should generally not be used. (Use instead the Accessor or ConstAccessor classes defined in AuxElement.)

The auxiliary data is not managed by this class, but rather by a separate `aux store' class, to which we hold a pointer. Actually, there can be two pointers. We define two interfaces for an aux store, IConstAuxStore, which defines operations for accessing data read-only, and IAuxStore, which defines operations for modifying data. If we have a const store, only the pointer to the const interface is set; if we have non-const store, then both pointers are set (to the same object).

To speed up access to aux data, we cache pointers to the start of the data for each vector. There are separate caches for const and non-const pointers. If you make any changes to the aux store behind the back of this container object, you should call clearCache.

We also support adding `decorations' to a const container. These are new auxiliary data items that don't conflict with existing ones. See IConstAuxStore for more information.

Notes on thread safety:

It's a little tricky to make this class thread-safe without spoiling the optimizations in getDataArray. This section outlines some of the considerations that went into the chosen solution.

First, by `thread-safe', we mean that getDataArray can be called in different threads without problems. This is necessary to allow simultaneous reads of the container. We make no attempt to any synchronization on modifications to the container, such as adding elements. Such operations must be synchronized externally. This is the same sort of thread semantics that the STL containers supply. So our considerations of thread-safety involve only the management of the cache vector.

Second, reads (of the cache vector) are very common (and inlined), while modifications of it are uncommon (and handled by out-of-line code). Thus, we would like reading to be entirely lock-free. If we need to make modifications, though, we can do whatever locking we need. Making the reader lock-free, though, is complicated by the fact that the cache vector may relocate in memory if is expanded.

A way forward is suggested by read-copy-update (RCU) synchronization. The idea there is that when you want to change some structure, you copy it and work on the copy. When the modifications are done, the new structure is copied to the old one in such a manner that at any instant in time, any reader will see a consistent version of the structure (even though it may not be the most recent one).

For this case, we can store the vector as a length and a pointer to the beginning. When we want to access AUXID, we first compare it to the length. If that's ok, then we test the pointer at index AUXID. If that's non-null, we go ahead and use it; if either test fails, we go to the out-of-line code.

The out-of-line code can then take out a lock and will in the new pointer in the vector. If it is necessary to expand the the vector, we allocate a new one and copy the old vector to the new one. Then we update the values: first, the pointer, then the length. This ensures that the inline code will always see something consistent. Then we must delay freeing the old vector until we're sure that no thread can possibly be using it anymore. For now, we just avoid deleting the old vectors until the container itself is deleted; the memory wasted by this should be negligible in the context of reconstruction.

This allows the inline part of the code to avoid locking. However, there is an additional critical detail. We have a test like this:

m_cache_length <= auxid || !m_cache[auxid]

As long as the length is read before the cache pointer itself, everything's fine, even if those reads were some time in the past. But if the reads can be in the other order, we could face disaster. While the short-circuit operator should prevent the array indexing from happening before the length is read, there is nothing a priori to prevent a speculative read of m_cache before the length. For the cognoscenti, this is a `control dependency' (rather than a `data dependency'), which implies no ordering guarantees.

Now, we can deal with this by inserting a read barrier between the two loads. That should be correct in all cases. However, that tends to destroy the optimization below for repeated references to the same aux data item (see the use of ATHCONTAINERS_ASSUME in getDataArray in the icc file).

It turns out that on x86 machines, memory ordering guarantees are relatively strong. In particular, loads cannot be reordered with other loads, and stores from one CPU are seen in the same order by all other CPUs. So in this case, no barrier is actually needed --- provided that the compiler emits the loads in the correct order. The supported way to do this with gcc is to use `asm volatile ("":::"memory")' --- however, that explicitly clobbers member, which again spoils our optimization.

While it seems unlikely that the compiler would actually find it worthwhile to reorder the loads on an x86 machine, some extra safety would be nice. We try to prevent this reordering by adding an explicit data dependency. Instead of a single m_cache pointer, we have an array of two pointers (which will be identical) and use m_cache[m_cache_len&1]. This provides an explicit data dependency which should prevent reading the pointer before the length; the cost is an added and operation and adding an index register to the dereference operation.

Actually, this is not completely watertight; the compiler could in principle decide to speculate the reads of both pointers, or speculate one and then throw it away if it guessed wrong. This seems sufficiently unlikely to be an issue that we'll live with it for now --- though it might be worth having something to validate the generated code.

Member Function Documentation

virtual size_t SG::AuxVectorData::capacity_v ( ) const [pure virtual]

Return the capacity of the container.

This is used when we need to create a new aux data vector.

Implemented in DataVector< T, DataModel_detail::NoBase >, and SG::AuxElementData.

void SG::AuxVectorData::clearCache ( ) [inline]

Clear the cached aux data pointers.

You should call this any time something changes in the aux store that could invalidate the vector pointers.

You should call this anytime something changes in the aux store that could invalidate the vector pointers.

void SG::AuxVectorData::clearDecorations ( ) const

Clear all decorations.

Erase all decorations from the store, restoring the state to when lock was called.

const SG::auxid_set_t & SG::AuxVectorData::getAuxIDs ( ) const

Return a set of identifiers for existing data items in store associated with this object.

This will include identifiers for all items, const and non-const. If no store is associated with this object, this will return an empty set.

const SG::IConstAuxStore * SG::AuxVectorData::getConstStore ( ) const [inline]

Return the current store, as a const interface.

This will be non-zero if either a const or non-const store is associated with this object.

template<class T >

AuxDataTraits< T >::const_reference_type SG::AuxVectorData::getData	(	SG::auxid_t	auxid,
		size_t	ndx
	)			const `[inline]`

Return const reference to an aux data item.

Parameters:

	auxid	The desired aux data item.
	ndx	Index of the element to return.

This will return a reference to element ndx of aux data item auxid. Errors are signaled by raising an exception.

Warning: no type checking is done. You should usually access the data via AuxElement::Accessor or AuxElement::ConstAccessor.

Parameters:

	auxid	The desired aux data item.
	ndx	Index of the element to return.

This will return a reference to element ndx of aux data item auxid. If the aux data item does not exist, it will be created. Errors are signaled by raising an exception.

Warning: no type checking is done. You should usually access the data via AuxElement::Accessor.

template<class T >

AuxDataTraits< T >::reference_type SG::AuxVectorData::getData	(	SG::auxid_t	auxid,
		size_t	ndx
	)			`[inline]`

Return reference to an aux data item.

Parameters:

	auxid	The desired aux data item.
	ndx	Index of the element to return.

This will return a reference to element ndx of aux data item auxid. If the aux data item does not exist, it will be created. Errors are signaled by raising an exception.

Warning: no type checking is done. You should usually access the data via AuxElement::Accessor or AuxElement::ConstAccessor.

Parameters:

	auxid	The desired aux data item.
	ndx	Index of the element to return.

This will return a reference to element ndx of aux data item auxid. If the aux data item does not exist, it will be created. Errors are signaled by raising an exception.

Warning: no type checking is done. You should usually access the data via AuxElement::Accessor.

void * SG::AuxVectorData::getDataArray ( SG::auxid_t auxid ) [inline, protected]

Return a pointer to the start of an aux data vector.

Parameters:

auxid

The desired aux data item.

This will return a pointer to the start of the data for aux data item auxid. If the item doesn't exist, it will be created. Errors are signaled by raising an exception.

const void * SG::AuxVectorData::getDataArray ( SG::auxid_t auxid ) const [inline]

Return a const pointer to the start of an aux data vector.

Parameters:

auxid

The desired aux data item.

This will return a pointer to the start of the data for aux data item auxid. Errors are signaled by raising an exception.

const void * SG::AuxVectorData::getDataArrayAllowMissing ( SG::auxid_t auxid ) const [inline]

Return a const pointer to the start of an aux data vector.

Parameters:

auxid

The desired aux data item.

This will return a pointer to the start of the data for aux data item auxid. If the item does not exist, this will return nullptr rather than raising an exception.

template<class T >

AuxDataTraits< T >::reference_type SG::AuxVectorData::getDecoration	(	SG::auxid_t	auxid,
		size_t	ndx
	)			const `[inline]`

Return reference to an aux decoration item.

Parameters:

	auxid	The desired aux decoration item.
	ndx	Index of the element to return.

This will return a reference to element ndx of aux decoration item auxid. If the aux data item does not exist, it will be created. Errors are signaled by raising an exception.

Warning: no type checking is done. You should usually access the data via AuxElement::Decorator.

The difference between getDecoration and getData is that getDecoration takes a const container as input, but returns a non-const reference. This will only succeed if either the container is not locked or the item was first accessed as a decoration.

void * SG::AuxVectorData::getDecorationArray ( SG::auxid_t auxid ) const [inline, protected]

Return a pointer to the start of an aux data vector for a decoration.

Parameters:

auxid

The desired aux data item.

This will return a pointer to the start of the data for aux data item auxid. If the item doesn't exist, it will be created. Errors are signaled by raising an exception.

The difference between getDecorationArray and getDataArray is that getDecorationArray takes a const container as input, but returns a non-const pointer. This will only succeed if either the container is not locked or the item was first accessed as a decoration.

SG::IAuxStore * SG::AuxVectorData::getStore ( ) const [inline]

Return the current store, as a non-const interface.

This will be non-zero if a non-const store is associated with this object.

const SG::auxid_set_t & SG::AuxVectorData::getWritableAuxIDs ( ) const

Return a set of identifiers for writable data items in this store.

This will include only non-const identifiers. If no store is associated with this object, this will return an empty set.

template<class T >

bool SG::AuxVectorData::isAvailable	(	const std::string &	name,
		const std::string &	clsname = `""`
	)			const `[inline]`

Test to see if a variable exists in the store.

Parameters:

	name	Name of the aux variable.
	clsname	The name of the associated class. May be blank.

bool SG::AuxVectorData::isAvailable ( auxid_t id ) const [inline]

Test to see if a variable exists in the store.

Parameters:

id

The variable to test.

template<class T >

bool SG::AuxVectorData::isAvailableWritable	(	const std::string &	name,
		const std::string &	clsname = `""`
	)			const `[inline]`

Test to see if a variable is available for writing.

Parameters:

	name	Name of the aux variable.
	clsname	The name of the associated class. May be blank.

bool SG::AuxVectorData::isAvailableWritable ( auxid_t id ) const [inline]

Test to see if a variable is available for writing.

Parameters:

id

The variable to test.

template<class T >

bool SG::AuxVectorData::isAvailableWritableAsDecoration	(	const std::string &	name,
		const std::string &	clsname = `""`
	)			const `[inline]`

Test to see if a variable is available for writing as a decoration.

Parameters:

	name	Name of the aux variable.
	clsname	The name of the associated class. May be blank.

bool SG::AuxVectorData::isAvailableWritableAsDecoration ( auxid_t id ) const [inline]

Test to see if a variable is available for writing as a decoration.

Parameters:

id

The variable to test.

void SG::AuxVectorData::lock ( ) [virtual]

Lock the container.

After this, only decorations can be changed/modified. If the container is already locked, this is a no-op.

template<class T >

bool SG::AuxVectorData::setOption	(	const std::string &	name,
		const std::string &	clsname,
		const std::string &	optname,
		T	arg
	)			`[inline]`