CDPComponent Class

The CDPComponent is the base class for a standard component in the CDP system. More...

Header: #include <CDPSystem/Base/CDPComponent.h>
Inherits: CDPObject,
Inherited By:

Application, CDPEngine, EthernetManager, IOServer, Messenger, and Sine

Public Functions

CDPComponent()
virtual ~CDPComponent()
virtual void AddToSyncInList(CDPPropertyBase *pProperty)
virtual void AddToSyncInList(CDPBaseObject *pObject)
virtual void AddToSyncInOnceList(CDPPropertyBase *pProperty)
virtual void AddToSyncOutList(CDPPropertyBase *pProperty)
virtual void AddToSyncOutList(CDPBaseObject *pObject)
virtual void AddToSyncOutOnceList(CDPPropertyBase *pProperty)
virtual void ConnectRemoteObject(const char *connectionName, const char *remoteObject)
virtual void ConnectRemoteObject(CDPConnector *connector, const char *remoteObject)
virtual void Create(const char *fullName)
void DecreaseDebugLevel()
CDPConnector *FindSubcomponentConnector(const char *subcomponent)
virtual int GetDebugLevel()
double GetFrequency() const
OSAPIMutex &GetMemberAccessMutex() override
double GetPeriod() const override
std::string GetPriorityName() const override
CDPProcess *GetProcess() const override
std::string GetSchedulingGroupName() const override
int GetStateNumber(const char *state)
int GetStateNumber()
std::string GetStateString(int stateNumber)
virtual std::list<std::string> GetSubcomponentNames()
int GetSyncInId() override
int GetSyncOutId() override
virtual void GetUpdatedSubcomponentsStatus(unsigned int &uiStatus) const
virtual void GetUpdatedSuspendStatus(unsigned int &uiStatus) const
void IncreaseDebugLevel()
bool IsInConfigure()
virtual bool IsState(const char *pS)
virtual void LockMemberAccess()
virtual int MessageEventNotify(void *messageEventUpdate)
virtual int MessageExtendedEventNotify(void *messageExtendedEventUpdate)
bool NeedsSync() override
std::string ParentName() const
virtual CDP::CDPCOMPONENT_PRIORITY_e Priority() const
unsigned int Process() override
virtual void QueryStatesMulti(unsigned int requestFromHandle, unsigned int stateNumberToStartFrom)
virtual void RegisterAlarm(CDPAlarm &alarm)
virtual void RegisterRemoteObject(CDPConnector *componentConnector, const char *connectionName, const char *remoteObject = 0)
virtual void RegisterStateProcess(const char *state, CDPCOMPONENT_STATEPROCESS stateProcess, const char *description = 0)
virtual void RegisterStateTransitionHandler(const char *fromState, const char *toState, CDPCOMPONENT_STATETRANSITIONHANDLER transitionHandler, const char *description = 0)
virtual void RegisterSubcomponent(const char *subcomponent, CDPConnector *subcomponentConnector = 0)
virtual void ReleaseMemberAccess()
virtual void RemoveAlarm(CDPAlarm &alarm)
virtual void RemoveFromSyncInList(CDPPropertyBase *pProperty)
virtual void RemoveFromSyncInList(CDPBaseObject *pObject)
virtual void RemoveFromSyncOutList(CDPPropertyBase *pProperty)
virtual void RemoveFromSyncOutList(CDPBaseObject *pObject)
virtual void RemoveParameter(CDPParameter &param)
void RemoveRemoteObject(const char *connectionName)
void RemoveRemoteObject(CDPConnector *connector)
virtual void RunInComponentThread(std::function<void() > command, double delayInSeconds = 0.0)
virtual void SaveXML()
void SetConfiguring(bool bIsInConfigure)
virtual void SetFrequency(double frequency)
virtual void SetPriority(CDP::CDPCOMPONENT_PRIORITY_e priority)
void SetXMLConfigurationFilename(const std::string &fileName)
void SetXMLParser(XMLParser &parser)
bool SignalRoutingOK()
virtual const char *State()
virtual bool SubscribeToEventCallback(CDPConnector &connector, IEventReceiver *pReceiver, unsigned int eventFilter = EVENT_PROPERTY_CHANGE)
virtual void SyncIn(int syncInId = 0, int syncOutId = 0, void *pMessage = nullptr)
virtual void SyncOut(int syncOutId = 0, int syncInId = 0, void *pMessage = nullptr)
bool TimedOut(int usSinceLastTimedOut, int dither)
virtual bool UnsubscribeFromEventCallback(CDPConnector &connector, IEventReceiver *pReceiver, unsigned int eventFilter = EVENT_PROPERTY_CHANGE)
virtual void UpdateComponentAlarmsAndStateAndBlockedStates()
void UpdateTimestamp(uint64_t timestamp) override
virtual void WriteXMLFileDelayed()
std::string &XMLConfigurationFilename()

Reimplemented Public Functions

virtual void Activate() override
virtual void Configure(const char *xml) override
virtual void Destroy() override
virtual void FillNodeChildren(CDP::StudioAPI::NodeStream &serializer) const override
virtual CDP::StudioAPI::CDPNodeType GetNodeType() const override
virtual std::string GetProperty(std::string propertyName) override
virtual XMLElementEx *GetXMLElement() override
virtual const XMLParser &GetXMLParser() const override
virtual XMLParser &GetXMLParser() override
virtual int ReceiveMessage(void *message) override
virtual void SetProperty(std::string propertyName, std::string propertyValue) override
virtual void SetPropertyHandler(CDPPropertyBase *pProp) override
virtual unsigned int Status() const override
virtual void Suspend() override
virtual bool ValidatePropertyHandler(CDP::StudioAPI::CDPVariantValue &newValue, CDPPropertyBase *property) override

Static Public Members

CDPComponent *ComponentPointer(const char *name)
CDPConnector *Parent(std::string childName)

Protected Functions

virtual bool HandleXMLElement(XMLElementEx *pEx)
virtual void ProcessNull()
void UpdateFrequency()
void UpdateScheduler(CDPSchedulable *item)

Reimplemented Protected Functions

virtual void CreateModel() override
virtual void CreateXMLConfigurationFilename(std::string &src, const std::string shortName = "", const char *parentName = NULL) override
virtual void InitializeModel(const char *pzModel) override
virtual void XMLParserCallback(XMLPrimitive *pPrim) override

Protected Variables

CDPAlarm alarmComponentSuspended
AlarmList alarms
CDPProperty<int> debugEx
CDPProperty<double> fs
CDPProperty<std::string> initialState
unsigned int inputObjectStatus
XMLParser m_XMLParser
bool m_bIsInConfigure
bool m_bSaveXML
CDPConnectorMap m_connectorMap
CDPProperty<std::string> m_htmlPage
EventNotifyReceiverList m_listEventNotifyReceivers
SignalBox m_listSignals
XMLPrimitive *m_pSkipToElement
PortList m_ports
CDPProperty<std::string> m_priority
CDPSignal<double> m_processPeriod
CDPSignal<double> m_processTime
unsigned int m_uiCurrentBlockedStates
int m_usSinceLastProcessRun
unsigned int outputObjectStatus
CDPProperty<std::string> overrideState
CDPProperty<bool> overrideStateMachine
ParameterList parameters
CDPConnector parent
std::string requestedState
CDPState *state
unsigned int status
CDPProperty<std::string> strState
SubcomponentConnectionList subcomponentConnections
double ts
double tsInus

Static Protected Members

ComponentMap s_mapComponents
  • 3 static protected members inherited from CDPObject

Detailed Description

The CDPComponent is the base class for a standard component in the CDP system.

The CDPComponent extends the basic object class CDPObject and defines the CDP component interface with functions to simplify initialization and access of signals and subcomponents.

Features:

  • Capability to receive messages and provide message interface information on request.
  • Dynamic text-command message interface for custom message handlers.
  • State machine with custom periodic process methods and state transition handlers.
  • May own CDPObject, CDPAlarm, CDPSignal, CDPParameter, CDPProperty, CDPPort and other CDPComponent objects.
  • Provide information on all owned objects on request.
  • Maintains connections to owned subcomponents and connected remote CDPObjects/CDPComponents.
  • Has a CDPConnector connection to parent (owner) component.

Usage

  • Create a new component using CDP Studio wizard. This will generate necessary code.
  • Optional: Override Activate() and Suspend(). Put code that must be executed every time a component is started (activated) or stopped (suspended) in these methods.

    (Remember to call the base class versions in the overridden methods)

  • Create message handler methods for all messages to be processed.
  • Create state process and state transition methods for the state machine.

State machine usage

Use CDP Studio wizards to add states and state trasitions.

Before every process run, each state transition handler for transitions out of the current state is run to check if a transition should occur. If a transition handler returns true, the corresponding transition takes place. On state change the handler can execute additional appropriate state entry actions and return true.

States can also be identified using numeric identifiers. First registered state==1 and counting upwards for each registered state. Method GetStateNumber() return state index number for a state. This state number can be used as a numeric state identifier.

It is also possible to use the simple periodic process without using state machine by overriding ProcessNull();

CDPConnectors

  • Create a CDPConnector using CDP Studio wizard. This will generate necessary code.
  • Configure the connector in component configuration, inside <Connectors> section. Set the Object attribute to the full name of the object to connect to.
  • Alternatively, if remote object name is known when the connection is created, the constructor of CDPConnector can be called specifying remote name. Create() must also be called, specifying a name of the CDPConnector and the CDPComponent which owns the CDPConnector:
    CDPConnector myConnector("MyRemoteSystem.MyComponent");
    myConnector.Create("MyConnector",this);
  • The created CDPConnector can now be used to send messages to the remote component.

Priority levels and scheduling groups

Each component has a SchedulingGroup property, initially set to 'Default'. The user can change the SchedulingGroup in any component when there is a need for it. All components which have the same SchedulingGroup and the same Priority run in the same thread. The thread name is a concatenation of the first letter in Priority and the full SchedulingGroup string. For instance, if Priority is 'normal' and SchedulingGroup is 'Default', the thread name becomes 'nDefault'.

Distributing components into different SchedulingGroups may enable the full utilization of all available CPU cores.

If all components have their own SchedulingGroup, all the components will run in parallel threads. If all components have the same SchedulingGroup (given they also have the same priority), they will run in the same thread, see Execution order below. If two components have the same SchedulingGroup, but different Priorities, the components will run in two different threads.

Note: If you want to monitor the load of each thread in operating system utilities such as the TaskManager on Windows, or 'htop' on Linux; Be aware that the thread name as displayed in these utilities are cut at 15 characters.

The priorities define the precedence of the threads, where higher priorities are preferred over lower priorities:

  • 'low': Runs process in TASKPRI_LOW priority, recommended for slower, time-consuming tasks.
  • 'normal': Runs process in TASKPRI_NORMAL priority, recommended for most real-time control components.
  • 'high': Runs process in TASKPRI_ABOVEHIGH priority, recommended for fast and time critical real-time control components.
  • Priority level is defined in the model, and may be overridden in component configuration.

Execution order

CDPComponents run when they receive a message or when CDPEngine calls the current state machine process method at specified periodic time interval.

All components and object are designed to function independent and asynchronous, but still it is often desirable to know and control the execution order.

In CDP, the CDPEngine runs all components in this deterministic execution order:

  • Messages are delivered before entering periodic process.
  • Messages are delivered asynchronous and independent of periodic process.
  • Components run in the order they are listed in the component configuration file, when Priority, SchedulingGroup and fs are equal.
  • Application component runs last, when Priority, SchedulingGroup and fs are equal and BottomUp SchedulingOrder is used.
  • Subcomponents run before parent component, when Priority, SchedulingGroup and fs are equal and BottomUp SchedulingOrder is used.
  • Application component runs first, when Priority, SchedulingGroup and fs are equal and TopDown SchedulingOrder is used.
  • Subcomponents run after parent component, when Priority, SchedulingGroup and fs are equal and TopDown SchedulingOrder is used.

Threads

Asynchronous threads can be added by deriving from OSAPIThread, and/or by adding OSAPITask member(s). The thread should be started in Activate() and stopped/deleted in Suspend() so that it will be able to start up again if it is activated after being suspended. A thread can be synchronized with the state-machine by f.i. using an OSAPIEvent. Example:

void MyComponent::Activate()
{
  CDPComponent::Activate();
  OSAPIThread::Start(CDPTHREAD_PRIORITY_NORMAL,ShortName());
}

void MyComponent::Suspend()
{
  CDPComponent::Suspend();
  OSAPIThread::Stop();
  OSAPIThread::Delete();
}

void MyComponent::ProcessRunning()
{
  myEvent.Set();
}

...

void MyComponent::Main()
{
  while(!Stopped())
  {
    myEvent.Wait(); // synchronize.
    myEvent.Reset();
    ...
  }
}

Debugging

The CDPComponent::debugEx member is used to determine how much debug information will be printed to screen. It may be set in the component configuration file.

The following debug levels are defined and used internally, but the users are free to use it as they wish:

0 DEBUGLEVEL_NONEVery little debug output, only fatal errors should be displayed
1 DEBUGLEVEL_NORMALDisplay errors and basic status information. Periodic output should be avoided.
2 DEBUGLEVEL_EXTENDEDDisplay extended info like state changes and similar.
9 DEBUGLEVEL_ALLDisplay very much debug info.

The macros DebugLevel() and DebugLevelForComponent() may be used when testing for the debug level. They will test if the currently set debug level is greater or equal to the specified level, for instance:

if (DebugLevel(DEBUGLEVEL_EXTENDED))
  CDPMessage("%s: Entering state:  %s\n", Name(), state->name);

Note that the DebugLevel macro will use the debugEx member visible where the macro is used.

If the code is within a CDPComponent member function, it will see that instance's debugEx member.

If the code is not within a CDPComponent, the macro will see the global ::debugEx member.

The macro DebugLevelForComponent may be used if a pointer to the component is available:

if (DebugLevelForComponent(m_pParent, DEBUGLEVEL_EXTENDED))
  CDPMessage("%s: New value: %f\n", Name(), GetDouble());

This is useful for instance from within CDPObject derived objects, since they do not have their own debug level, and it is often convenient to print debug messages depending of the parent component's debug level..

Component properties

NameShort name of component
ModelModel type class of component
ActivateActivate delay in s. Set to a low value (< 1.0) to activate early, set to 0 to disable automatic activation.
Description:Instance help description string. Can be configured as value or attribute.
fs:Overrides default process sample frequency.
Debug:Set debug level for component.
InitialState:Sets an initial start up state.
OverrideStateMachine:Set to 1 to override state machine.
OverrideState:The state to put the state machine into when OverrideState is set.
InstanceHelpComponent instance help text.
HtmlPageComponent custom .html page.
CurrentStateThe current State of the component.
PriorityOverride default model priority to instance specific level. Can be "low", "normal" or "high". See Priority levels and scheduling groups for more information.
SchedulingGroupSchedulingGroup is a string that makes up part of the name of a thread the component should run in. See Priority levels and scheduling groups for more information.

Message

CM_REQUESTSTATUSRequest a MessageStatus message (CM_STATUS)
CM_QUERYSTATES_MULTIRequest a MessageStateStringMulti message (CM_STATEINFO_MULTI)
CM_SETFSSet the fs from a MessageFloat or a MessageDouble message
CM_ALARMACKNOWLEDGEiterate through all alarm members and do Acknowledge() on each object.
CM_EVENT_NOTIFYNotify from event subscriber of new events
CM_EVENT_NOTIFY_EXTENDEDNotify from event subscriber of new extended events

Member Function Documentation

CDPComponent::CDPComponent()

Constructs a CDPComponent. Initializes all member variables to safe default values.

[virtual] CDPComponent::~CDPComponent()

Destructs the instance.

[override virtual] void CDPComponent::Activate()

Reimplemented from CDPBaseObject::Activate().

Activates the component, starts message processing and periodic process execution.

Subcomponents must be activated individually.

All components listed in Application configuration with attribute Activate="1" in component configuration will be started automatically.

Connects all subcomponents connections and remote component connections.

Activate the object so it can receive messages and do processing. When this function is called, the member mutex of the CDPComponent (if this is not a CDPComponent: then the member mutex of the object owner) has already been locked.

This function may be called from another thread, typically the main thread or the Application process thread, or from the correct CDPEngine scheduler.

[virtual] void CDPComponent::AddToSyncInList(CDPPropertyBase *pProperty)

Adds a Property to the list of objects to periodically sync in.

See also SyncIn() and AddToSyncInOnceList().

[virtual] void CDPComponent::AddToSyncInList(CDPBaseObject *pObject)

Adds an object to the list of objects to sync in.

See also SyncIn().

[virtual] void CDPComponent::AddToSyncInOnceList(CDPPropertyBase *pProperty)

Syncs in a Property just once.

See also SyncIn() and AddToSyncInList().

[virtual] void CDPComponent::AddToSyncOutList(CDPPropertyBase *pProperty)

Adds a Property to the list of objects to periodically sync out.

See also SyncOut() and AddToSyncInOnceList().

[virtual] void CDPComponent::AddToSyncOutList(CDPBaseObject *pObject)

Adds an object to the list of objects to sync out.

See also SyncOut().

[virtual] void CDPComponent::AddToSyncOutOnceList(CDPPropertyBase *pProperty)

Syncs out a Property just once.

See also SyncOut() and AddToSyncOutList().

[static] CDPComponent *CDPComponent::ComponentPointer(const char *name)

Find the pointer to the CDPComponent object identified by name. Static method.

This method is preferred due to performance increase compared to CDPObject::Pointer() when it is known that the object is derived CDPComponent.

Example:

CDPComponent* pComponent = ComponentPointer("Component.Subcomp");
if (pComponent)
  pComponent->AddSubcomponent(mySubComponent);  // Adds a subcomponent to pComponent

name: The full name of the object.

Returns: Pointer to the CDPComponent-derived object identified by name.

[override virtual] void CDPComponent::Configure(const char *xml)

Reimplemented from CDPObject::Configure().

Configures the Component. Will be called automatically when starting a CDP application.

Opens file if src="filename" specified. Finds and opens file named "Components<component full name>.xml" if xml==0.

[virtual] void CDPComponent::ConnectRemoteObject(const char *connectionName, const char *remoteObject)

Connect an already registered connection to a remote object (remoteObject).

A CDPConnector and connectionName (local name) must have been registered with RegisterRemoteObject() before using this method.

connectionName Local name of connection/object earlier registered with RegisterRemoteObject()

remoteObject Full or relative name of the object to connect to.

[virtual] void CDPComponent::ConnectRemoteObject(CDPConnector *connector, const char *remoteObject)

Connect a connector to a remote object. Normally, the other version of ConnectRemoteObject() is used by components.

connector The connector to use. Will be connected to remoteObject.

remoteObject Full or relative name of the object to connect to.

[virtual] void CDPComponent::Create(const char *fullName)

Create component instance with members (signals, alarms, parameters..).

[override virtual protected] void CDPComponent::CreateModel()

Reimplemented from CDPBaseObject::CreateModel().

Creates a model instance for this class and fills model data.

This is a model method. The changes initiated will affect all components of this type.

Overridden method must always call base implementation.

[override virtual protected] void CDPComponent::CreateXMLConfigurationFilename(std::string &src, const std::string shortName = "", const char *parentName = NULL)

Reimplemented from CDPObject::CreateXMLConfigurationFilename().

Creates .xml configuration file name from component name. Resolves the application component path for application owned components. If shortName is empty, Name() will be used internally. If shortName is specified, shortName and parentName (may be nullptr) are combined and used.

void CDPComponent::DecreaseDebugLevel()

Decrease DebugLevel

[override virtual] void CDPComponent::Destroy()

Reimplemented from CDPBaseObject::Destroy().

Removes references to this component in other objects. Destroy this and all members. This method should reverse what what was done in Create(). Calls CDPObject::Destroy().

[override virtual] void CDPComponent::FillNodeChildren(CDP::StudioAPI::NodeStream &serializer) const

Reimplemented from CDPNode::FillNodeChildren().

CDPConnector *CDPComponent::FindSubcomponentConnector(const char *subcomponent)

Returns connector to subcomponent if found.

[virtual] int CDPComponent::GetDebugLevel()

CDPComponent::GetDebugLevel Returns the debug level of the component

double CDPComponent::GetFrequency() const

Returns the component sampling frequency for this instance.

OSAPIMutex &CDPComponent::GetMemberAccessMutex()

Returns the reference to the member access mutex so it can be used with OSAPIMutexLocker. Take care when using this, as improper usage may cause race conditions.

See also LockMemberAccess() and ReleaseMemberAccess().

[override virtual] CDP::StudioAPI::CDPNodeType CDPComponent::GetNodeType() const

Reimplemented from ICDPNode::GetNodeType().

double CDPComponent::GetPeriod() const

Returns the component sampling period for this instance.

std::string CDPComponent::GetPriorityName() const

CDPProcess *CDPComponent::GetProcess() const

[override virtual] std::string CDPComponent::GetProperty(std::string propertyName)

Reimplemented from CDPBaseObject::GetProperty().

Get property value from property storage. Will call CDPObject and return value for property if propertyName is not found. Specially handled properties are: "Status", "StatusNumber" and "XMLConfigurationFilename".

std::string CDPComponent::GetSchedulingGroupName() const

int CDPComponent::GetStateNumber(const char *state)

Gets numeric state identifier, first state == 1, returns 0 if not found.

int CDPComponent::GetStateNumber()

Get numeric state identifier of current state.

std::string CDPComponent::GetStateString(int stateNumber)

Get string state identifier for numeric state identifier. First state == 1.

[virtual] std::list<std::string> CDPComponent::GetSubcomponentNames()

CDPComponent::GetSubcomponentNames() This function walks through all subcomponents directly owned by this component and fills up a string list containing the full names of said subcomponents

int CDPComponent::GetSyncInId()

int CDPComponent::GetSyncOutId()

[virtual] void CDPComponent::GetUpdatedSubcomponentsStatus(unsigned int &uiStatus) const

Updates the component status caused by the statuses in subcomponents.

Will bitwise OR uiStatus with the status of each subcomponent.

See also Status().

[virtual] void CDPComponent::GetUpdatedSuspendStatus(unsigned int &uiStatus) const

Updates the component status caused by suspend state.

See also Status().

[override virtual] XMLElementEx *CDPComponent::GetXMLElement()

Reimplemented from CDPObject::GetXMLElement().

Get the XMLElement pointing to <Component>

[override virtual] const XMLParser &CDPComponent::GetXMLParser() const

Reimplemented from CDPObject::GetXMLParser().

[override virtual] XMLParser &CDPComponent::GetXMLParser()

Reimplemented from CDPObject::GetXMLParser().

[virtual protected] bool CDPComponent::HandleXMLElement(XMLElementEx *pEx)

Handles creation of objects that have an XML configuration in component configuration file. Handle XMLElement <Name...>

Return true for each element that should not be handled by CDP (properties are generated for unhandled elements)

Example code for handling:

bool MyComponent::HandleXMLElement( XMLElementEx* pEx)
  {
    std::string strElementName=pEx->GetName();

    if(strElementName=="MyElement")
    {
      if(pEx->GetParent()==nullptr)
      {
        // set XML element
        m_pXMLElement = pEx;
        //call base to configure base component stuff such as name etc:
        CDPObject::Configure(pEx);
        return true;  // If true is returned, all child elements are skipped.
      }
    }
    return CDPComponent::HandleXMLElement(pEx); // call baseclass
  }

void CDPComponent::IncreaseDebugLevel()

Increase DebugLevel

[override virtual protected] void CDPComponent::InitializeModel(const char *pzModel)

Reimplemented from CDPBaseObject::InitializeModel().

Creates model.

bool CDPComponent::IsInConfigure()

Return true if component is inside Configure() (use IsInitialized() if you want to find out if Configure() has been run at least once).

[virtual] bool CDPComponent::IsState(const char *pS)

Compares the input state string with the current state and returns true if equal.

[virtual] void CDPComponent::LockMemberAccess()

Should be called before modifying (writing/deleting) objects. It is called by CDPEngine before Transitions, Processes, Messages

See also ReleaseMemberAccess().

[virtual] int CDPComponent::MessageEventNotify(void *messageEventUpdate)

Called by event subscriber to notify subscribed objects that new simple events have arrived.

[virtual] int CDPComponent::MessageExtendedEventNotify(void *messageExtendedEventUpdate)

Called by event subscriber to notify subscribed objects that new extended events have arrived.

bool CDPComponent::NeedsSync()

[static] CDPConnector *CDPComponent::Parent(std::string childName)

Returns pointer to parent connector of childName. Finds the pointer to CDPConnector to the parent (owner) of object 'childName'.

std::string CDPComponent::ParentName() const

Returns parent name.

[virtual] CDP::CDPCOMPONENT_PRIORITY_e CDPComponent::Priority() const

Returns the current priority value.

Returned value is one of the scheduling priority enums in CDP::CDPCOMPONENT_PRIORITY_e.

unsigned int CDPComponent::Process()

Runs the state machine.

This method is called periodically from the CDPEngine. It takes care of the following tasks:

  • Updates the status by or'ing the status of all alarms and all subcomponents.
  • Runs all state transition handlers out of the current state and changes state if a handler returns true.
  • Calls the process function for the current state.
  • Calculates process timer and process period.

Returns Status()

[virtual protected] void CDPComponent::ProcessNull()

Process method for the default initial state of the component. May be overridden.

[virtual] void CDPComponent::QueryStatesMulti(unsigned int requestFromHandle, unsigned int stateNumberToStartFrom)

Sends a message containing many (all, if there is room) state machine state-strings.

[override virtual] int CDPComponent::ReceiveMessage(void *message)

Reimplemented from CDPBaseObject::ReceiveMessage().

Handles incoming messages.

[virtual] void CDPComponent::RegisterAlarm(CDPAlarm &alarm)

Adds an alarm to the component.

[virtual] void CDPComponent::RegisterRemoteObject(CDPConnector *componentConnector, const char *connectionName, const char *remoteObject = 0)

Registers connection to a remote object. componentConnector must always be specified. Either connectionName or remoteObject must be specified, or both of them. If only componentConnector and connectionName are specified, ConnectRemoteObject(connectionName, remoteObject) must be called later.

ConnectRemoteObject() may be used later to connect/change the connection.

componentConnector The connector to use. Will be connected to connectionName and/or remoteObject.

connectionName Local name to use for the connection/object.

remoteObject Full or relative name of the object to connect to.

Assumes that LockMemberAccess() has been called

See also CDPComponent::ConnectRemoteObject().

[virtual] void CDPComponent::RegisterStateProcess(const char *state, CDPCOMPONENT_STATEPROCESS stateProcess, const char *description = 0)

Registers a state machine state.

[virtual] void CDPComponent::RegisterStateTransitionHandler(const char *fromState, const char *toState, CDPCOMPONENT_STATETRANSITIONHANDLER transitionHandler, const char *description = 0)

Registers a state transition handler.

From state and to state must be registered prior to registering the transition.

[virtual] void CDPComponent::RegisterSubcomponent(const char *subcomponent, CDPConnector *subcomponentConnector = 0)

Registers connection to a member subcomponent.

subcomponent Short or full name of subcomponent. Connector will be created using this name if name is specified.

subcomponentConnector Reference to CDPConnector for subcomponent. A connector will be created if a pointer is not specified.

Assumes that LockMemberAccess() is called

[virtual] void CDPComponent::ReleaseMemberAccess()

Must be called after modifying (writing/deleting) objects. It is called by CDPEngine after Transitions, Processes, Messages.

See also LockMemberAccess().

[virtual] void CDPComponent::RemoveAlarm(CDPAlarm &alarm)

Remove alarm must be called before deleting the alarm.

Assumes that LockMemberAccess() has been called

[virtual] void CDPComponent::RemoveFromSyncInList(CDPPropertyBase *pProperty)

Removes an object from the list of objects to sync in.

See also SyncIn().

[virtual] void CDPComponent::RemoveFromSyncInList(CDPBaseObject *pObject)

Removes an object from the list of objects to sync in.

See also SyncIn().

[virtual] void CDPComponent::RemoveFromSyncOutList(CDPPropertyBase *pProperty)

Removes an object from the list of objects to sync out.

See also SyncOut().

[virtual] void CDPComponent::RemoveFromSyncOutList(CDPBaseObject *pObject)

Removes an object from the list of objects to sync out.

See also SyncOut().

[virtual] void CDPComponent::RemoveParameter(CDPParameter &param)

Remove parameter must be called before deleting the parameter.

Assumes that LockMemberAccess() has been called

void CDPComponent::RemoveRemoteObject(const char *connectionName)

Removes remote object connection. Assumes that LockMemberAccess() has been called.

void CDPComponent::RemoveRemoteObject(CDPConnector *connector)

Removes remote object connection. Assumes that LockMemberAccess() has been called.

[virtual] void CDPComponent::RunInComponentThread(std::function<void() > command, double delayInSeconds = 0.0)

Queues the command and runs it in Component thread Process loop after a given delayInSeconds.

This is an alternative to using GetMemberAccessMutex() when modifying CDP objects from another thread, and can also be used to simplify handling timed code.

Example usage, where the transmission alarm will be set after the (current) state-machine has been run:

RunInComponentThread([&] () { m_transmissionAlarm->Set(); });

Another example, where the function 'MyComponent::OpenFirstValve' is executed after a 2 second delay:

void MyComponent::OpenFirstValve()
{
  Valve1On = true;
}

void MyComponent::TransitionStoppedToRunning()
{
  if(Start==true)
  {
    RunInComponentThread(std::bind(&MyComponent::OpenFirstValve, this), 2.0);
    return true;
  }
  else
    return false;
}

Note: The timing-accuracy of RunInComponentThread() is dependent on the component frequency. The objects referred in the provided std::function must live longer than delayInSeconds.

[virtual] void CDPComponent::SaveXML()

Saves component configuration. Take care, as this function blocks. This function can not be called from a process-function as it locks the member access mutex.

See also WriteXMLFileDelayed().

void CDPComponent::SetConfiguring(bool bIsInConfigure)

Called by CDP before and after Configure() is called

[virtual] void CDPComponent::SetFrequency(double frequency)

Set a new update frequency

[virtual] void CDPComponent::SetPriority(CDP::CDPCOMPONENT_PRIORITY_e priority)

Sets the priority to one of the scheduling priority enums in CDP::CDPCOMPONENT_PRIORITY_e.

[override virtual] void CDPComponent::SetProperty(std::string propertyName, std::string propertyValue)

Reimplemented from CDPBaseObject::SetProperty().

Set a property of the object. Called by MessageSetProperty after property name and value has been figured out.

[override virtual] void CDPComponent::SetPropertyHandler(CDPPropertyBase *pProp)

Reimplemented from CDPObject::SetPropertyHandler().

This handler is called when a property changes.

void CDPComponent::SetXMLConfigurationFilename(const std::string &fileName)

Sets the component configuration file name.

void CDPComponent::SetXMLParser(XMLParser &parser)

Copies parser content to the Component's XMLParser.

bool CDPComponent::SignalRoutingOK()

Returns /c true if the Routing of all signals is OK.

[virtual] const char *CDPComponent::State()

Returns current state machine state.

[override virtual] unsigned int CDPComponent::Status() const

Reimplemented from CDPBaseObject::Status().

Returns status of the component.

See also CDPAlarm#Alarm Status Defines.

[virtual] bool CDPComponent::SubscribeToEventCallback(CDPConnector &connector, IEventReceiver *pReceiver, unsigned int eventFilter = EVENT_PROPERTY_CHANGE)

Adds pReceiver to list of objects that will receive a call of their RemotePropertyChanged() function when events from object with handle eventFilter are received. If eventFilter == 0xffffffff, all incoming events from connector will be sent to pReceiver.

[override virtual] void CDPComponent::Suspend()

Reimplemented from CDPBaseObject::Suspend().

Suspends the component, stops message processing and periodic process execution.

Stop the periodic calling of Process() and message processing for CDPObject derived types. The member mutex of the Component or owner object has already been locked when this function is called. This function will be called from the correct CDPEngine scheduler during runtime, or from the main task on shutdown.

[virtual] void CDPComponent::SyncIn(int syncInId = 0, int syncOutId = 0, void *pMessage = nullptr)

SyncIn synchronously clocks signals value from signal external side to signal internal side. CDPComponent will clock all its signals with SyncGroupId==0.

[virtual] void CDPComponent::SyncOut(int syncOutId = 0, int syncInId = 0, void *pMessage = nullptr)

SyncOut synchronously clocks signals value from signal internal side to signal external side. CDPComponent will clock all its signals with SyncGroupId==0.

bool CDPComponent::TimedOut(int usSinceLastTimedOut, int dither)

Called by engine process scheduler to keep track of process periodic interval. Used by the scheduler to determine if it's time to run Process() again.

usSinceLastTimedOut: Microseconds since last run of Process(). dither: Correction for sync error in scheduler process.

Returns true if it is time to call Process() now.

[virtual] bool CDPComponent::UnsubscribeFromEventCallback(CDPConnector &connector, IEventReceiver *pReceiver, unsigned int eventFilter = EVENT_PROPERTY_CHANGE)

Remove pReceiver from list of objects receiving a callback for incoming events from connector with specified filter. Specify eventFilter EVENT_MASK_ALL to remove for all events to this receiver, or another mask to remove only some events.

[virtual] void CDPComponent::UpdateComponentAlarmsAndStateAndBlockedStates()

Updates the component alarms, state and blocked states.

See also Status().

[protected] void CDPComponent::UpdateFrequency()

Updates Frequency calculations based on fs member.

Update the frequency (from fs) of which the scheduler is to call the Process() method for this component instance.

[protected] void CDPComponent::UpdateScheduler(CDPSchedulable *item)

Adds item to Component scheduling context

Depending on item priority, fs and scheduling group the item is added as sub item to current component if all the fields match or into current Process.

void CDPComponent::UpdateTimestamp(uint64_t timestamp)

[override virtual] bool CDPComponent::ValidatePropertyHandler(CDP::StudioAPI::CDPVariantValue &newValue, CDPPropertyBase *property)

Reimplemented from CDPObject::ValidatePropertyHandler().

Called when a property changes. Return true to allow setting newValue to property.

[virtual] void CDPComponent::WriteXMLFileDelayed()

Will trigger the Application worker thread to save the component configuration.

std::string &CDPComponent::XMLConfigurationFilename()

Returns component configuration file name.

[override virtual protected] void CDPComponent::XMLParserCallback(XMLPrimitive *pPrim)

Reimplemented from CDPObject::XMLParserCallback().

After a successful file parse, all elements in the XML tree is sent to this function.

XMLParser callback. Called for each element (<SomeElement/>) in the component configuration file in the order they are defined.

This function is only invoked after a successful parsing of the component configuration file. Example code for handling:

void MyComponent::XMLParserCallback(XMLPrimitive* pPrim)
{
  CDPComponent::XMLParserCallback(pPrim);

  if(pPrim->GetType()==e_XMLElement)
  {
    // We now know we have an XMLElementEx pointer:
    XMLElementEx* pEx = static_cast<XMLElementEx*>(pPrim);
    // Get the name of the element <Signal ... ></Signal>
    std::string strElementName = pEx->GetName(); // should return 'Signal' for a Signal.
    if(strElementName=="Signal" && pEx->GetAttributeValue("Name")=="TestSignal" )
    {
      // treat the <Signal Name="TestSignal" .... /> element further.
    }
  }
}

Member Variable Documentation

CDPAlarm CDPComponent::alarmComponentSuspended

This variable holds this alarm is set if it is Enabled, and the component is suspended.

AlarmList CDPComponent::alarms

This variable holds list of alarm events, instance-specific.

CDPProperty<int> CDPComponent::debugEx

This variable holds set to enable extra debug messages printing.

CDPProperty<double> CDPComponent::fs

This variable holds the ideal frequency (Hz) that the state machine is sheduled on.

CDPProperty<std::string> CDPComponent::initialState

This variable holds inital state after Configure().

unsigned int CDPComponent::inputObjectStatus

This variable holds status of all input objects as calculated in SyncIn().

XMLParser CDPComponent::m_XMLParser

This variable holds the XMLParser object that contains the XML configuration.

bool CDPComponent::m_bIsInConfigure

This variable holds flag indicating if the component is being configured or not.

bool CDPComponent::m_bSaveXML

This variable holds flag for triggering saving the component configuration from the Application worker thread.

CDPConnectorMap CDPComponent::m_connectorMap

This variable holds list of connections to other objects, instance-specific.

CDPProperty<std::string> CDPComponent::m_htmlPage

This variable holds name of html page to serve. If blank, a default component page is used.

EventNotifyReceiverList CDPComponent::m_listEventNotifyReceivers

This variable holds list of eventNotify receivers.

SignalBox CDPComponent::m_listSignals

This variable holds list of signals, instance- specific.

XMLPrimitive *CDPComponent::m_pSkipToElement

This variable holds if set, the XMLParserCallback shall skip to this element.

PortList CDPComponent::m_ports

This variable holds list of ports, instance- specific.

CDPProperty<std::string> CDPComponent::m_priority

This variable holds a string containing the priority.

CDPSignal<double> CDPComponent::m_processPeriod

This variable holds period between each run of the process.

CDPSignal<double> CDPComponent::m_processTime

This variable holds duration between start and stop of the process.

unsigned int CDPComponent::m_uiCurrentBlockedStates

This variable holds always indicates the states that are currently blocked. (Typically blocked by alarms.).

int CDPComponent::m_usSinceLastProcessRun

This variable holds microseconds since Process() was last called.

unsigned int CDPComponent::outputObjectStatus

This variable holds status of all output objects as calculated in SyncOut().

CDPProperty<std::string> CDPComponent::overrideState

This variable holds if overrideStateMachine is set, this state will be run (no state transitions will be checked).

CDPProperty<bool> CDPComponent::overrideStateMachine

This variable holds set to true to disable state transitions. Only the state specified by overrideState will be run.

ParameterList CDPComponent::parameters

This variable holds list of persistent parameters, instance- specific.

CDPConnector CDPComponent::parent

This variable holds connection to parent (owner) component.

std::string CDPComponent::requestedState

This variable holds requested state. Will enter this state at next process run if allowed.

ComponentMap CDPComponent::s_mapComponents

This variable holds a map relating the object name to the object handle. Use ComponentPointer(string) to look up in this map.

CDPState *CDPComponent::state

This variable holds pointer to current state struct.

unsigned int CDPComponent::status

This variable holds component status created from all member alarm statuses.

CDPProperty<std::string> CDPComponent::strState

This variable holds state string (Read-only). Reflects the current state.

SubcomponentConnectionList CDPComponent::subcomponentConnections

This variable holds list of connections to subcomponents, instance-specific.

double CDPComponent::ts

This variable holds the ideal process period in seconds.

double CDPComponent::tsInus

This variable holds the ideal process period in usecs.

© CDP Technologies AS - All rights reserved