MFSM || reference guide
Alexandre R.J. François
Code release version: 0.8
ARJF © 2001-2006
contents
Introduction
Factories
Nodes
Cells
Other structures
Index
This reference guide, part of the documentation for the MFSM project,
describes the core FSF library. Individual modules should provide specific
user and reference guides.
In its current implementation, the FSF library contains a set of C++ classes
implementing SAI elements: the source, the nodes and pulses, the cells, the
filters, the handles. It also contains classes for two implementation related
object types: the factories and the System. This document provides detailed
interface description and implementation notes for all the classes defined in
the FSF library.
All FSF library structures are defined in the fsf namespace.
All time variables are of type fsf::Time, which is currently a signed 64bit
integer (long long int). The time unit is the nanosecond (1 ns = 10^-9 s).
Class factories are used to instantiate objects at run time, whose type is not
known at compile time. Since cells and nodes constitute extensible sets of
specialized object types derived from respective base classes, Cell and Node
factories a necessary for instantiating cells and nodes at run time, and
modify application graphs dynamically. Node factories also allow to
instantiate filters for the corresponding node type. Note that all classes
defined in the FSF library do not have a registered factory. Only those nodes
and cells that require dynamic creation have registered factories.
This section lists all the node and cell factories registered by the FSF
library, in the following format:
- Factory name: ClassName "TYPE_ID"
Node factories
Base node and pulses
Fundamental type nodes
Fundamental type nodes are template instantiations of CTypeNode.
Other nodes
- Barrier (for synchronization): CBarrier "FSF_BARRIER"
- Character buffer node: CCharBuffer "FSF_CHAR_BUFFER"
Cell factories
Base Cell
Fundamental type cells
Fundamental type cells allow to get or set the value of corresponding type
nodes. They are all template instantiations of template class CTypeCell, which implements modified semantics for the
process member function in order to perform the get and set operations. The
template instantiation nature of these classes is made apparent in the
notation by not preceding the class name with a 'C'.
Node value access cells
Node value access cells allow to perform get and/or set operations on specific
CNode members. These cells are derived from CTypeCellBase, and implement consistent modified
semantics for the process member function in order to perform the get and set
operations.
Character buffer value access cells
Character buffer node value access cells allow to perform get and/or set
operations on specific CCharBuffer members. These
cells are derived from CTypeCellBase, and
implement the standard modified semantics for the process member function in
order to perform the get and set operations.
Other cells
- Pulsar: CPulsar "FSF_PULSAR"
- Barrier synchronization: CSync "FSF_SYNC"
The Fsf library contains a base node class, that implements connectivity
elements for building hierarchical structures. Specialized node classes,
encapsulating or implementing specific data structures, can be derived from
the base class (or derived classes). FSF specializes and active pulse and a
passive pulse classes from the base node class for active and passive pulse.
These specialized classes serve as root nodes for active and passive pulse
which are node hierarchies. Another node specialization implements nodes
holding one variable of simple or standard type values (integer, floating
point, boolean, string, etc.). These are called TypeNodes, and are
implemented as template instances of a template classe, itself derived from a
non template TypeNodeBase class (to allow
undetermined pointers to a TypeNode object).
This section details each node class defined in the FSF library. Classes are
listed in alphabetical order, according to the following formats:
- Title: NodeClassName (CBaseNodeClassName) "NODE_TYPE_ID"
- Short Description [header].
- Data members : type m_iName: description (default value and/or range when
applicable)
- Member functions: type Name(params): description.
Nodes
Template instances
Typedef for CTypeNode<bool>. [FsfTypeNode.h]
Active pulse. [FsfPulse.h]
Data members
- volatile int m_nNbPaths : number of concurrent paths currently followed by--
--this pulse
Member functions
Constructors, destructor and other functions that are part of any derived node class
- CActivePulse() : default constructor
- CActivePulse(const std::string &strName, fsf::Time tTime=0) :
initialization constructor
- CActivePulse(const CActivePulse& rhs) : copy constructor
- CActivePulse& operator=(const CActivePulse& rhs) : assignment operator
- virtual CNode* Clone() : virtual cloning member function (necessary for
run-time polymorphism)
- virtual void GetTypeID(std::string &str) : factory mapping key
Member access
- int IncNbPaths(int nNbPaths=1) : increment the number of concurrent paths
- int DecNbPaths() : decrement the number of concurrent paths
- int GetNbPaths() : return current number of concurrent paths
Barrier node for synchronization.
[FsfBarrier.h]
Data members
- CCriticalSection m_csFilter : lock for active filter
- CActiveFilterBase* m_pFilter : active filter for wait condition
- Time m_tTimeOut : time-out for wait condition
Member functions
Constructors, destructor and other functions that are part of any derived
node class
- CBarrier() : default constructor
- CBarrier(CNode *pParent, fsf::Time tTime=0) : initialization constructor
- CBarrier(const std::string &strName, fsf::Time tTime=0) :
initialization constructor
- CBarrier(CActiveFilterBase *pFilter, fsf::CNode *pParent=NULL, fsf::Time tTime=0) :
initialization constructor
- CBarrier(const std::string &strName, CActiveFilterBase *pFilter, fsf::CNode
*pParent=NULL, fsf::Time tTime=0) : initialization constructor
- CBarrier(const CBarrier& rhs) : copy constructor
- virtual ~CBarrier() : virtual destructor
- CBarrier& operator=(const CBarrier& rhs) : assignment operator
- virtual CNode* Clone() : virtual cloning member function (necessary for
run-time polymorphism)
- virtual void GetTypeID(std::string &str) : factory mapping key
Memory allocation
- virtual void Allocate() : allocate data buffer of size m_nSize
Member access
- void SetFilter(CActiveFilterBase *pFilter) : set filter
- CActiveFilterBase *GetFilter() : return filter
- void SetTimeOut(Time tTime) : set time-out value
- Time GetTimeOut() const : return time-out value
Operations
- bool Filter(CActivePulse *pPulse) : return result of applying current
filter to pulse
Character buffer node.
[FsfCharBuffer.h]
Data members
- CCriticalSection m_csData : lock for data buffer
- long m_nSize : buffer size, in number of characters (bytes)(0)
- char* m_pData : pointer to character buffer (NULL)
Member functions
Constructors, destructor and other functions that are part of any derived
node class
- CCharBuffer() : default constructor
- CCharBuffer(CNode *pParent, fsf::Time tTime=0) : initialization constructor
- CCharBuffer(const std::string &strName, fsf::Time tTime=0) :
initialization constructor
- CCharBuffer(long nSize, fsf::CNode *pParent=NULL, fsf::Time tTime=0) :
initialization constructor
- CCharBuffer(const std::string &strName, long nSize, fsf::CNode
*pParent=NULL, fsf::Time tTime=0) : initialization constructor
- CCharBuffer(const CCharBuffer& rhs) : copy constructor
- virtual ~CCharBuffer() : virtual destructor
- CCharBuffer& operator=(const CCharBuffer& rhs) : assignment operator
- virtual CNode* Clone() : virtual cloning member function (necessary for
run-time polymorphism)
- virtual void GetTypeID(std::string &str) : factory mapping key
Memory allocation
- virtual void Allocate() : allocate data buffer of size m_nSize
Member access
- long Size() const : return buffer size
- char *Data() : return pointer to character buffer
- void LockData() : enter critical section for data buffer access
- void UnlockData() : exit critical section for data buffer access
- void CCharBuffer::CopyData(const CCharBuffer &rhs) : copy data buffer,
assume m_pData is either NULL (in which case it is allocated) or, if already
allocated, of same size as rhs.m_pData
- char *DetachData() : return pointer to current m_pData and set m_pData to
NULL, may be used at node destruction time to avoid duplicating copying buffer
CNode "FSF_NODE"
Base node class. [FsfNode.h]
Data members
- CNode* m_pParent : pointer to parent node (NULL)
- volatile fsf::Time m_tTime : node (sample) time stamp in ns (0)
- volatile fsf::Time m_tDuration : node (sample) duration in ns (0)
- CCriticalSection m_csName : Lock for node name string
- std::string m_strName : Node name ("")
- volatile bool m_bNotDeleted : "Not deleted" flag (true)
- volatile bool m_bNoDelete : "No delete" flag (false)
- volatile int m_nNbHandleRefs : Handle reference counter (0)
- CCriticalSection m_csComponents : Lock for subnode list
- std::list<CNode*> m_listComponents : Subnode list
Member functions
Constructors, destructor and other functions that are part of any derived node class
- CNode() : default constructor
- CNode(CNode *pParent, fsf::Time tTime=0) : initialization constructor
- CNode(const std::string &strName, CNode *pParent=NULL, fsf::Time tTime=0)
: initialization constructor
- CNode(const CNode& rhs) : copy constructor
- virtual ~CNode() : virtual destructor
- CNode& operator=(const CNode& rhs) : assignment operator
- virtual CNode* Clone() : virtual cloning member function (necessary for
run-time polymorphism)
- virtual void GetTypeID(std::string &str) : factory mapping key
Member access
- void SetTime(fsf::Time tTime) : set node time stamp
- fsf::Time GetTime() const : get node time stamp
- void SetDuration(fsf::Time tDuration) : set node duration
- fsf::Time GetDuration() const : get node duration
- void SetName(const std::string &strName) : set node name (locks/unlocks
the string)
- void GetName(std::string &strName) : get node name (locks/unlocks the
string)
Wildcard matching
- bool TestNameExact(const std::string &str) const : check name for string
equality
- bool TestNameWildcard(const std::string &str) const : check name for
string pattern with wildcards
- bool WildcardMatch(const std::string &strWildcard, const std::string
&strTest) const : check string for wildcard pattern (std::string interface)
- bool WildcardMatch(const char *wildcard, const char *test) const : check
string for wildcard pattern (char* interface, called by std::string interface
WildcardMatch function)
- bool Set (const char **wildcard, const char **test) const : wildcard check
helper function
- bool Star (const char **wildcard, const char **test) const : wildcard
check helper function
Special tree organization functions
- virtual CPulse* GetPulse() : get pointer to the node's root pulse (or NULL
if none) (overloaded in pulses)
- void SetParent(CNode *pParent) : set node's parent pointer
- CNode* GetParent() const : get pointer to node's parent (or NULL if none)
- virtual void AddComponent(CNode *pNode) : add node to front of list of
subnodes
- virtual void AddComponent(CNode *pNode, int nMode, CNode *pReference=NULL)
: add node to list of subnodes at specified location
- virtual bool RemoveComponent(CNode *pNode) : remove node from list of
subnodes
- virtual void GenerateChildrenList(std::list<CNode*> &listNode) :
return a list of pointers to subnodes
- virtual void GenerateChildrenHandleList(std::list<CPassiveHandle*>
&listHandles) : return a list of passive handles to subnodes
Reference counting and garbage collecting
- int IncNbHandleRefs() : increment handle reference counter (return updated value)
- int DecNbHandleRefs() : decrement handle reference counter (return updated
value)
- bool IsRefFree() const : check if handle reference counter is zero
- bool IsNotDeleted() const : check if the node is not marked as deleted
- void SetDeleted() : mark the node as deleted (non recursive). Should not
be called from outside (use Delete member function).
- bool CanDelete() const : check whether the node can be marked as deleted
- void SetNoDelete(bool bNoDelete=true) : mark the node as not to be marked
for deletion
- virtual bool Delete(bool bForce=false) : mark the node and
all the nodes its subnodes (recursively) as deleted if allowed (check for
NoDelete flag). Return true if all nodes could be marked as deleted.
- virtual void CleanUpComponents(std::list<CNode*> &listNodes) :
recursive garbage collecting on tree rooted by this node. Actually deallocate
memory for all nodes marked as deleted and reference free.
Passive pulse. [FsfPulse.h]
Member functions
Constructors, destructor and other functions that are part of any derived node class
- CPassivePulse() : default constructor
- CPassivePulse(const std::string &strName, fsf::Time tTime=0) :
initialization constructor
- CPassivePulse(const CActivePulse& rhs) : copy constructor
- CPassivePulse& operator=(const CPassivePulse& rhs) : assignment operator
- virtual CNode* Clone() : virtual cloning member function (necessary for
run-time polymorphism)
- virtual void GetTypeID(std::string &str) : factory mapping key
Special tree organization functions
- void DetachComponents(std::list<CNode*> &listComponents) : remove
components, put them in listComponents
Garbage collecting
- void CleanUpComponents() : garbage collecting; recursively destroy nodes
that are reference free
CPulse (CNode) "FSF_PULSE" - no
factory
Pulse base class. [FsfPulse.h]
Member functions
Constructors, destructor and other functions that are part of any derived node class
- CPulse() : default constructor
- CPulse(const std::string &strName, fsf::Time tTime=0) : initialization
constructor
- CPulse(const CPulse& rhs) : copy constructor
- CPulse& operator=(const CPulse& rhs) : assignment operator
- virtual CNode* Clone() : virtual cloning member function (necessary for
run-time polymorphism)
- virtual void GetTypeID(std::string &str) : factory mapping key
Special tree organization functions
- virtual CPulse* GetPulse() : specialization: return pointer to current
instance pulse root)
Type node template class. [FsfTypeNode.h]
Data members
- Type m_tData : mamber of template type argument Type
Member functions
Constructors, destructor and other functions that are part of any derived node class
- CTypeNode() : default constructor
- CTypeNode(CNode *pParent, fsf::Time tTime=0) : initialization constructor
- CTypeNode(const std::string &strName, CNode *pParent=NULL, fsf::Time
tTime=0) : initialization constructor
- CTypeNode(const Type &val, const std::string &strName, CNode
*pParent=NULL, fsf::Time tTime=0) : initialization constructor
- CTypeNode(const CTypeNode& rhs) : copy constructor
- CTypeNode& operator=(const CTypeNode& rhs) : assignment operator
- virtual void GetTypeID(std::string &str) : factory mapping key
Member access
- void SetData(const Type &val) : set member value
- void GetData(Type &val) const : get member value
- const Type& GetData() const : get member value
CTypeNodeBase (CNode)
"FSF_TYPE_NODE_BASE" - no factory
Base type node. [FsfTypeNode.h]
Member functions
Constructors, destructor and other functions that are part of any derived node class
- CTypeNodeBase() : default constructor
- CTypeNodeBase(CNode *pParent, fsf::Time tTime=0) : initialization
constructor
- CTypeNodeBase(const std::string &strName, CNode *pParent=NULL, fsf::Time
tTime=0) : initialization constructor
- CTypeNodeBase(const CTypeNodeBase& rhs) : copy constructor
- CTypeNodeBase& operator=(const CTypeNodeBase& rhs) : assignment operator
- virtual void GetTypeID(std::string &str) : factory mapping key
Typedef for CTypeNode<float>. [FsfTypeNode.h]
Typedef for CTypeNode<double>. [FsfTypeNode.h]
Typedef for CTypeNode<long int>.
[FsfTypeNode.h]
Typedef for CTypeNode<long long int>.
[FsfTypeNode.h]
Typedef for CTypeNode<std::string>.
[FsfTypeNode.h]
The Fsf library contains a base cell class, that implements cell-cell and
cell-source connectivity mechanisms (lists of pointers). It also implements
all the computation associated with the parallel processing of active pulses.
In MFSM, in each cell, each active pulse is processed in a separate thread.
Each passive filtering operation is also carried in a separate thread. As a
result, some precautions must be taken for concurrent data access. Thanks to
inheritance and virtual functions, when implementing a specialized cell
derived from the base cell, only the specific computation must be coded, in an
overloaded process virtual member funtion. All the events leading to the call
to this process function, including filtering, will be automatically
performed. A cell can be active or inactive. For efficiency purposes,
passive filtering only occurs when the cell is activated (activation fails if
passive filtering fails), and when explicitely notified by the source after a
cell notified the source of a structural change in the passive pulse.
If the root of the active filter specifies a pattern, the specialized process
function is invoked for each handle generated by the filtering (sequentially,
in the same thread). If the root of the passive filter specifies a pattern,
only one passive handle is generated (pointing to the first encountered node
satisfying the pattern).
This section details each cell class defined in the FSF library. Classes are
listed in alphabetical order, according to the following format:
- Title: CCellClassName (CBaseCellClassName) "CELL_TYPE_ID"
- Logical level specifications
| Active filter | [NODE_TYPE_ID "Default node name"] |
| Passive filter | [NODE_TYPE_ID "Default node name"] |
| Output | (NODE_TYPE_ID "Default output base name--more if needed") |
- Short Description [header].
- Data members : type m_iName: description (default value and/or range when
applicable)
- Member functions: type Name(params): description.
Cells
Template instances
Value access cells
<--
Figure 2: Cell classes inheritance hierarchy
-->
Typedef for CTypeCell<bool>. [FsfTypeCell.h]
CCell "FSF_CELL"
Base cell. [FsfCell.h]
Data members
- volatile bool m_bActive : active flag
- volatile bool m_bReset : reset flag
- CCriticalSection m_csOutputName : critical section lock for output name
string
- std::string m_strOutputName : base name to use for output
- bool m_bPassThrough : pass through flag
- volatile WORD m_wNbPassiveThreads : Number of passive threads
- CCriticalSection m_csPassiveFilter : critical section lock for passive
filter
- CPassiveFilterBase* m_pPassiveFilter : pointer to passive filter root
- CCriticalSection m_csPassiveHandle : critical section lock for passive
handle
- CPassiveHandle *m_pPassiveHandle : pointer to passive handle root
- volatile Csource *m_pSource : pointer to source (passive stream)
- volatile WORD m_wNbActiveThreads : number of active threads
- CCriticalSection m_csActiveFilter : critical section lock for active
filter
- CActiveFilterBase* m_pActiveFilter : pointer to active filter root
- volatile Ccell *m_pUpstreamCell : pointer to upstream cell (active stream)
- CCriticalSection m_csDownstream : critical section lock for list of
downstream cells (active stream)
- std::list<CCell*> m_listDownstream : list of downstream cells
(active stream)
Member functions
Constructors, destructor and other functions that are part of any derived
cell class
- CCell() : default constructor
- virtual ~CCell() : virtual destructor
- virtual void GetTypeID(std::string &str) : factory mapping key; must be
overloaded in any derived cell
Member access
- WORD GetNbPassiveThreads() : return number of passive threads
- WORD GetNbActiveThreads() : return number of active threads
- bool IsActive() const : check if cell is currently active (switched on)
Passive stream connections
- void SetSource(CSource *pSource) : set pointer to source
- CSource *GetSource() : get pointer to source
Passive stream processing
- inline void StartPassiveThread(CPassivePulse *pPulse=NULL, bool
bTransmit=true) : interface function for thread triggering, starts a new
thread whose entry point is PassiveThreadProc
- inline static UINT PassiveThreadProc(LPVOID pParam) : thread entry
function for passive stream update, routes the pulse if necessary and calls
PassiveThread
- virtual bool PassiveThread(CPassivePulse *pPulse) : triggered by passive
stream update, force passive pulse (re-)filtering
Active stream connections
- CCell *GetUpstreamCell() : get pointer to upstream cell (active stream)
- void ConnectDownstream(CCell *pCell) : add pointer to list of downstream
cells (active stream)
- void DisconnectDownstreamCell(Ccell *pCell=NULL) : remove pointer to
downstream cell (active stream); remove all pointers if argument is NULL
Active stream processing
- inline void StartActiveThread(CActivePulse *pPulse=NULL) : interface
function for thread triggering, starts a new thread whose entry point is
ActiveThreadProc
- inline static UINT ActiveThreadProc(LPVOID pParam) : thread entry function
for active stream processing, calls ActiveThread function
- virtual bool ActiveThread(CPassivePulse *pPulse) : active thread function
calls Process function if needed
- virtual void Process(CPassiveHandle *pPassiveHandle, CActiveHandle
*pActiveHandle, CActivePulse *pActivePulse) : custom processing place holder,
called by ActiveThread; should be overloaded in all derived cells
Flow control
- virtual bool Switch(bool bOn) : toggle processing; switch on succeeds only
if passive filtering succeeds
- bool On() : shortcut for Switch(true)
- bool Off() : shortcut for Switch(false)
- virtual void Reset() : set reset flag to true
CCharBuffer size value access cell (get only).
[FsfCharBuffer.h]
Member functions
Constructors, destructor and other functions that are part of any derived cell class
- CCharBufferSize() : default constructor
- virtual void GetTypeID(std::string &str) : factory mapping key
ActiveStream processing
- virtual void Process(fsf::CPassiveHandle *pPassiveHandle,
fsf::CActiveHandle *pActiveHandle, fsf::CActivePulse *pActivePulse):
specialized processing function
CNode name value access cell (get only).
[FsfNodeCells.h]
Member functions
Constructors, destructor and other functions that are part of any derived cell class
- CNodeName() : default constructor
- virtual void GetTypeID(std::string &str) : factory mapping key
ActiveStream processing
- virtual void Process(fsf::CPassiveHandle *pPassiveHandle,
fsf::CActiveHandle *pActiveHandle, fsf::CActivePulse *pActivePulse):
specialized processing function
CNode time stamp value access cell (get only).
[FsfNodeCells.h]
Member functions
Constructors, destructor and other functions that are part of any derived cell class
- CNodeTimeStamp() : default constructor
- virtual void GetTypeID(std::string &str) : factory mapping key
ActiveStream processing
- virtual void Process(fsf::CPassiveHandle *pPassiveHandle,
fsf::CActiveHandle *pActiveHandle, fsf::CActivePulse *pActivePulse):
specialized processing function
CNode type ID value access cell (get only).
[FsfNodeCells.h]
Member functions
Constructors, destructor and other functions that are part of any derived cell class
- CNodeTypeID() : default constructor
- virtual void GetTypeID(std::string &str) : factory mapping key
ActiveStream processing
- virtual void Process(fsf::CPassiveHandle *pPassiveHandle,
fsf::CActiveHandle *pActiveHandle, fsf::CActivePulse *pActivePulse):
specialized processing function
Pulsar cell. [FsfPulsar.h]
Member functions
Constructors, destructor and other functions that are part of any derived cell class
- CPulsar() : default constructor
- virtual ~CPulsar() : virtual destructor
- virtual void GetTypeID(std::string &str) : factory mapping key
Flow control
- virtual bool Switch(bool bOn) : toggle processing function overlaod
Pulsing
- void StartPulsarThread() : interface function for thread triggering,
starts a new thread whose entry point is PulsarThreadProc
- static UINT PulsarThreadProc(LPVOID pParam) : thread entry function for
pulsar thread; while cell is active, call Pulse function and sleep for a given
amount of time
- void Pulse() : pulse generation function
Barrier synchronization cell. Holds the incoming active pulse until filtering
with the active pulse specified in the Barrier node
succeeds or the operation times-out (time-out value specified in the barrier
node). [FsfBarrier.h]
Member functions
Constructors, destructor and other functions that are part of any derived cell class
- CSync() : default constructor
- virtual void GetTypeID(std::string &str) : factory mapping key
Active stream processing
- virtual void Process(CPassiveHandle *pPassiveHandle, CActiveHandle
*pActiveHandle, CActivePulse *pActivePulse) : specialized process function;
gets into a well-behaved wait loop
| Active filter | [Type "*"]* |
| Passive filter | [Type "*"] |
| Output | (Type "Output") |
Type cell template class. Modified semantics for process function to
implement get and set value. [FsfTypeCell.h]
Member functions
Constructors, destructor and other functions that are part of any derived cell class
- CTypeCell() : default constructor
- virtual void GetTypeID(std::string &str) : factory mapping key
Active stream processing
- virtual void Process(CPassiveHandle *pPassiveHandle, CActiveHandle
*pActiveHandle, CActivePulse *pActivePulse) : specialized process function;
special semantics, active handle can be null (=get value) or non null (=set
value)
CTypeCellBase (CCell) "FSF_TYPE_CELL_BASE" - no factory
Type cell base class. Implements modified semantics for its process member
function in order to perform the get and set operations. [FsfTypeCellBase.h]
Member functions
Constructors, destructor and other functions that are part of any derived
cell class
- CTypeCellBase() : default constructor
- virtual void GetTypeID(std::string &str) : factory mapping key
Active stream processing
- virtual bool ActiveThread(CPassivePulse *pPulse) : specialized active
thread function, calls Process function if needed; semantics are slightly
modified for the type cell to handle get and set value operations, active
handle can be null (=get value) or non null (=set value)
- virtual void Process(CPassiveHandle *pPassiveHandle, CActiveHandle
*pActiveHandle, CActivePulse *pActivePulse) : place holder process function;
special semantics, active handle can be null (=get value) or non null (=set
value)
Typedef for CTypeCell<float>. [FsfTypeCell.h]
Typedef for CTypeNode<double>. [FsfTypeCell.h]
Typedef for CTypeCell<long int>.
[FsfTypeCell.h]
Typedef for CTypeCell<long long int>. [FsfTypeCell.h]
Typedef for CTypeCell<std::string>. [FsfTypeCell.h]
This section details all the classes defined in the FSF library not described
in the previous sections. These include classes for source, filters, handles,
factories and system objects.
Source. The source class is fairly simple. It holds a
single passive pulse, and keeps a list of pointers to connected cells. Note
that connectors are not implemented as objects, but simply lists of pointers
in the components. This results from the simplicity of the role played by
connectors in the SAI style. In particular, they do not perform any
computation. Sources also perform garbage collecting on their passive pulse
when notified of a structural change by a connected cell.
Filters. Two sets of classes are implemented, for active and
passive filters respectively. For each, a template class derived from a non
template base class provides support for intantiating filters corresponding to
any node type. The non template base class allows to have pointers to
undetermined filters (e.g. in cells). The filter objects also implement the
filtering functionality. Active filtering instantiates and returns a list of
active handles, passive filtering instantiates and returns a list of passive
handles.
Handles. Two sets of classes are implemented, for active and
passive handles respectively. Active handle simply provide a pointer to a
node in an active pulse. An optional handle ID, inherited during the
filtering operation, allows to identify the node with respect to the filter.
Passive handles play the additional role of locks for node deletion and
garbage collecting (not required in active pulses). When a cell removes a
node, it does not destroy it, but marks it as deleted, so it is not used in
subsequent filtering operations. The cell must notify the source, which in
turns notify all connected cells to re-filter the passive pulse, and initiates
a garbage collecting process, which will physically deleted the node when is
it free of handles from ongoing process.
Factories. Class factories are used to instantiate objects
at run time, whose type is not known at compile time. Since cells and nodes
constitute extensible sets of specialized object types derived from respective
base classes, Cell and Node factories a necessary for instantiating cells and
nodes at run time, and modify application graphs dynamically. Node factories
also allow to instantiate filters for the corresponding node type.
System. By convention, any application using FSF must have a
single instance of the System type. The corresponding class therefore
implements the Singleton pattern, so that this unique instance is
automatically created the first time it is needed. This object provides the
reference clock, and holds the lists of node and cell factories available for
building application graphs. In order to use a module in an application, its
node and cell factories must be declared and registered with the system
instance.
Classes are listed in alphabetical order.
Source:
Filters:
Handles:
Factories:
System:
Active filter template class. [FsfFilter.h]
Member functions
Constructors, destructor and cloning
- CActiveFilter() : default constructor
- CActiveFilter(const std::string &strName, long nFilterID=-1, bool
bOptional=false) : initialization constructor
- CActiveFilter(const CActiveFilter &f) : copy constructor
- virtual CActiveFilterBase *Clone() : cloning function
Type checking
- virtual bool TestType(CNode *pNode) : checks pNode type compatibility with
template node class; use C++ dynamic_cast operator (requires RTTI)
Virtual base active filter class. [FsfFilter.h]
Data members
- std::list<CActiveFilterBase*> m_listChildren : list of subfilters
Member functions
Constructors, destructor and cloning
- CActiveFilterBase() : default constructor
- CActiveFilterBase(const std::string &strName, long nFilterID=-1, bool
bOptional=false) : initialization constructor
- CActiveFilterBase(const CActiveFilterBase &f) : copy constructor
- virtual ~CActiveFilterBase() : virtual destructor
- virtual CActiveFilterBase *Clone()=0 : virtual cloning function, must be
overloaded in all non virtual derived classes
Tree functions
- void GetChildren(std::list<CActiveiveFilterBase*> &listFilters) :
return pointers to children in listFilters
- void AddChild(CActiveFilterBase *pFilter) : add pFilter to list of child filters
Type checking
- virtual bool TestType(CNode *pNode) : virtual type checking function,
should be overloaded in derived classes
Filtering
- bool Filter(std::list<CActiveHandle*> &listHandles, CNode *pRoot) :
high level filtering function, call FilterExact or FilterWildcard depending on
wildcard flag; active filtering does not use handles since nodes cannot be
destroyed in active pulse
- bool FilterExact(std::list<CActiveHandle*> &listHandles, CNode
*pRoot) : high level exact filtering function (for exact node name)
- bool FilterWildcard(std::list<CActiveHandle*> &listHandles, CNode
*pRoot) : high level wildcard filtering function (for name pattern)
- bool MatchInRootList(std::list<CActiveHandle*> &listHandles,
std::list<CNode*> &listNodes) : call MatchInRootListExact or
MatchInRootListWildcard depending on wildcard flag
- bool MatchInRootListExact(std::list<CActiveHandle*> &listHandles,
std::list<CNode*> &listNodes) :
- bool MatchInRootListWildcard(std::list<CActiveHandle*> &listHandles,
std::list<CNode*> &listNodes) :
- bool MatchInList(std::list<CActiveHandle*> &listHandles,
std::list<CNode*> &listNodes, std::list<CNode*>::iterator &it) :
call MatchInListExact or MatchInListWildcard depending on wildcard flag
- bool MatchInListExact(std::list<CActiveHandle*> &listHandles,
std::list<CNode*> &listNodes, std::list<CNode*>::iterator &it) :
- bool MatchInListWildcard(std::list<CActiveHandle*> &listHandles,
std::list<CNode*> &listNodes, std::list<CNode*>::iterator &it) :
- bool MatchInList(std::list<CActiveHandle*> &listHandles,
std::list<CNode*> &listNodes, std::list<CNode*>::iterator &it) :
call MatchInListExact or MatchInListWildcard depending on wildcard flag
- bool MatchInListExact(std::list<CActiveHandle*> &listHandles,
std::list<CNode*> &listNodes, std::list<CNode*>::iterator &it) :
- bool MatchInListWildcard(std::list<CActiveHandle*> &listHandles,
std::list<CNode*> &listNodes, std::list<CNode*>::iterator &it) :
- bool MatchNode(std::list<CActiveHandle*> &listHandles, CNode *pNode)
: call MatchNodeExact or MatchNodeWildcard depending on wildcard flag
- bool MatchNodeExact(std::list<CActiveHandle*> &listHandles, CNode
*pNode) :
- bool MatchNodeWildcard(std::list<CActiveHandle*> &listHandles, CNode
*pNode) :
- bool MatchSubnodes(std::list<CActiveFilterBase*> &listFilters,
std::list<CNode*> &listNodes, std::list<CActiveHandle*>
&listHandles) :
Active handle. [FsfHandle.h]
Data members
- std::list<CActiveHandle*> m_listChildren : list of child handles
- CNode *m_pNode : pointer to pulse node
- long m_nHandleID : handle ID inherited from filter
Member functions
Constructors and destructor
- CActiveHandle() : default constructor
- CActiveHandle(CNode *pNode, long nHandleID) : initialization constructor
- CActiveHandle(const CActiveHandle &h) : copy constructor
- ~CActiveHandle() : destructor
Member access
- long GetHandleID() const : return handle ID
- void SetNode(CNode *pNode) : set node pointer, should not change during
life time of handle (called only from constructor)
- void ReleaseNode() :
- CNode *GetNode() const : return pointer to node
- void GetChildren(std::list &listHandles) : return list of
child handles
- void AddChild(CActiveHandle *pHandle) : add handle to list of child handle
Cell factory template class. [FsfClassFactories.h]
Member functions
Constructors and destructor
- CCellFactoryBase() : default constructor
- CCellFactoryBase(const std::string& strName) : initialization constructor
- CCellFactoryBase(const std::string& strName, const std::string& strAuthor)
: initialization constructor
- CCellFactoryBase(const std::string& strName, const std::string& strAuthor,
const std::string& strThanks) : initialization constructor
- CCellFactoryBase(const CCellFactory &rhs) : copy constructor
Instantiation
- virtual void *Instantiate() : class instantiation function, return new
cell of class C
Cell factory base class. [FsfClassFactories.h]
Member functions
Constructors
- CCellFactoryBase() : default constructor
- CCellFactoryBase(const std::string& strName) : initialization constructor
- CCellFactoryBase(const std::string& strName, const std::string& strAuthor)
: initialization constructor
- CCellFactoryBase(const std::string& strName, const std::string& strAuthor,
const std::string& strThanks) : initialization constructor
- CCellFactoryBase(const CCellFactoryBase &rhs) : copy constructor
Virtual base class factory class. [FsfClassFactories.h]
Data members
- std::string m_strName : class name
- std::string m_strAuthor : class author
- std::string m_strThanks : acknowledgements
Member functions
Constructors and destructor
- CClassFactoryBase() : default constructor
- CClassFactoryBase(const std::string& strName) : initialization constructor
- CClassFactoryBase(const std::string& strName, const std::string&
strAuthor) : initialization constructor
- CClassFactoryBase(const std::string& strName, const std::string&
strAuthor, const std::string& strThanks) : initialization constructor
- CClassFactoryBase(const CClassFactoryBase &rhs) : copy constructor
- virtual ~CClassFactoryBase() : virtual destructor
Member access
- void GetName(std::string &str) const : return class name
- void GetAuthor(std::string &str) const : return author name
- void GetThanks(std::string &str) const : return acknowledgements
Class instantiation
- virtual void *Instantiate()=0 : virtual class instantiation function, must
be defined in all non virtual derived classes
Filter base class. [FsfFilter.h]
Data members
- std::string m_strName : node name or name pattern
- bool m_bWildcard : wildcard flag for name matching
- long m_nFilterID : filter ID to be passed to corresponding generated
handles
- bool m_bOptional : optional filter flag
Member functions
Constructors and destructor
- CFilter() : default constructor
- CFilter(const std::string &strName, long nFilterID=-1, bool
bOptional=false) : initialization constructor
- CFilter(const CFilter &f) : copy constructor
- virtual ~CFilter() : virtual destructor
Member access
- void SetName(std::string &strName) : set name or name pattern, set widcard
flag accordingly
- void GetName(std::string &strName) const : get name or name pattern
- void SetFilterID(long nFilterID) : set filter ID
- long GetFilterID() const : get filter ID
- bool SetOptional(bool bOptional=true) : set optional filter flag
- bool IsOptional() const : get optional filter flag
Helper functions
- void SetWildcardFlag() : set wildcard flag according to name or name
pattern
Node factory template class. [FsfClassFactories.h]
Member functions
Constructors and destructor
- CNodeFactory() : default constructor
- CNodeFactory(const std::string& strName) : initialization constructor
- CNodeFactory(const std::string& strName, const std::string& strAuthor) :
initialization constructor
- CNodeFactory(const std::string& strName, const std::string& strAuthor,
const std::string& strThanks) : initialization constructor
- CNodeFactory(const CNodeFactory &rhs) : copy constructor
Instantiation
- virtual void *Instantiate() : class instantiation function, return new
node of class N
- virtual CPassiveFilterBase* MakePassiveFilter(const std::string &str) :
passive filter instantiation function, return new passive filter for node type
N and name str
- virtual CActiveFilterBase* MakeActiveFilter(const std::string &str) :
active filter instantiation function, return new active filter for node type N
and name str
Node factory virtual base class. [FsfClassFactories.h]
Member functions
Constructors
- CNodeFactoryBase() : default constructor
- CNodeFactoryBase(const std::string& strName) : initialization constructor
- CNodeFactoryBase(const std::string& strName, const std::string& strAuthor)
: initialization constructor
- CNodeFactoryBase(const std::string& strName, const std::string& strAuthor,
const std::string& strThanks) : initialization constructor
- CNodeFactoryBase(const CNodeFactoryBase &rhs) : copy constructor
Instantiation
- virtual CPassiveFilterBase* MakePassiveFilter(const std::string &str)=0 :
virtual passive filter instantiation function, must be defined in all non
virtual derived classes
- virtual CActiveFilterBase* MakeActiveFilter(const std::string &str)=0 :
virtual active filter instantiation function, must be defined in all non
virtual derived classes
Passive filter template class. [FsfFilter.h]
Member functions
Constructors, destructor and cloning
- CPassiveFilter() : default constructor
- CPassiveFilter(const std::string &strName, long nFilterID=-1, bool
bOptional=false) : initialization constructor
- CPassiveFilter(const CPassiveFilter &f) : copy constructor
- virtual CPassiveFilterBase *Clone() : cloning function
Type checking
- virtual bool TestType(CNode *pNode) : checks pNode type compatibility with
template node class; use C++ dynamic_cast operator (requires RTTI)
Virtual base passive filter class. [FsfFilter.h]
Data members
q- std::list<CPassiveFilterBase*> m_listChildren : list of subfilters
Member functions
Constructors, destructor and cloning
- CPassiveFilterBase() : default constructor
- CPassiveFilterBase(const std::string &strName, long nFilterID=-1, bool
bOptional=false) : initialization constructor
- CPassiveFilterBase(const CPassiveFilterBase &f) : copy constructor
- virtual ~CPassiveFilterBase() : virtual destructor
- virtual CPassiveFilterBase *Clone()=0 : virtual cloning function, must be
overloaded in all non virtual derived classes
Tree functions
- void GetChildren(std::list<CPassiveFilterBase*> &listFilters) :
return pointers to children in listFilters
- void AddChild(CPassiveFilterBase *pFilter) : add pFilter to list of child filters
Type checking
- virtual bool TestType(CNode *pNode) : virtual type checking function,
should be overloaded in derived classes
Filtering
- bool Filter(std::list<CPassiveHandle*> &listHandles, CPassiveHandle
*pRootHandle) : high level filtering function, call FilterExact or
FilterWildcard depending on wildcard flag; passive filtering uses handles to
avoid problems if nodes are destroyed by other threads
- bool FilterExact(std::list<CPassiveHandle*> &listHandles,
CPassiveHandle *pRootHandle) : high level exact filtering function (for exact
node name)
- bool FilterWildcard(std::list<CPassiveHandle*> &listHandles,
CPassiveHandle *pRootHandle) : high level wildcard filtering function (for
name pattern)
- bool MatchInRootList(std::list<CPassiveHandle*> &listHandles,
std::list<CPassiveHandle*> &listOtherHandles) : call
MatchInRootListExact or MatchInRootListWildcard depending on wildcard flag
- bool MatchInRootListExact(std::list<CPassiveHandle*> &listHandles,
std::list<CPassiveHandle*> &listOtherHandles) :
- bool MatchInRootListWildcard(std::list<CPassiveHandle*>
&listHandles, std::list<CPassiveHandle*> &listOtherHandles) :
- bool MatchInList(std::list<CPassiveHandle*> &listHandles,
std::list<CPassiveHandle*> &listOtherHandles,
std::list<CPassiveHandle*>::iterator &it) : call MatchInListExact or
MatchInListWildcard depending on wildcard flag
- bool MatchInListExact(std::list<CPassiveHandle*> &listHandles,
std::list<CPassiveHandle*> &listOtherHandles,
std::list<CPassiveHandle*>::iterator &it) :
- bool MatchInListWildcard(std::list<CPassiveHandle*> &listHandles,
std::list<CPassiveHandle*> &listOtherHandles,
std::list<CPassiveHandle*>::iterator &it) :
- bool MatchInList(std::list<CPassiveHandle*> &listHandles,
std::list<CPassiveHandle*> &listOtherHandles) : call MatchInListExact or
MatchInListWildcard depending on wildcard flag
- bool MatchInListExact(std::list<CPassiveHandle*> &listHandles,
std::list<CPassiveHandle*> &listOtherHandles) :
- bool MatchInListWildcard(std::list<CPassiveHandle*> &listHandles,
std::list<CPassiveHandle*> &listOtherHandles) :
- bool MatchSubnode(std::list<CPassiveHandle*>
&listHandles,CPassiveHandle *pNHandle) : call MatchSubnodeExact or
MatchSubnodeWildcard depending on wildcard flag
- bool MatchSubnodeExact(std::list<CPassiveHandle*>
&listHandles,CPassiveHandle *pNHandle) :
- bool MatchSubnodeWildcard(std::list<CPassiveHandle*>
&listHandles,CPassiveHandle *pNHandle) :
- bool MatchNode(std::list<CPassiveHandle*> &listHandles,
CPassiveHandle *pNHandle) : call MatchNodeExact or MatchNodeWildcard depending
on wildcard flag
- bool MatchNodeExact(std::list<CPassiveHandle*> &listHandles,
CPassiveHandle *pNHandle) :
- bool MatchNodeWildcard(std::list<CPassiveHandle*> &listHandles,
CPassiveHandle *pNHandle) :
- bool MatchSubnodes(std::list<CPassiveFilterBase*> &listFilters,
std::list<CPassiveHandle*> &listNodeHandles,
std::list<CPassiveHandle*> &listHandles) :
Active handle. [FsfHandle.h]
Data members
- std::list<CPassiveHandle*> m_listChildren : list of child handles
- CNode *m_pNode : pointer to passive pulse node
- long m_nHandleID : handle ID inherited from filter
Member functions
Constructors and destructor
- CPassiveHandle() : default constructor
- CPassiveHandle(CNode *pNode, long nHandleID) : initialization constructor
- CPassiveHandle(const CPassiveHandle &h) : copy constructor
- ~CPassiveHandle() : destructor
Member access
- long GetHandleID() const : return handle ID
- void SetNode(CNode *pNode) : set node pointer, should not change during
life time of handle (called only from constructor); nodes must keep a count of
passive handle pointers so that they are not physically deleted while still in
use in other threads
- void ReleaseNode() : set node pointer to null, decrement reference counter
in node if needed
- CNode *GetNode() const : return pointer to node
- void GetChildren(std::list &listHandles) : return list of
child handles
- void AddChild(CActiveHandle *pHandle) : add handle to list of child handle
Source. [FsfSource.h]
Data members
- CPassivePulse* m_pPulse : evolving passive pulse held by the source, pulse
address can never change during the life of the source object
- CCriticalSection m_csCells : critical section lock for list of connected
cells (passive stream)
- std::list<CCell*> m_listCells : list of connected cells (passive stream)
Member functions
Constructor and destructor
- CSource() : default constructor
- virtual ~CSource() : virtual destructor
Pulse functions
- CPassivePulse *GetPulse() : return pointer to passive pulse
- void ReplacePulse(CPassivePulse *pPulse, fsf::Time tNewTime=0) : replace
current pulse; local passive pulse address does not change, argument pulse is
deleted, force update on passive stream
- void NotifyPulseUpdate() : force passive filtering for all connected cells
Cell functions
- bool ConnectCell(CCell *pCell) : add cell to list of connected cells
- bool DisconnectCell(CCell *pCell) : remove cell from list of connected
cells
System class. Implements system clock and node and cell factories management.
Follows the Singleton pattern, as exactly one instance of this class must
exists in an MFSM-based application. Although FSF is highly multi-threaded,
the unique instance will be allocated before multi-threading kicks in, and
thus a double lock mechanism is probably not needed...
Maps should be made thread-safe with critical sections. However, for now they
are set at start time and never modified... Critical sections would not hurt
anyways, since the map access is not a highly time critical operation.
Typedefs
- typedef std::map NodeFactoryMap;
- typedef std::map CellFactoryMap;
Data members
Singleton specifics
- static CSystem m_pSingle: pointer to single instance (private)
System clock
- UINT m_uPeriod : minimum timer resolution, in ms (1, cannot be changed)
Class factories
- NodeFactoryMap m_mapNodeFactories : node factories
- CellFactoryMap m_mapCellFactories : cell factories
Member functions
Constructor and destructor
- CSystem() : default constructor (private, should not be called directly)
- ~CSystem() : destructor
Singleton specifics
- static CSystem* GetInstance() : single instance access/creation method.
Returns the single instance, allocates if needed.
System clock
- fsf::Time GetTime() const : return system time, in ns
Node factories management
- void RegisterNodeFactory(std::string &strID, CNodeFactoryBase
*pNodeFactory) : register node factory pNodeFactory under string ID strID
- CNodeFactoryBase *GetNodeFactory(const std::string &strID) : return node
factory corresponding to string ID strID, or NULL if not found
- NodeFactoryMap::const_iterator GetNodeMapBegin() : return node factory map
front (iterator)
- NodeFactoryMap::const_iterator GetNodeMapEnd() : return node factory map
end (iterator)
- void IncNodeMapCI(NodeFactoryMap::const_iterator &itn) : increment node
factory map iterator
Cell factories management
- void RegisterCellFactory(std::string &strID, CCellFactoryBase
*pCellFactory) : register cell factory pCellFactory under string ID strID
- CCellFactoryBase *GetCellFactory(const std::string &strID) : return cell
factory corresponding to string ID strID, or NULL if not found
- CellFactoryMap::const_iterator GetCellMapBegin() : return cell factory map
front (iterator)
- CellFactoryMap::const_iterator GetCellMapEnd() : return cell factory map
end (iterator)
- void IncCellMapCI(CellFactoryMap::const_iterator &itc) : increment cell
factory map iterator
B
C
F
I
S
T