Free Electron
Classes | Public Types | Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | List of all members
fe::StateCatalog Class Referenceabstract

Catalog with extensible mirroring. More...

#include <StateCatalog.h>

Inheritance diagram for fe::StateCatalog:
Inheritance graph
[legend]

Classes

class  Atomic
 A locking mechanism to get cohesive state. More...
 
class  Snapshot
 A fixed copy of state from a StateCatalog. More...
 

Public Types

typedef std::function< void(String, String)> Callback
 

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 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...
 
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...
 
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_type, String a_value)
 Set state with mutex (serialized) More...
 
Result removeState (String a_name, String a_property)
 
Result overlayState (sp< Catalog > a_spOtherCatalog)
 Set state for entries in a Catalog, with Mutex. 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...
 
Result addCallback (Callback &a_lambda, String a_name)
 Add a Callback for a specific key. More...
 
- Public Member Functions inherited from fe::Catalog
sp< CatalogcatalogShallowCopy (void)
 Returns a mirror of the catalog. More...
 
sp< CatalogcatalogDeepCopy (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) 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< ComponentcatalogComponent (String implementation, String a_name, String a_property="value")
 Returns a component entry of the given property for the given name. More...
 
sp< ComponentcatalogComponent (sp< Component > a_spComponent, String a_name, String a_property="value")
 Returns a component entry of the given property for the given name. More...
 
InstancecatalogInstance (Instance &instance, String a_name, String a_property="value")
 Returns the literal Instance of the given property for the given name. More...
 
InstancecatalogInstance (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 >
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...
 
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< TypeMastertypeMaster (void) const
 
- Public Member Functions inherited from fe::Component
const Stringname (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< Registryregistry (void) const
 Get the Registry that created this component. More...
 
void adjoin (sp< Component > spComponent)
 Tie this component's lifetime to another. More...
 
sp< Componentcreate (const String &implementation, BWORD quiet=FALSE) const
 Convienience function to registry()->create() More...
 
void disjoin (void)
 Untie component from Hub, if connected. More...
 
void setLibrary (sp< Library > spLibrary)
 Store a reference to the library used to instantiate this component. More...
 
sp< Librarylibrary (void)
 Get the library that created the component. 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 Protectableclone (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
 
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_type, String a_value)
 
Result updateState (String a_name, String a_property, String a_type, 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
 
std::map< I32, sp< Snapshot > > m_snapshotMap
 
I32 m_latestSerial
 
sp< Snapshotm_latestSnapshot
 
std::map< String, Array< sp< ListenerI > > > m_listenerMap
 
std::map< String, Array< Callback > > m_callbackMap
 

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 *)
 

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

◆ addCallback()

Result fe::StateCatalog::addCallback ( Callback &  a_lambda,
String  a_name 
)

Add a Callback for a specific key.

The callback is called every time any property of that key is updated.

The Callback is simply a std::function<void(String,String) which can be assigned to an appropriate lambda function.

The callback arguments are the key name and property.

◆ 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.

◆ 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.

◆ 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().

◆ 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().

◆ 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.

References fe::failure().

◆ overlayState()

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

◆ postGet()

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

Referenced by getTypeName().

◆ postSet()

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

Reimplemented in fe::ext::ConnectedCatalog.

Referenced by overlayState(), and setState().

◆ preGet()

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

◆ preSet()

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

Referenced by overlayState(), and setState().

◆ sendMessage()

template<class T >
Result fe::StateCatalog::sendMessage ( String  a_name,
const T &  a_rValue 
)

Append value to remote queues.

◆ 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_type,
String  a_value 
)

Set state with mutex (serialized)

References fe::Catalog::catalogRemove(), 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.

◆ 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.

◆ 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: