Catalog with extensible mirroring. More...

#include <StateCatalog.h>

Inheritance diagram for fe::StateCatalog:

[legend]

Classes
class	Atomic
	A locking mechanism to get cohesive state. More...

class	Snapshot
	A fixed copy of state from a StateCatalog. More...

Public Member Functions
virtual Result	configure (String a_line)
	Provide a parsable setup string. More...

virtual Result	start (void)=0
	Begin any special behaviors of derived classes. More...

virtual Result	stop (void)=0
	Cease any special behaviors of derived classes. More...

virtual Result	waitForConnection (void)
	Wait for derived class to begin communication. More...

virtual BWORD	started (void) const
	Return TRUE if the special function has begun. More...

virtual BWORD	connected (void) const
	Return TRUE if communication is currently established. More...

virtual void	setConnectionTimeout (Real a_seconds)
	Indicate how long a connection may remain quiet. More...

virtual Result	flush (void)
	Indicate the end of some phase of state changes. More...

virtual Result	waitForUpdate (I32 &a_rFlushCount, I32 &a_rSpins, volatile BWORD &a_rKeepWaiting, I32 a_microSleep)
	Wait for a state change. More...

virtual Result	lockAfterUpdate (I32 &a_rFlushCount, I32 &a_rSpins, volatile BWORD &a_rKeepWaiting, I32 a_microSleep)
	Wait for a state change and then lock the mutex. More...

Result	getTypeName (String a_name, String &a_rTypeName) const
	Get state with mutex (default property) More...

Result	getTypeName (String a_name, String a_property, String &a_rTypeName) const
	Get state with mutex. More...

void	getStateKeys (Array< String > &a_keys, String a_pattern=".*") const
	Returns keys that match the regex pattern. More...

void	getStateProperties (String a_name, Array< String > &a_properties) const
	Returns properties for a key. More...

template<class T >
Result	getState (String a_name, T &a_rValue) const
	Get state with mutex (default property) More...

template<class T >
Result	getState (String a_name, String a_property, T &a_rValue) const
	Get state with mutex. More...

Result	getState (String a_name, String a_property, String &a_rTypeName, String &a_rValue) const

template<class T >
Result	justGetState (String a_name, String a_property, T &a_rValue) const
	Get state with mutex, but without calling the internal preGet() and postGet() methods. More...

template<class T >
Result	setState (String a_name, const T &a_rValue)
	Set state with mutex (default property) More...

template<class T >
Result	setState (String a_name, String a_property, const T &a_rValue)
	Set state with mutex. More...

Result	setState (String a_name, String a_property, String a_typeName, String a_value)
	Set state with mutex (serialized) More...

Result	removeState (String a_name, String a_property)
	Remove a state, with mutex. More...

Result	removeState (String a_name)
	Remove all properties of a state, with mutex. More...

Result	overlayState (sp< Catalog > a_spOtherCatalog)
	Set state for entries in a Catalog, with mutex. More...

Result	getTypeNameUnsafe (String a_name, String &a_rTypeName) const
	Get state without mutex. More...

Result	getTypeNameUnsafe (String a_name, String a_property, String &a_rTypeName) const
	Get state without mutex (default property) More...

template<class T >
Result	getStateUnsafe (String a_name, T &a_rValue) const
	Get state without mutex. More...

template<class T >
Result	getStateUnsafe (String a_name, String a_property, T &a_rValue) const
	Get state without mutex (default property) More...

Result	snapshot (sp< Snapshot > &a_rspSnapshot)
	Grab current state into a fixed snapshot. More...

void	incrementSerial (void)
	Increment the serial index, indicating a collective change of state. More...

void	incrementFlushCount (void)
	Increment the count of incoming flushes indicating a collective remote change of state. More...

template<class T >
Result	sendMessage (String a_name, const T &a_rValue)
	Append value to remote queues. More...

template<class T >
Result	nextMessage (String a_name, T &a_rValue)
	Pop received value from front of queue. More...

Result	addListener (sp< ListenerI > a_spListener, String a_name)
	Add a ListenerI for a specific key. More...

template<>
Result	nextMessage (String a_name, String &a_rValue)

Public Member Functions inherited from fe::Catalog
sp< Catalog >	catalogShallowCopy (void)
	Returns a mirror of the catalog. More...

sp< Catalog >	catalogDeepCopy (void)
	Returns a duplicate of the catalog. More...

U32	catalogSize (void) const
	Returns the number of name keys. More...

String	catalogKey (U32 index) const
	Returns a key by ordered index. More...

void	catalogKeys (Array< String > &a_keys, String a_pattern=".*") const
	Returns keys in order of creation. More...

void	catalogProperties (String a_name, Array< String > &a_properties) const
	Returns properties for a key. More...

BWORD	cataloged (String a_name, String a_property="value") const
	Returns TRUE if the given property for the given name has been created. More...

BWORD	catalogedAny (String a_name) const
	Returns TRUE if any property for the given name has been created. More...

void	catalogClear (void)
	Remove all entries. More...

void	catalogOverlay (sp< Catalog > a_spOtherCatalog, Array< String > *a_pTypeList=NULL, BWORD a_shallow=FALSE)
	Duplicates entries from another catalog. More...

sp< Component >	catalogComponent (String implementation, String a_name, String a_property="value")
	Returns a component entry of the given property for the given name. More...

sp< Component >	catalogComponent (sp< Component > a_spComponent, String a_name, String a_property="value")
	Returns a component entry of the given property for the given name. More...

Instance &	catalogInstance (Instance &instance, String a_name, String a_property="value")
	Returns the literal Instance of the given property for the given name. More...

Instance &	catalogInstance (String a_name, String a_property="value")
	Returns the literal Instance of the given property for the given name. More...

const fe_type_info &	catalogTypeInfo (String a_name, String a_property="value") const
	Returns the type_info of the given property for the given name. More...

const String	catalogTypeName (String a_name, String a_property="value") const
	Returns the type name of the given property, determined by the TypeMaster. More...

template<class T >
BWORD	catalogTypeIs (String a_name, String a_property="value") const
	Returns TRUE if given catalog entry match the template type. More...

template<class T >
T &	catalog (String a_name, String a_property="value")
	Returns existing catalog entry if already set or a default if not. More...

template<class T >
T &	catalog (String a_name, String a_property, const T &a_default)
	Returns existing catalog entry if already set or default if not. More...

template<class T >
const T &	catalogOrDefault (String a_name, String a_property, const T &a_default) const
	Returns existing catalog entry if already set or default if not. More...

template<class T >
const T &	catalogOrDefault (String a_name, const T &a_default) const

String	catalogValue (String a_name, String a_property="value") const
	Returns existing catalog entry, converted to a String. More...

I32	catalogBytes (String a_name, String a_property, Array< U8 > &a_rByteArray) const
	Converts a catalog entry, into raw binary. More...

BWORD	catalogSet (String a_name, String a_property, String a_value)
	Sets the value for a catalog entry, converted to the existing type, from a given String. More...

BWORD	catalogSet (String a_name, String a_value)

BWORD	catalogSet (String a_name, String a_property, String a_type, String a_value, Instance **a_ppInstance=NULL)
	Sets the value for a catalog entry, converted to the existing type, from a given String. More...

BWORD	catalogSet (String a_name, String a_property, String a_type, const U8 a_pRawBytes, I32 a_byteCount, Instance *a_ppInstance=NULL)
	Sets the value for a catalog entry, using a raw byte block. More...

template<class T >
T &	catalogOrException (String a_name, String a_property) const
	Returns an existing catalog entry, if it exists. More...

bool	catalogLookup (const String a_name, String a_property, Instance &a_instance) const
	Gets the Instance of an existing catalog entry, if it exists. More...

bool	catalogLookup (const String a_name, Instance &a_instance) const

void	catalogMoveToEnd (String a_name)
	Move all properties for name to bottom. More...

void	catalogRemove (String a_name)
	Remove all properties for a name. More...

void	catalogRemove (String a_name, String a_property)
	Remove one property for a name. More...

void	catalogDump (void) const
	Print a description of the catalog to the log. More...

sp< TypeMaster >	typeMaster (void) const

Public Member Functions inherited from fe::Component
const String &	name (void) const
	Return the components chosen name. More...

const String	verboseName (void) const
	Return the annotated chosen name. More...

void	setName (const String &name)
	Rename the component to anything you want. More...

hp< Registry >	registry (void) const
	Get the Registry that created this component. More...

void	adjoin (sp< Component > spComponent)
	Tie this component's lifetime to another. More...

sp< Component >	create (const String &implementation, BWORD quiet=FALSE) const
	Convienience function to registry()->create() More...

void	disjoin (void)
	Untie component from Hub, if connected. More...

String	factoryName (void)

void	setLibrary (sp< Library > spLibrary)
	Store a reference to the library used to instantiate this component. More...

sp< Library >	library (void)
	Get the library that created the component. More...

void	setFactoryIndex (I32 a_factoryIndex)
	Set the library's factory index. More...

I32	factoryIndex (void)
	Get the library's factory index. More...

void	setSingleton (BWORD set)
	Specify whether component is a singleton. More...

BWORD	isSingleton (void)
	Return whether component is a singleton. More...

virtual void	acquire (void)
	Specialized reference increment. More...

virtual void	release (void)
	Specialized reference decrement. More...

Public Member Functions inherited from fe::Handled< Component >
const hp< Component > &	getHandle (void) const
	Get a safe handle to this object. More...

Public Member Functions inherited from fe::Protectable
virtual I32	protection (void) const

virtual void	protect (void)

virtual void	unprotect (void)

virtual Protectable *	clone (Protectable *pInstance=NULL)

Public Member Functions inherited from fe::Counted
virtual void	acquire (int &rCount)
	Increment the reference count (and get the count) More...

virtual void	abandon (void)
	Decrement the reference count. More...

int	count (void) const
	Return the count of references. More...

void	setName (const String &)

void	trackReference (void *pReference, String what)

void	untrackReference (void *pReference)

void	registerRegion (void *pT, U32 bytes)

Public Member Functions inherited from fe::Initialized
void	initializeAll (void)

void	setActive (bool a_active)

Protected Member Functions
virtual Result	preGet (String a_name, String a_property) const

virtual Result	postGet (String a_name, String a_property) const

virtual Result	preSet (String a_name, String a_property)

virtual Result	postSet (String a_name, String a_property)

I32	serial (void) const

I32	flushCount (void) const

Result	addNotification (String a_name, String a_property)

Result	sendNotifications (void)

Result	notify (String a_name, String a_property)

template<class T >
Result	updateState (String a_name, String a_property, const T &a_rValue)

Result	updateState (String a_name, String a_property, String a_typeName, String a_value)

Result	updateState (String a_name, String a_property, String a_typeName, const U8 *a_pRawBytes, I32 a_byteCount)

Result	clearState (String a_name, String a_property)

Protected Member Functions inherited from fe::Handled< Component >
void	abandonHandle (void)

Protected Member Functions inherited from fe::Counted
int	releaseInternal (void)
	Decrement the reference count. More...

void	suppressReport (void)

Protected Member Functions inherited from fe::Initialized
void	addInitializer (InitializeFunction function)

Private Member Functions
void	cacheInstanceUpdates (String a_name, String a_property, Instance &a_rInstance)

Private Attributes
volatile I32	m_serial

volatile I32	m_flushCount

AutoHashMap< I32, sp< Snapshot > >	m_snapshotMap

I32	m_latestSerial

sp< Snapshot >	m_latestSnapshot

AutoHashMap< String, Array< sp< ListenerI > > >	m_listenerMap

Array< Notification >	m_notificationArray

RecursiveMutex	m_notificationMutex

Additional Inherited Members
Static Public Member Functions inherited from fe::Counted
static String	reportTracker (void)

static U32	trackerCount (void)

Protected Types inherited from fe::Initialized
typedef void(*	InitializeFunction) (Initialized *)

Related Functions inherited from fe::Component
FE_DL_EXPORT void FE_CDECL	checkUnload (sp< Library > &pLibrary, Component *pComponent=NULL)
	Delete the component and unload libraries where appropriate. More...

Detailed Description

Catalog with extensible mirroring.

This class has some pure virtual methods which must be implemented by derived classes, such as relaying the state across networks.

The get/set methods are templated on type.

Member Function Documentation

◆ addListener()

Result fe::StateCatalog::addListener	(	sp< ListenerI >	a_spListener,
		String	a_name
	)

Add a ListenerI for a specific key.

The bind method of the Listener is called once as it is added here.

The notify method of the Listener is called every time any property of that key is updated.

The notification arguments are the key name and property.

◆ configure()

virtual Result fe::StateCatalog::configure ( String a_line )

inlinevirtual

Provide a parsable setup string.

Reimplemented in fe::ext::ConnectedCatalog.

◆ connected()

virtual BWORD fe::StateCatalog::connected ( void ) const

inlinevirtual

Return TRUE if communication is currently established.

Reimplemented in fe::ext::ConnectedCatalog.

◆ flush()

virtual Result fe::StateCatalog::flush ( void )

inlinevirtual

Indicate the end of some phase of state changes.

The default implementation does nothing. This may be used by a derived class to trigger a transmission and/or to delineate a single frame in time.

Reimplemented in fe::ext::ConnectedCatalog, and fe::ext::NetworkCatalog.

Referenced by fe::ext::ConnectedCatalog::flush().

◆ getState() [1/2]

template<class T >

Result fe::StateCatalog::getState	(	String	a_name,
		T &	a_rValue
	)		const

inline

Get state with mutex (default property)

◆ getState() [2/2]

template<class T >

Result fe::StateCatalog::getState	(	String	a_name,
		String	a_property,
		T &	a_rValue
	)		const

Get state with mutex.

References fe::failure().

◆ getStateKeys()

void fe::StateCatalog::getStateKeys	(	Array< String > &	a_keys,
		String	a_pattern = `".*"`
	)		const

Returns keys that match the regex pattern.

Keys are appended to the given array. Clear the array if only want new values.

References fe::Catalog::catalogKeys().

◆ getStateProperties()

void fe::StateCatalog::getStateProperties	(	String	a_name,
		Array< String > &	a_properties
	)		const

Returns properties for a key.

Properties are appended to the given array. Clear the array if only want new values.

Order is arbitrary.

References fe::Catalog::catalogProperties().

◆ getStateUnsafe() [1/2]

template<class T >

Result fe::StateCatalog::getStateUnsafe	(	String	a_name,
		T &	a_rValue
	)		const

inline

Get state without mutex.

◆ getStateUnsafe() [2/2]

template<class T >

Result fe::StateCatalog::getStateUnsafe	(	String	a_name,
		String	a_property,
		T &	a_rValue
	)		const

Get state without mutex (default property)

References fe::failure().

◆ getTypeName() [1/2]

Result fe::StateCatalog::getTypeName	(	String	a_name,
		String &	a_rTypeName
	)		const

inline

Get state with mutex (default property)

◆ getTypeName() [2/2]

Result fe::StateCatalog::getTypeName	(	String	a_name,
		String	a_property,
		String &	a_rTypeName
	)		const

Get state with mutex.

References fe::Catalog::catalogTypeName(), fe::failure(), postGet(), and preGet().

◆ getTypeNameUnsafe() [1/2]

Result fe::StateCatalog::getTypeNameUnsafe	(	String	a_name,
		String &	a_rTypeName
	)		const

inline

Get state without mutex.

◆ getTypeNameUnsafe() [2/2]

Result fe::StateCatalog::getTypeNameUnsafe	(	String	a_name,
		String	a_property,
		String &	a_rTypeName
	)		const

Get state without mutex (default property)

References fe::Catalog::catalogTypeName(), fe::failure(), postGet(), and preGet().

◆ incrementFlushCount()

void fe::StateCatalog::incrementFlushCount ( void )

inline

Increment the count of incoming flushes indicating a collective remote change of state.

This is generally only called from derived implementations, such as when new data arrives over a connection.

◆ incrementSerial()

void fe::StateCatalog::incrementSerial ( void )

inline

Increment the serial index, indicating a collective change of state.

This is generally only called from derived implementations, such as when new data arrives over a connection.

◆ justGetState()

template<class T >

Result fe::StateCatalog::justGetState	(	String	a_name,
		String	a_property,
		T &	a_rValue
	)		const

Get state with mutex, but without calling the internal preGet() and postGet() methods.

◆ lockAfterUpdate()

virtual Result fe::StateCatalog::lockAfterUpdate	(	I32 &	a_rFlushCount,
		I32 &	a_rSpins,
		volatile BWORD &	a_rKeepWaiting,
		I32	a_microSleep
	)

inlinevirtual

Wait for a state change and then lock the mutex.

This method is generally only used by specialized mechanisms, since the Atomic and Snapshot classes neatly present this functionality.

See the Atomic constructor for parameter description.

Reimplemented in fe::ext::ConnectedCatalog.

◆ nextMessage()

template<class T >

Result fe::StateCatalog::nextMessage	(	String	a_name,
		T &	a_rValue
	)

Pop received value from front of queue.

◆ overlayState()

Result fe::StateCatalog::overlayState ( sp< Catalog > a_spOtherCatalog )

Set state for entries in a Catalog, with mutex.

References fe::Catalog::catalogInstance(), fe::Catalog::catalogKeys(), fe::Catalog::catalogProperties(), fe::failure(), postSet(), and preSet().

◆ postGet()

virtual Result fe::StateCatalog::postGet	(	String	a_name,
		String	a_property
	)		const

inlineprotectedvirtual

Referenced by getTypeName(), and getTypeNameUnsafe().

◆ postSet()

virtual Result fe::StateCatalog::postSet	(	String	a_name,
		String	a_property
	)

inlineprotectedvirtual

Reimplemented in fe::ext::ConnectedCatalog.

Referenced by overlayState(), removeState(), and setState().

◆ preGet()

Result fe::StateCatalog::preGet	(	String	a_name,
		String	a_property
	)		const

inlineprotectedvirtual

Reimplemented in fe::ext::ConnectedCatalog.

Referenced by getTypeName(), getTypeNameUnsafe(), and fe::ext::ConnectedCatalog::preGet().

◆ preSet()

virtual Result fe::StateCatalog::preSet	(	String	a_name,
		String	a_property
	)

inlineprotectedvirtual

Referenced by overlayState(), removeState(), and setState().

◆ removeState() [1/2]

Result fe::StateCatalog::removeState	(	String	a_name,
		String	a_property
	)

Remove a state, with mutex.

References fe::Catalog::catalogRemove(), fe::failure(), postSet(), and preSet().

◆ removeState() [2/2]

Result fe::StateCatalog::removeState ( String a_name )

Remove all properties of a state, with mutex.

References fe::Catalog::catalogProperties(), fe::Catalog::catalogRemove(), fe::failure(), postSet(), and preSet().

◆ sendMessage()

template<class T >

Result fe::StateCatalog::sendMessage	(	String	a_name,
		const T &	a_rValue
	)

Append value to remote queues.

◆ setConnectionTimeout()

virtual void fe::StateCatalog::setConnectionTimeout ( Real a_seconds )

inlinevirtual

Indicate how long a connection may remain quiet.

The default implementation does nothing. This may be used by a derived class to determine when a connection has failed.

Reimplemented in fe::ext::ConnectedCatalog.

◆ setState() [1/3]

template<class T >

Result fe::StateCatalog::setState	(	String	a_name,
		const T &	a_rValue
	)

inline

Set state with mutex (default property)

◆ setState() [2/3]

template<class T >

Result fe::StateCatalog::setState	(	String	a_name,
		String	a_property,
		const T &	a_rValue
	)

Set state with mutex.

References fe::failure().

◆ setState() [3/3]

Result fe::StateCatalog::setState	(	String	a_name,
		String	a_property,
		String	a_typeName,
		String	a_value
	)

Set state with mutex (serialized)

References fe::failure(), postSet(), and preSet().

◆ snapshot()

Result fe::StateCatalog::snapshot ( sp< Snapshot > & a_rspSnapshot )

Grab current state into a fixed snapshot.

Multiple calls to get a snapshot will get the same snapshot until there is a change to the state of the StateCatalog.

References fe::StateCatalog::Snapshot::serial().

◆ start()

virtual Result fe::StateCatalog::start ( void )

pure virtual

Begin any special behaviors of derived classes.

Implemented in fe::ext::ConnectedCatalog, and fe::ext::NetworkCatalog.

◆ started()

virtual BWORD fe::StateCatalog::started ( void ) const

inlinevirtual

Return TRUE if the special function has begun.

Reimplemented in fe::ext::ConnectedCatalog.

◆ stop()

virtual Result fe::StateCatalog::stop ( void )

pure virtual

Cease any special behaviors of derived classes.

Implemented in fe::ext::ConnectedCatalog.

◆ waitForConnection()

virtual Result fe::StateCatalog::waitForConnection ( void )

inlinevirtual

Wait for derived class to begin communication.

Reimplemented in fe::ext::ConnectedCatalog.

◆ waitForUpdate()

virtual Result fe::StateCatalog::waitForUpdate	(	I32 &	a_rFlushCount,
		I32 &	a_rSpins,
		volatile BWORD &	a_rKeepWaiting,
		I32	a_microSleep
	)

inlinevirtual

Wait for a state change.

This method is generally only used by specialized mechanisms, since the Atomic and Snapshot classes neatly present this functionality.

See the Atomic constructor for parameter description.

Reimplemented in fe::ext::ConnectedCatalog.

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

Classes

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ addListener()

◆ configure()

◆ connected()

◆ flush()

◆ getState() [1/2]

◆ getState() [2/2]

◆ getStateKeys()

◆ getStateProperties()

◆ getStateUnsafe() [1/2]

◆ getStateUnsafe() [2/2]

◆ getTypeName() [1/2]

◆ getTypeName() [2/2]

◆ getTypeNameUnsafe() [1/2]

◆ getTypeNameUnsafe() [2/2]

◆ incrementFlushCount()

◆ incrementSerial()

◆ justGetState()

◆ lockAfterUpdate()

◆ nextMessage()

◆ overlayState()

◆ postGet()

◆ postSet()

◆ preGet()

◆ preSet()

◆ removeState() [1/2]

◆ removeState() [2/2]

◆ sendMessage()

◆ setConnectionTimeout()

◆ setState() [1/3]

◆ setState() [2/3]

◆ setState() [3/3]

◆ snapshot()

◆ start()

◆ started()

◆ stop()

◆ waitForConnection()

◆ waitForUpdate()