Detailed Description

The DtAttribute class provides a flexible system for storing data to be shared between various app systems and components. It supports type-safe access and thread-safe change notifications. Attributes are organized in a heirarchical tree structure. Attribute are identified by names, which must be unique within each node.

#include <attribute.h>

Inheritance diagram for makVre::DtAttribute:

[legend]

Classes
struct	CallbacksForThread

struct	Stats

Public Types
enum	Trace { OFF , SET , CHANGE , GET , LOOKUP }

using	DumpItem = std::pair<DtAttributeHandle, std::list<std::string>>

using	DumpTable = std::list<DumpItem>

Public Member Functions
virtual	~DtAttribute ()

DtAttributeHandle	handle ()

const DtAttributeHandle	handle () const

	operator DtAttributeHandle ()

	operator const DtAttributeHandle () const

virtual const std::string &	name () const

virtual std::string	path () const

const std::string &	type () const

template<typename T>
bool	isType () const

bool	isType (const std::string &type) const

bool	isSet () const

template<typename T>
const T &	get () const

template<typename T>
T	getOr (T orValue) const

template<typename T>
bool	set (const T &value)

template<typename T>
bool	setIfNot (const T &defaultValue)

template<typename T>
void	modifyFast (std::function< bool(T &value)> modifyFunc)

template<typename T>
bool	modify (std::function< void(T &value)> modifyFunc)

template<typename T>
const T &	getAttribute (const std::string &attribute) const

template<typename T>
T	getAttributeOr (const std::string &attribute, T orValue) const

template<typename T>
bool	setAttribute (const std::string &attribute, const T &newValue)

std::string	getAsString () const

bool	setFromString (const std::string &newValue)

template<typename T>
const T &	previousValue () const

bool	unset ()

bool	unset (const std::string &name)

bool	unsetRecursive ()

void	setPersistence (bool persistent)

void	setPersistenceRecursive (bool persistent)

bool	isPersistent () const

bool	hasAttribute (const std::string &name) const

bool	contains (const DtAttributeHandle &attr) const

bool	containedBy (const DtAttributeHandle &attr) const

DtAttributeHandle	attribute (const std::string &name)

const DtAttributeHandle	attribute (const std::string &name) const

DtAttributeHandle	parent ()

const DtAttributeHandle	parent () const

DtAttributeHandle	first ()

const DtAttributeHandle	first () const

DtAttributeHandle	next ()

const DtAttributeHandle	next () const

DtAttributeHandle	next_looping ()

const DtAttributeHandle	next_looping () const

void	forEach (std::function< void(DtAttributeHandle)> forEachFun)

void	forEach (std::function< void(const DtAttributeHandle)> forEachFun) const

bool	isRoot () const

const void *	raw () const

bool	lock (unsigned int key)

bool	unlock (unsigned int key)

bool	locked () const

void	addCallback (const DtAttributeCallbackBase &callback)

void	removeCallback (const DtAttributeCallbackBase &callback)

void	checkPendingCallbacksRecursive ()

void	recursiveDumpToTable (DumpTable &output, int depth=0) const

const Stats &	stats () const

Static Public Member Functions
static DtAttributeHandle &	Root ()

static void	QueueTrace (DtAttributeHandle attribute, Trace trace)

static std::pair< DtAttributeHandle, Trace >	QueuedTrace ()

static void	CancelQueuedTrace ()

Protected Types
using	Ptr = std::shared_ptr<DtAttribute>

using	Ref = std::weak_ptr<DtAttribute>

using	Map = std::map<std::string, std::pair<Ptr, Ref>>

using	DataPtr = std::shared_ptr<DtAttributeData>

using	Mutex = tbb::spin_mutex

using	CallbackList = std::list<const DtAttributeCallbackBase*>

using	CallbackThreadMap = std::map<unsigned int, CallbacksForThread>

Protected Member Functions
	DtAttribute ()

	DtAttribute (const std::string &name, Ptr parent)

Ptr	self () const

void	forEach (std::function< void(Ptr)> forEachFun)

void	forEach (std::function< void(const Ptr)> forEachFun) const

Ptr	find (const std::string &path, bool orCreate=false)

const Ptr	find (const std::string &path, bool orCreate=false) const

Ptr	addAttribute (const std::string &name)

const Ptr	addAttribute (const std::string &name) const

template<typename T>
void	createData () const

template<typename T>
void	validateData () const

void	checkPendingCallbacks ()

void	invokeCallbacks (const Ptr &changed, unsigned int threadId)

void	valueChanged ()

bool	lockCheck () const

void	doTrace () const

Static Protected Member Functions
static Ptr	create (const std::string &name, Ptr parent)

Protected Attributes
std::string	myName

DataPtr	myData

bool	myExplicitType

Mutex	myMutex

CallbackThreadMap	myChangeCallbacks

Stats	myStats

Ref	mySelf

Ptr	myParent

Map	myAttributes

Map::iterator	myItr

unsigned int	myLock

Static Protected Attributes
static std::pair< Ref, Trace >	TheQueuedTrace

static std::pair< Ref, std::string >	TheLastTrace

Friends
class	DtAttributeHandle

Member Typedef Documentation

◆ DumpItem

using makVre::DtAttribute::DumpItem = std::pair<DtAttributeHandle, std::list<std::string>>

Recursively dumps the attribute hierarchy to a table.

Parameters

depth The current depth in the hierarchy

Returns: A table representation of the attribute hierarchy

◆ DumpTable

using makVre::DtAttribute::DumpTable = std::list<DumpItem>

◆ Ptr

using makVre::DtAttribute::Ptr = std::shared_ptr<DtAttribute>

protected

Shared pointer type for attributes.

◆ Ref

using makVre::DtAttribute::Ref = std::weak_ptr<DtAttribute>

protected

Weak pointer type for attributes.

◆ Map

using makVre::DtAttribute::Map = std::map<std::string, std::pair<Ptr, Ref>>

protected

Map type for storing child attributes.

◆ DataPtr

using makVre::DtAttribute::DataPtr = std::shared_ptr<DtAttributeData>

protected

◆ Mutex

using makVre::DtAttribute::Mutex = tbb::spin_mutex

protected

◆ CallbackList

using makVre::DtAttribute::CallbackList = std::list<const DtAttributeCallbackBase*>

protected

◆ CallbackThreadMap

using makVre::DtAttribute::CallbackThreadMap = std::map<unsigned int, CallbacksForThread>

protected

Member Enumeration Documentation

◆ Trace

enum makVre::DtAttribute::Trace

Enumerator
OFF
SET
CHANGE
GET
LOOKUP

Constructor & Destructor Documentation

◆ ~DtAttribute()

virtual makVre::DtAttribute::~DtAttribute ( )

virtual

Virtual destructor.

◆ DtAttribute() [1/2]

makVre::DtAttribute::DtAttribute ( )

protected

Default constructor.

◆ DtAttribute() [2/2]

makVre::DtAttribute::DtAttribute	(	const std::string &	name,
		Ptr	parent )

protected

Constructor with name and parent.

Parameters

name	The name of the attribute
parent	The parent attribute

References name(), and parent().

Member Function Documentation

◆ Root()

static DtAttributeHandle & makVre::DtAttribute::Root ( )

static

Returns a reference to the root attribute.

Returns: A reference to the root attribute handle

References DtAttributeHandle.

◆ handle() [1/2]

DtAttributeHandle makVre::DtAttribute::handle ( )

Returns the handle for this attribute.

Returns: A handle to this attribute

References DtAttributeHandle.

◆ handle() [2/2]

const DtAttributeHandle makVre::DtAttribute::handle ( ) const

Returns the const handle for this attribute.

Returns: A const handle to this attribute

References DtAttributeHandle.

◆ operator DtAttributeHandle()

makVre::DtAttribute::operator DtAttributeHandle ( )

Conversion operator to DtAttributeHandle.

References DtAttributeHandle.

◆ operator const DtAttributeHandle()

makVre::DtAttribute::operator const DtAttributeHandle ( ) const

Conversion operator to const DtAttributeHandle.

References DtAttributeHandle.

◆ name()

virtual const std::string & makVre::DtAttribute::name ( ) const

virtual

Returns the name associated with this attribute.

Returns: The name of this attribute

Referenced by addAttribute(), addAttribute(), attribute(), attribute(), create(), DtAttribute(), hasAttribute(), and unset().

◆ path()

virtual std::string makVre::DtAttribute::path ( ) const

virtual

Returns the full path of this attribute in the hierarchy.

Returns: The full path string in dot notation

Referenced by find(), and find().

◆ type()

const std::string & makVre::DtAttribute::type ( ) const

Returns the type of this attribute.

Returns: The type name as a string

Referenced by isType().

◆ isType() [1/2]

template<typename T>

bool makVre::DtAttribute::isType ( ) const

Checks if the attribute is of the specified type.

Returns: true if the attribute is of type T, false otherwise

◆ isType() [2/2]

bool makVre::DtAttribute::isType ( const std::string & type ) const

Checks if the attribute is of the specified type by name.

Parameters

type	The type name to check against

Returns: true if the attribute is of the specified type, false otherwise

References type().

◆ isSet()

bool makVre::DtAttribute::isSet ( ) const

Checks if the attribute value is undefined.

Returns: true if the attribute has no defined value, false otherwise

◆ get()

template<typename T>

const T & makVre::DtAttribute::get ( ) const

Gets the value of the attribute.

Returns: The value of the attribute of type T

Note: Throws an assertion if the attribute is of a different type

◆ getOr()

template<typename T>

T makVre::DtAttribute::getOr ( T orValue ) const

Gets the value of the attribute or a default value if undefined.

Parameters

orValue The default value to return if the attribute is undefined

Returns: The attribute value or the default value

◆ set()

template<typename T>

bool makVre::DtAttribute::set ( const T & value )

Sets the value of the attribute.

If the new value differs from existing, change callbacks will be invoked.

Parameters

value The new value to set

Returns: true if the new value differs from existing

◆ setIfNot()

template<typename T>

bool makVre::DtAttribute::setIfNot ( const T & defaultValue )

Sets the value of the attribute only if it is currently undefined.

Parameters

defaultValue The default value to set if the attribute is undefined

Returns: true if the value was set, false if the attribute already had a value

◆ modifyFast()

template<typename T>

void makVre::DtAttribute::modifyFast ( std::function< bool(T &value)> modifyFunc )

◆ modify()

template<typename T>

bool makVre::DtAttribute::modify ( std::function< void(T &value)> modifyFunc )

◆ getAttribute()

template<typename T>

const T & makVre::DtAttribute::getAttribute ( const std::string & attribute ) const

Gets the value of a child attribute.

Parameters

attribute The name of the child attribute

Returns: The value of the child attribute

References attribute().

◆ getAttributeOr()

template<typename T>

T makVre::DtAttribute::getAttributeOr	(	const std::string &	attribute,
		T	orValue ) const

Gets the value of a child attribute or a default value if undefined.

Parameters

attribute	The name of the child attribute
orValue	The default value to return if the attribute is undefined

Returns: The child attribute value or the default value

References attribute().

◆ setAttribute()

template<typename T>

bool makVre::DtAttribute::setAttribute	(	const std::string &	attribute,
		const T &	newValue )

Sets the value of a child attribute.

If the new value differs from existing, change callbacks will be invoked.

Parameters

attribute	The name of the child attribute
newValue	The new value to set

Returns: true if the value changed

References attribute().

◆ getAsString()

std::string makVre::DtAttribute::getAsString ( ) const

Gets string representation of the attribute value.

Returns: String representation of the attribute value

◆ setFromString()

bool makVre::DtAttribute::setFromString ( const std::string & newValue )

Sets the attribute value from a string representation.

If the new value differs from existing, change callbacks will be invoked.

Parameters

newValue String representation of the new value

Returns: true if the value changed

◆ previousValue()

template<typename T>

const T & makVre::DtAttribute::previousValue ( ) const

Gets the previous value of the attribute before the last change.

Returns: The previous value of the attribute

◆ unset() [1/2]

bool makVre::DtAttribute::unset ( )

Unsets the attribute value.

Value is returned to an undefined, typeless state

Returns: true if the attribute was unset, false otherwise

◆ unset() [2/2]

bool makVre::DtAttribute::unset ( const std::string & name )

Unsets (clears) a child attribute value.

Value is returned to an undefined, typeless state

Parameters

name	The name of the child attribute to unset

Returns: true if the child attribute was unset, false otherwise

References name().

◆ unsetRecursive()

bool makVre::DtAttribute::unsetRecursive ( )

Unsets this attribute and all child attributes, recursively.

Returns: true if all attributes were unset successfully

◆ setPersistence()

void makVre::DtAttribute::setPersistence ( bool persistent )

Set whether this attribute exists w/o handles assigned.

A persistent attribute will continue to exist in the attribute tree for the lifetime of the application. A non-persistent attribute will be deleted as soon as no handles are assigned to it. The default condition for attributes is persistent.

Parameters

persistent Set true for persistent, false for non-persistent

◆ setPersistenceRecursive()

void makVre::DtAttribute::setPersistenceRecursive ( bool persistent )

Sets the persistence of this attribute and all child attributes.

setPersistence

Parameters

persistent Set true for persistent, false for non-persistent

◆ isPersistent()

bool makVre::DtAttribute::isPersistent ( ) const

Check the persistence state of this attribute.

setPersistence

Returns: true if attribute is persitent, false if not

◆ hasAttribute()

bool makVre::DtAttribute::hasAttribute ( const std::string & name ) const

Checks if a child attribute exists.

Returns: true if the child attribute exists, false otherwise

References name().

◆ contains()

bool makVre::DtAttribute::contains ( const DtAttributeHandle & attr ) const

References DtAttributeHandle.

◆ containedBy()

bool makVre::DtAttribute::containedBy ( const DtAttributeHandle & attr ) const

References DtAttributeHandle.

◆ attribute() [1/2]

DtAttributeHandle makVre::DtAttribute::attribute ( const std::string & name )

Gets a handle to a child attribute.

Parameters

name	The name of the child attribute. Name may be a path to child subattributes in format "ChildName.GrandChild.GreatGrandChild"

Returns: A handle to the child attribute

References DtAttributeHandle, and name().

Referenced by getAttribute(), getAttributeOr(), QueueTrace(), and setAttribute().

◆ attribute() [2/2]

const DtAttributeHandle makVre::DtAttribute::attribute ( const std::string & name ) const

Const version of attribute(const std::string&)

References DtAttributeHandle, and name().

◆ parent() [1/2]

DtAttributeHandle makVre::DtAttribute::parent ( )

Gets a handle to the parent attribute.

Returns: A handle to the parent attribute

References DtAttributeHandle.

Referenced by create(), and DtAttribute().

◆ parent() [2/2]

const DtAttributeHandle makVre::DtAttribute::parent ( ) const

Gets a const handle to the parent attribute.

Returns: A const handle to the parent attribute

References DtAttributeHandle.

◆ first() [1/2]

DtAttributeHandle makVre::DtAttribute::first ( )

Gets a handle to the first child attribute.

Returns: A handle to the first child attribute

References DtAttributeHandle.

◆ first() [2/2]

const DtAttributeHandle makVre::DtAttribute::first ( ) const

Gets a const handle to the first child attribute.

Returns: A const handle to the first child attribute

References DtAttributeHandle.

◆ next() [1/2]

DtAttributeHandle makVre::DtAttribute::next ( )

Gets a handle to the next sibling attribute.

Returns: A handle to the next sibling attribute

References DtAttributeHandle.

◆ next() [2/2]

const DtAttributeHandle makVre::DtAttribute::next ( ) const

Gets a const handle to the next sibling attribute.

Returns: A const handle to the next sibling attribute

References DtAttributeHandle.

◆ next_looping() [1/2]

DtAttributeHandle makVre::DtAttribute::next_looping ( )

Gets a handle to the next sibling attribute, looping back to the first if at the end.

Returns: A handle to the next sibling attribute

References DtAttributeHandle.

◆ next_looping() [2/2]

const DtAttributeHandle makVre::DtAttribute::next_looping ( ) const

Gets a const handle to the next sibling attribute, looping back to the first if at the end.

Returns: A const handle to the next sibling attribute

References DtAttributeHandle.

◆ forEach() [1/4]

void makVre::DtAttribute::forEach ( std::function< void(DtAttributeHandle)> forEachFun )

References DtAttributeHandle.

◆ forEach() [2/4]

void makVre::DtAttribute::forEach ( std::function< void(const DtAttributeHandle)> forEachFun ) const

References DtAttributeHandle.

◆ isRoot()

bool makVre::DtAttribute::isRoot ( ) const

Checks if this attribute is the root attribute.

Returns: true if this is the root attribute, false otherwise

◆ raw()

const void * makVre::DtAttribute::raw ( ) const

Gets the raw data pointer.

Returns: The raw data pointer

◆ lock()

bool makVre::DtAttribute::lock ( unsigned int key )

Locks the attribute with a key.

Parameters

key	The key to use for locking

Returns: true if the attribute was locked, false if it was already locked

◆ unlock()

bool makVre::DtAttribute::unlock ( unsigned int key )

Unlocks the attribute with a key.

Parameters

key	The key used for locking

Returns: true if the attribute was unlocked, false if the key was incorrect

◆ locked()

bool makVre::DtAttribute::locked ( ) const

Checks if the attribute is locked.

Returns: true if the attribute is locked, false otherwise

◆ addCallback()

void makVre::DtAttribute::addCallback ( const DtAttributeCallbackBase & callback )

Adds a change callback for this attribute.

Parameters

callback The callback to add

◆ removeCallback()

void makVre::DtAttribute::removeCallback ( const DtAttributeCallbackBase & callback )

Removes a change callback from this attribute.

Parameters

callback The callback to remove

◆ checkPendingCallbacksRecursive()

void makVre::DtAttribute::checkPendingCallbacksRecursive ( )

◆ recursiveDumpToTable()

void makVre::DtAttribute::recursiveDumpToTable	(	DumpTable &	output,
		int	depth = 0 ) const

◆ stats()

const Stats & makVre::DtAttribute::stats ( ) const

inline

Gets the attribute statistics.

Returns: The attribute statistics

References myStats.

◆ QueueTrace()

static void makVre::DtAttribute::QueueTrace	(	DtAttributeHandle	attribute,
		Trace	trace )

static

References attribute(), and DtAttributeHandle.

◆ QueuedTrace()

static std::pair< DtAttributeHandle, Trace > makVre::DtAttribute::QueuedTrace ( )

static

◆ CancelQueuedTrace()

static void makVre::DtAttribute::CancelQueuedTrace ( )

static

◆ create()

static Ptr makVre::DtAttribute::create	(	const std::string &	name,
		Ptr	parent )

staticprotected

References name(), and parent().

◆ self()

Ptr makVre::DtAttribute::self ( ) const

protected

Gets a shared pointer to this attribute.

Returns: A shared pointer to this attribute

◆ forEach() [3/4]

void makVre::DtAttribute::forEach ( std::function< void(Ptr)> forEachFun )

protected

◆ forEach() [4/4]

void makVre::DtAttribute::forEach ( std::function< void(const Ptr)> forEachFun ) const

protected

◆ find() [1/2]

Ptr makVre::DtAttribute::find	(	const std::string &	path,
		bool	orCreate = false )

protected

Recursive search for child attribute at path, relative to this.

Recursive child names in path are delimited by '.', e.g. find("childName.grandChildName.greatGrandChildName")

Parameters

path	Name or path of names of child attribute to find
orCreate	If true, creates the attribute (and any intermediate path attributes) if not found; if false, returns null pointer when not found

Returns: Shared pointer to the found or created attribute, or null if not found and orCreate is false

References path().

◆ find() [2/2]

const Ptr makVre::DtAttribute::find	(	const std::string &	path,
		bool	orCreate = false ) const

protected

Const version of find(const std::string&, bool)

References path().

◆ addAttribute() [1/2]

Ptr makVre::DtAttribute::addAttribute ( const std::string & name )

protected

References name().

◆ addAttribute() [2/2]

const Ptr makVre::DtAttribute::addAttribute ( const std::string & name ) const

protected

References name().

◆ createData()

template<typename T>

void makVre::DtAttribute::createData ( ) const

protected

Creates data storage for the specified type.

Note: This is used to initialize the attribute data

◆ validateData()

template<typename T>

void makVre::DtAttribute::validateData ( ) const

protected

Validates that the attribute data is of the specified type.

◆ checkPendingCallbacks()

void makVre::DtAttribute::checkPendingCallbacks ( )

protected

◆ invokeCallbacks()

void makVre::DtAttribute::invokeCallbacks	(	const Ptr &	changed,
		unsigned int	threadId )

protected

Invokes all registered change callbacks.

◆ valueChanged()

void makVre::DtAttribute::valueChanged ( )

protected

◆ lockCheck()

bool makVre::DtAttribute::lockCheck ( ) const

protected

Checks if the attribute is locked.

Returns: true if locked and action should be prevented, false otherwise

◆ doTrace()

void makVre::DtAttribute::doTrace ( ) const

protected

Friends And Related Symbol Documentation

◆ DtAttributeHandle

friend class DtAttributeHandle

friend

References DtAttributeHandle.

Referenced by attribute(), attribute(), containedBy(), contains(), DtAttributeHandle, first(), first(), forEach(), forEach(), handle(), handle(), next(), next(), next_looping(), next_looping(), operator const DtAttributeHandle(), operator DtAttributeHandle(), parent(), parent(), QueueTrace(), and Root().

Member Data Documentation

◆ myName

std::string makVre::DtAttribute::myName

protected

The name of this attribute.

◆ myData

DataPtr makVre::DtAttribute::myData

mutableprotected

The data stored in this attribute.

◆ myExplicitType

bool makVre::DtAttribute::myExplicitType

mutableprotected

Flag indicating if the type was explicitly set.

◆ myMutex

Mutex makVre::DtAttribute::myMutex

mutableprotected

Mutex for thread synchronization.

◆ myChangeCallbacks

CallbackThreadMap makVre::DtAttribute::myChangeCallbacks

protected

List of change callbacks.

◆ myStats

Stats makVre::DtAttribute::myStats

mutableprotected

Statistics for this attribute.

Referenced by stats().

◆ mySelf

Ref makVre::DtAttribute::mySelf

mutableprotected

Weak reference to self.

◆ myParent

Ptr makVre::DtAttribute::myParent

protected

Shared pointer to parent.

◆ myAttributes

Map makVre::DtAttribute::myAttributes

mutableprotected

Map of child attributes.

◆ myItr

Map::iterator makVre::DtAttribute::myItr

protected

Iterator in parent's attribute map referring to this attribute.

◆ myLock

unsigned int makVre::DtAttribute::myLock

protected

Lock key.

◆ TheQueuedTrace

std::pair<Ref, Trace> makVre::DtAttribute::TheQueuedTrace

staticprotected

◆ TheLastTrace

std::pair<Ref, std::string> makVre::DtAttribute::TheLastTrace

staticprotected

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

include/utilities/vreUtil/attribute.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Member Typedef Documentation

◆ DumpItem

◆ DumpTable

◆ Ptr

◆ Ref

◆ Map

◆ DataPtr

◆ Mutex

◆ CallbackList

◆ CallbackThreadMap

Member Enumeration Documentation

◆ Trace

Constructor & Destructor Documentation

◆ ~DtAttribute()

◆ DtAttribute() [1/2]

◆ DtAttribute() [2/2]

Member Function Documentation

◆ Root()

◆ handle() [1/2]

◆ handle() [2/2]

◆ operator DtAttributeHandle()

◆ operator const DtAttributeHandle()

◆ name()

◆ path()

◆ type()

◆ isType() [1/2]

◆ isType() [2/2]

◆ isSet()

◆ get()

◆ getOr()

◆ set()

◆ setIfNot()

◆ modifyFast()

◆ modify()

◆ getAttribute()

◆ getAttributeOr()

◆ setAttribute()

◆ getAsString()

◆ setFromString()

◆ previousValue()

◆ unset() [1/2]

◆ unset() [2/2]

◆ unsetRecursive()

◆ setPersistence()

◆ setPersistenceRecursive()

◆ isPersistent()

◆ hasAttribute()

◆ contains()

◆ containedBy()

◆ attribute() [1/2]

◆ attribute() [2/2]

◆ parent() [1/2]

◆ parent() [2/2]

◆ first() [1/2]

◆ first() [2/2]

◆ next() [1/2]

◆ next() [2/2]

◆ next_looping() [1/2]

◆ next_looping() [2/2]

◆ forEach() [1/4]

◆ forEach() [2/4]

◆ isRoot()

◆ raw()

◆ lock()

◆ unlock()

◆ locked()

◆ addCallback()

◆ removeCallback()

◆ checkPendingCallbacksRecursive()