cisstMultiTask API

cisstMultiTask provides the component-based framework for cisst: components, tasks, interfaces, commands, functions, events, and state tables.

Key classes

class mtsComponent : public cmnGenericObject 

mtsComponent should be used to write wrappers around existing devices or resources. This class allows to interact with existing devices as one would interact with a task (as in mtsTask and mtsTaskPeriodic). To do so, the component maintains a list of provided interfaces (of type mtsInterfaceProvided) which contains commands.

The main differences are that the base component class doesn’t have a thread and is stateless. Since the component doesn’t have any thread, the commands are not queued and the class doesn’t add any thread safety mechanism. The component class doesn’t maintain a state as it relies on the underlying device to do so. It is basically a pass-thru or wrapper.

Subclassed by mtsCollectorFactoryQtWidget, mtsComponentWithManagement, mtsIntervalStatisticsQtWidgetComponent, mtsMessageQtWidgetComponent, mtsQtWidgetComponent, mtsSystemQtWidgetComponent, mtsTask, prmEventButtonQtWidgetComponent, prmForceCartesianGetQtWidgetComponent, prmInputDataQtWidgetComponent, prmPositionCartesianArrayGetQtWidget, prmPositionCartesianGetQtWidgetFactory, prmStateRobotQtWidgetComponent, svlFilterBase, svlQtWidgetVidCapSrcImageProperties, svlQtWidgetVideoEncoder, svlStreamManager, svlVideoCodecBase

Public Types

typedef mtsComponent ThisType

Public Functions

mtsComponent(const std::string &deviceName): Default constructor. Sets the name.

virtual ~mtsComponent(): Default destructor. Does nothing.

const std::string &GetName(void) const: Returns the name of the component.

void GetName(std::string &placeHolder) const

void AddTag(const std::string &tag): Add a tag to the component.

const std::set<std::string> &GetTags(void) const: Return all tags.

void SetName(const std::string &componentName): Set name. This method is useful to perform dynamic creation using the default constructor and then set the name.

virtual void Configure(const std::string &filename = ""): The virtual method so that the interface or tasks can configure themselves

virtual void Create(void): Virtual method to create the components, e.g. for tasks create the required threads. For other components, place initialization code.

bool CreateAndWait(double timeoutInSeconds): Call the Create method followed by WaitForState

virtual void Start(void): Virtual method called after components are connected to start the computations and message processing.

bool StartAndWait(double timeoutInSeconds): Call the Start method followed by WaitForState

virtual void Suspend(void): Virtual method to suspend the component (same as Stop).

virtual void Kill(void): Virtual method to stop the computations and message processing. See Start.

bool KillAndWait(double timeoutInSeconds): Call the Kill method followed by WaitForState

inline virtual void Startup(void): Virtual method that gets overloaded, and is run before the component is started.

inline virtual void Cleanup(void): Virtual method that gets overloaded, and is run after the component gets killed using Kill() method.

mtsInterfaceProvided *AddInterfaceProvided(const std::string &interfaceProvidedName, mtsInterfaceQueueingPolicy queueingPolicy = MTS_COMPONENT_POLICY): Method to add a provided interface to the component.

virtual mtsInterfaceProvided *AddInterfaceProvidedWithoutSystemEvents(const std::string &interfaceProvidedName, mtsInterfaceQueueingPolicy queueingPolicy = MTS_COMPONENT_POLICY)

Method to add a bare provided interface, i.e. without all the system events. This method should not be used by regular users as it might break things like blocking commands.

This method is virtual so that mtsTask can redefine it and create a provided interface that includes queues for thread safety.

inline CISST_DEPRECATED mtsInterfaceProvided * AddProvidedInterface (const std::string &interfaceProvidedName)

virtual mtsInterfaceOutput *AddInterfaceOutput(const std::string &interfaceOutputName): Method to add an output interface to the component.

std::vector<std::string> GetNamesOfInterfacesProvidedOrOutput(void) const: Return the list of provided interfaces. This returns a list of names. To retrieve the actual interface, use GetInterfaceProvided with the provided interface name.

std::vector<std::string> GetNamesOfInterfacesProvided(void) const

std::vector<std::string> GetNamesOfInterfacesOutput(void) const

bool InterfaceExists(const std::string &interfaceName, cmnLogLevel lod = CMN_LOG_LEVEL_INIT_VERBOSE) const: Check if there is any interface with the given name

bool InterfaceProvidedOrOutputExists(const std::string &interfaceName, cmnLogLevel lod = CMN_LOG_LEVEL_INIT_VERBOSE) const: Check if there is any interface provided or output with the given name

bool InterfaceRequiredOrInputExists(const std::string &interfaceName, cmnLogLevel lod = CMN_LOG_LEVEL_INIT_VERBOSE) const: Check if there is any interface required or input with the given name

mtsInterfaceProvided *GetInterfaceProvided(const std::string &interfaceProvidedName) const: Get a provided interface identified by its name

mtsInterfaceOutput *GetInterfaceOutput(const std::string &interfaceOutputName) const: Get an output interface identified by its name

size_t GetNumberOfInterfacesProvided(void) const: Get the total number of provided interfaces

size_t GetNumberOfInterfacesOutput(void) const: Get the total number of output interfaces

bool RemoveInterfaceProvided(const std::string &interfaceProvidedName): Remove a provided interface identified by its name

mtsInterfaceRequired *AddInterfaceRequired(const std::string &interfaceRequiredName, mtsRequiredType isRequired = MTS_REQUIRED)

Remove an output interface identified by its name

Add a required interface. This interface will later on be connected to another task and use the provided interface of the other task. The required interface created also contains a list of event handlers to be used as observers.

virtual mtsInterfaceRequired *AddInterfaceRequiredWithoutSystemEventHandlers(const std::string &interfaceRequiredName, mtsRequiredType isRequired = MTS_REQUIRED)

inline CISST_DEPRECATED mtsInterfaceRequired * AddRequiredInterface (const std::string &requiredInterfaceName)

virtual mtsInterfaceInput *AddInterfaceInput(const std::string &interfaceInputName): Add an input interface.

std::vector<std::string> GetNamesOfInterfacesRequiredOrInput(void) const: Provide a list of existing required interfaces (by names)

std::vector<std::string> GetNamesOfInterfacesRequired(void) const

std::vector<std::string> GetNamesOfInterfacesInput(void) const

const mtsInterfaceProvided *GetInterfaceProvidedFor(const std::string &interfaceRequiredName): Get a pointer on the provided interface that has been connected to a given required interface (defined by its name). This method will return a null pointer if the required interface has not been connected. See mtsTaskManager::Connect.

mtsInterfaceRequired *GetInterfaceRequired(const std::string &interfaceRequiredName): Get a required interface identified by its name

mtsInterfaceInput *GetInterfaceInput(const std::string &interfaceInputName) const: Get an input interface identified by its name

size_t GetNumberOfInterfacesRequired(void) const: Get the total number of required interfaces

size_t GetNumberOfInterfacesInput(void) const: Get the total number of input interfaces

bool RemoveInterfaceRequired(const std::string &interfaceRequiredName): Remove a required interface identified by its name

inline const mtsManagerComponentServices *GetManagerComponentServices(void) const

Remove an input interface identified by its name

Get pointer to manager component services, which extends the internal required interface to the Manager Component Client (MCS). This is used by the IRE (Python wrapping)

inline mtsManagerComponentServices *GetManagerComponentServices(void)

mtsStateTable *GetStateTable(const std::string &stateTableName): Return a pointer to state table with the given name.

bool AddStateTable(mtsStateTable *existingStateTable, bool addInterfaceProvided = true)

Add an existing state table to the list of known state tables in this task. This method will add a provided interface for the state table using the name “StateTable” + existingStateTable->GetName() unless the caller specifies that no interface should be created.

By default, all state tables added will advance at each call of the Run method. To avoid the automatic advance, use the method mtsStateTable::SetAutomaticAdvance(false).

void UseSeparateLogFileDefault(bool forwardToLogger = true): Tells this component to use its own file for log. By default the messages are also sent to cmnLogger but this can be changed setting forwardToLogger to false. The default file name is based on the component’s name, followed by ‘-log.txt’

void UseSeparateLogFileDefaultWithDate(bool forwardToLogger = true): Tells this component to use its own file for log. By default the messages are also sent to cmnLogger but this can be changed setting forwardToLogger to false. The default file name is based on the component’s name, followed by the date and ‘-log.txt’

void UseSeparateLogFile(const std::string &filename, bool forwardToLogger = true): Tells this component to use its own file for log. By default the messages are also sent to cmnLogger but this can be changed setting forwardToLogger to false.

virtual cmnLogger::StreamBufType *GetLogMultiplexer(void) const override: Overload GetLodMultiplexer. This method is used for all class level log (i.e. CMN_LOG_CLASS) and allows to redirect the log to a separate file for each component when activated by UseSeparateLogFile or UseSeparateLogFileDefault.

bool AreAllInterfacesRequiredConnected(const bool log = false): Return true if all required interfaces are connected. This method will not log the results in cisstLog unless the flag ‘log’ is set to true.

bool IsRunning(void) const: Return true if task is active.

inline bool CISST_DEPRECATED Running (void) const

bool IsStarted(void) const: Return true if task was started.

bool IsTerminated(void) const: Return true if task is terminated.

bool IsEndTask(void) const: Return true if task is marked for killing.

const mtsComponentState &GetState(void) const: Return task state.

void GetState(mtsComponentState &state) const

virtual bool WaitForState(mtsComponentState desiredState, double timeout): Helper function to wait on a state change, with specified timeout in seconds.

virtual void ToStream(std::ostream &outputStream) const override: Send a human readable description of the component.

bool SetReplayMode(void): Method to set replay mode

bool SetReplayData(const std::string &stateTableName, const std::string &fileName)

bool SetReplayTime(const double time)

class mtsTask : public mtsComponent 

This class provides the base for implementing tasks that have a thread, a state table to store the state at each ‘tick’ (increment) of the task, and queues to receive messages (commands) from other tasks. It is derived from mtsComponent, so it also contains the provided and required interfaces, with their lists of commands.

Subclassed by mtsTaskContinuous, mtsTaskFromCallback

Public Types

typedef mtsComponent BaseType

Public Functions

mtsTask(const std::string &name, unsigned int sizeStateTable = 256)

Create a task with name ‘name’ and set the state table size (see mtsStateTable). This is the task base class. Tasks should be derived from one of the existing derived classes: mtsTaskContinuous, mtsTaskPeriodic, mtsTaskFromCallback, and mtsTaskFromSignal.

Note

See note in mtsTask regarding length of string name.

Parameters:

name – The name of the task
sizeStateTable – The history size of the state table

mtsTaskFromSignal(const mtsTaskConstructorArg &arg)

inline virtual ~mtsTaskFromSignal(): Default Destructor.

void Kill(void) override

mtsInterfaceRequired *AddInterfaceRequiredWithoutSystemEventHandlers(const std::string &interfaceRequiredName, mtsRequiredType required = MTS_REQUIRED) override

mtsInterfaceProvided *AddInterfaceProvidedWithoutSystemEvents(const std::string &newInterfaceName, mtsInterfaceQueueingPolicy queueingPolicy = MTS_COMPONENT_POLICY) override

class mtsInterfaceProvided : public mtsInterface

This class implements the provided interface for a component, mtsComponent. It provides services via command objects, which have four signatures:

Void: no parameters Read: one non-const parameter Write: one const parameter QualifiedRead: one non-const (read) and one const (write) parameter

The interface can also generate two types of events:

Void: no parameters Write: one const parameter

Clients (components) connect to this interface and obtain pointers to command objects. They can then execute these command objects to obtain the desired service. Clients can also provide event handlers to the interface — these are actually command objects that the device will execute when the particular event occurs (Observer Pattern).

This class includes both public and protected members functions. The public members are for access by connected clients. The protected members are for access by the owning device, in order to populate the lists of commands and events.

Note that this class is instantiated by both mtsComponent and its derived mtsTask classes, via the virtual method AddInterfaceProvided. Because mtsTask (and its derived classes) have a thread, they (by default) instantiate mtsInterfaceProvided with a queueing policy of MTS_COMMANDS_SHOULD_BE_QUEUED. In this case, the provided interface uses queues for Void and Write commands in order to maintain thread safety. Furthermore, a separate queue is allocated for each client that connects to this interface — this ensures that each queue has only a single writer (the client) and a single reader (this task), so thread-safety can be achieved without relying on potentially blocking mutexes. This is implemented by the GetEndUserInterface method, which returns a new mtsInterfaceProvided object to the client component. In other words, the original provided interface acts as a provided interface factory that generates a “copy” of the provided interface for every client. Note that GetEndUserInterface is protected, and should only be called by mtsComponent.

Public Types

enum [anonymous]

Default size for mail boxes and argument queues

Values:

enumerator DEFAULT_MAIL_BOX_AND_ARGUMENT_QUEUES_SIZE

typedef mtsInterfaceProvided ThisType: This type

typedef mtsInterface BaseType: Base class

typedef cmnNamedMap<mtsCommandVoid> CommandVoidMapType: Typedef for a map of name and void commands.

typedef cmnNamedMap<mtsCommandVoidReturn> CommandVoidReturnMapType: Typedef for a map of name and void return commands.

typedef cmnNamedMap<mtsCommandWriteBase> CommandWriteMapType: Typedef for a map of name and write commands.

typedef cmnNamedMap<mtsCommandWriteReturn> CommandWriteReturnMapType: Typedef for a map of name and write return commands.

typedef cmnNamedMap<mtsCommandRead> CommandReadMapType: Typedef for a map of name and read commands.

typedef cmnNamedMap<mtsCommandQualifiedRead> CommandQualifiedReadMapType: Typedef for a map of name and qualified read commands.

typedef cmnNamedMap<mtsMulticastCommandVoid> EventVoidMapType: Typedef for a map of event name and void event generators.

typedef cmnNamedMap<mtsMulticastCommandWriteBase> EventWriteMapType: Typedef for a map of event name and write event generators.

typedef cmnNamedMap<mtsCommandBase> CommandInternalMapType: Typedef for a map of internally-generated commands (only used for garbage collection).

Public Functions

mtsInterfaceProvided(const std::string &name, mtsComponent *component, mtsInterfaceQueueingPolicy queueingPolicy, mtsCallableVoidBase *postCommandQueuedCallable = 0): Constructor with a post queued command. This constructor is used by mtsTaskFromSignal to provide the command used everytime one uses a queued command of this interface (write and void commands). The post command queued command in this case performs a wakeup (signal) on the task’s thread.

virtual ~mtsInterfaceProvided(): Default Destructor.

void Cleanup(void): The member function that is executed once the task terminates. This does some cleanup work

void SetMailBoxSize(size_t desiredSize)

Set the desired size for the command mail box. If queueing has been enabled for this interface, a single mailbox is created for each connected required interface. All commands provided by this interface share a single mailbox but each write command (write and write with return) manages it’s own queue for the command argument. To change the argument queue size, use SetArgumentQueuesSize. To change both parameters at once, use SetMailBoxAndArgumentQueuesSize.

The size of the mail box can’t be changed while being used (i.e. while any required interface is connected to the provided interface.

inline size_t GetMailBoxSize(void) const: Get the current mailbox size.

void SetArgumentQueuesSize(size_t desiredSize)

Set the desired size for all argument queues. If queueing has been enabled for this interface, each write command (write or write with return) manages it’s own queue of arguments. The command itself is queued in the interface mailbox (see SetMailBoxSize) and the argument is queued by the command itself. There is no reason to have an argument queue larger than the command mail box as there can’t be more arguments queued than commands. The reciprocal is not true as different commands can be queued. So, the argument queue size should be lesser or equal to the mail box size.

The size of argument queues can’t be changed while being used (i.e. while any required interface is connected to the provided interface.

inline size_t GetArgumentQueuesSize(void) const: Get the current argument queues size.

void SetMailBoxAndArgumentQueuesSize(size_t desiredSize): Set the desired size for the command mail box and argument queues. See SetMailBoxSize and SetArgumentQueuesSize.

mtsInterfaceProvidedDescription GetDescription() const: Get the description of this interface.

std::vector<std::string> GetNamesOfCommands(void) const: Get the names of commands provided by this interface.

std::vector<std::string> GetNamesOfCommandsVoid(void) const

std::vector<std::string> GetNamesOfCommandsVoidReturn(void) const

std::vector<std::string> GetNamesOfCommandsWrite(void) const

std::vector<std::string> GetNamesOfCommandsWriteReturn(void) const

std::vector<std::string> GetNamesOfCommandsRead(void) const

std::vector<std::string> GetNamesOfCommandsQualifiedRead(void) const

std::vector<std::string> GetNamesOfEventsVoid(void) const: Get the names of events coming from this interface

std::vector<std::string> GetNamesOfEventsWrite(void) const

mtsCommandVoid *GetCommandVoid(const std::string &commandName, const mtsRequiredType required = MTS_REQUIRED) const: Find a command based on its name.

mtsCommandVoidReturn *GetCommandVoidReturn(const std::string &commandName, const mtsRequiredType required = MTS_REQUIRED) const

mtsCommandWriteBase *GetCommandWrite(const std::string &commandName, const mtsRequiredType required = MTS_REQUIRED) const

mtsCommandWriteReturn *GetCommandWriteReturn(const std::string &commandName, const mtsRequiredType required = MTS_REQUIRED) const

mtsCommandRead *GetCommandRead(const std::string &commandName, const mtsRequiredType required = MTS_REQUIRED) const

mtsCommandQualifiedRead *GetCommandQualifiedRead(const std::string &commandName, const mtsRequiredType required = MTS_REQUIRED) const

const cmnClassServicesBase *GetCommandWriteArgumentServices(const std::string &commandName) const: Get argument class services for a command

const cmnClassServicesBase *GetCommandReadArgumentServices(const std::string &commandName) const

mtsMulticastCommandVoid *GetEventVoid(const std::string &eventName) const: Find an event based on its name.

mtsMulticastCommandWriteBase *GetEventWrite(const std::string &eventName) const

template<class __classType> inline mtsCommandVoid *AddCommandVoid(void (__classType::* method)(void), __classType *classInstantiation, const std::string &commandName, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY)

Add a void command to the provided interface based on a method and an object instantiating the method. This method creates an mtsCommandVoid object and then calls the AddCommandVoid virtual method; this method is overridden in mtsInterfaceProvided to queue the void command (thereby ensuring thread safety).

Parameters:

method – method pointer
classInstantiation – an instantiation of the method’s class
commandName – name as it should appear in the interface

Returns:

pointer on the newly created and added command, null pointer (0) if creation or addition failed (name already used)

inline mtsCommandVoid *AddCommandVoid(void (*function)(void), const std::string &commandName, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY)

Add a void command to the provided interface based on a void function. This method creates an mtsCommandVoid object and then calls the AddCommandVoid virtual method; this method is overridden in mtsInterfaceProvided to queue the void command (thereby ensuring thread safety).

Parameters:

function – void function pointer
commandName – name as it should appear in the interface

Returns:

pointer on the newly created and added command, null pointer (0) if creation or addition failed (name already used)

template<class __classType, class __resultType> inline mtsCommandVoidReturn *AddCommandVoidReturn(void (__classType::* method)(__resultType&), __classType *classInstantiation, const std::string &commandName, const __resultType &resultPrototype, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY): Add a void command with result.

template<class __classType, class __resultType> inline mtsCommandVoidReturn *AddCommandVoidReturn(void (__classType::* method)(__resultType&), __classType *classInstantiation, const std::string &commandName, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY)

template<class __classType, class __argumentType> inline mtsCommandWriteBase *AddCommandWrite(void (__classType::* method)(const __argumentType&), __classType *classInstantiation, const std::string &commandName, const __argumentType &argumentPrototype, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY)

Add a write command to the provided interface based on a method and an object instantiating the method. This method creates an mtsCommandWrite object and then calls the AddCommandWrite virtual method; this method is overridden in mtsInterfaceProvided to queue the write command (thereby ensuring thread safety).

Parameters:

method – method pointer
classInstantiation – an instantiation of the method’s class
commandName – name as it should appear in the interface
argumentPrototype – example of argument that should be used to call this method. This is especially useful for commands using objects of variable size (dynamic allocation)

Returns:

pointer on the newly created and added command, null pointer (0) if creation or addition failed (name already used)

template<class __classType, class __argumentType> inline mtsCommandWriteBase *AddCommandWrite(void (__classType::* method)(const __argumentType&), __classType *classInstantiation, const std::string &commandName, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY)

template<class __classType, class __argumentType, class __resultType> inline mtsCommandWriteReturn *AddCommandWriteReturn(void (__classType::* method)(const __argumentType&, __resultType&), __classType *classInstantiation, const std::string &commandName, const __argumentType &argumentPrototype, const __resultType &resultPrototype, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY): Add a write command with result.

template<class __classType, class __argumentType, class __resultType> inline mtsCommandWriteReturn *AddCommandWriteReturn(void (__classType::* method)(const __argumentType&, __resultType&), __classType *classInstantiation, const std::string &commandName, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY)

template<class __classType, class __argumentType> inline mtsCommandRead *AddCommandRead(void (__classType::* method)(__argumentType&) const, __classType *classInstantiation, const std::string &commandName, const __argumentType &argumentPrototype)

Add a read command to the provided interface based on a method and an object instantiating the method. This method creates an mtsCommandRead object and then calls the AddCommandRead virtual method.

Parameters:

method – method pointer
classInstantiation – an instantiation of the method’s class
commandName – name as it should appear in the interface
argumentPrototype – example of argument that should be used to call this method. This is especially useful for commands using objects of variable size (dynamic allocation)

Returns:

pointer on the newly created and added command, null pointer (0) if creation or addition failed (name already used)

template<class __classType, class __argumentType> inline mtsCommandRead *AddCommandRead(void (__classType::* method)(__argumentType&) const, __classType *classInstantiation, const std::string &commandName)

template<class _elementType> mtsCommandRead *AddCommandReadState(const mtsStateTable &stateTable, const _elementType &stateData, const std::string &commandName): Adds command objects to read from the state table (by default, all tasks have state tables, but it is possible to have a state table in a device). Note that there are two command objects: a ‘read’ command to get the latest value, and a ‘qualified read’ command to get the value at the specified time.

template<class _elementType, class _outputType> mtsCommandRead *AddCommandFilteredReadState(const mtsStateTable &stateTable, const _elementType &stateData, bool (_elementType::* getMethod)(_outputType&) const, const std::string &commandName)

template<class _elementType, class _outputType> mtsCommandRead *AddCommandFilteredReadState(const mtsStateTable &stateTable, const _elementType &stateData, _outputType (_elementType::* getMethod)(void) const, const std::string &commandName)

template<class _elementType, class _outputType> mtsCommandRead *AddCommandFilteredReadState(const mtsStateTable &stateTable, const _elementType &stateData, bool (*convertFunction)(const _elementType &input, _outputType &output), const std::string &commandName)

template<class _elementType> mtsCommandRead *AddCommandReadStateDelayed(const mtsStateTable &stateTable, const _elementType &stateData, const std::string &commandName): Adds command objects to read from the state table with a delay. The commands created (‘read’ and ‘qualified read’) are similar to the commands added using AddCommandReadState except that instead of reading from the head, these commands read from head - delay.

template<class _elementType> mtsCommandWriteBase *AddCommandWriteState(const mtsStateTable &stateTable, const _elementType &stateData, const std::string &commandName, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY): Adds command object to write to state table.

template<class __classType, class __argument1Type, class __argument2Type> inline mtsCommandQualifiedRead *AddCommandQualifiedRead(void (__classType::* method)(const __argument1Type&, __argument2Type&) const, __classType *classInstantiation, const std::string &commandName, const __argument1Type &argument1Prototype, const __argument2Type &argument2Prototype)

template<class __classType, class __argument1Type, class __argument2Type> inline mtsCommandQualifiedRead *AddCommandQualifiedRead(void (__classType::* method)(const __argument1Type&, __argument2Type&) const, __classType *classInstantiation, const std::string &commandName)

template<class __classType, class __argumentType, class __filteredType> inline mtsCommandWriteBase *AddCommandFilteredWrite(void (__classType::* premethod)(const __argumentType&, __filteredType&) const, void (__classType::* method)(const __filteredType&), __classType *classInstantiation, const std::string &commandName, const __argumentType &argumentPrototype, const __filteredType &filteredPrototype, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY)

template<class __classType, class __argumentType, class __filteredType> inline mtsCommandWriteBase *AddCommandFilteredWrite(void (__classType::* premethod)(const __argumentType&, __filteredType&) const, void (__classType::* method)(const __filteredType&), __classType *classInstantiation, const std::string &commandName, mtsCommandQueueingPolicy queueingPolicy = MTS_INTERFACE_COMMAND_POLICY)

mtsCommandVoid *AddEventVoid(const std::string &eventName): Add events to the interface. This method creates the multicast command used to trigger all the observers for the event. These methods are used to populate the provided interface.

bool AddEventVoid(mtsFunctionVoid &eventTrigger, const std::string &eventName)

template<class __argumentType> mtsCommandWriteBase *AddEventWrite(const std::string &eventName, const __argumentType &argumentPrototype)

template<class __argumentType> bool AddEventWrite(mtsFunctionWrite &eventTrigger, const std::string &eventName, const __argumentType &argumentPrototype)

mtsCommandWriteBase *AddEventWriteGeneric(const std::string &eventName, const mtsGenericObject &argumentPrototype)

bool AddEventWriteGeneric(mtsFunctionWrite &eventTrigger, const std::string &eventName, const mtsGenericObject &argumentPrototype)

bool AddObserver(const std::string &eventName, mtsCommandVoid *handler, const mtsRequiredType required = MTS_REQUIRED)

Add an observer for the specified event. These methods are used to connect to an existing provided interface, ideally from a required interface.

Parameters:

name – Name of event
handler – command object that implements event handler

Returns:

true if successful; false otherwise

bool AddObserver(const std::string &eventName, mtsCommandWriteBase *handler, const mtsRequiredType required = MTS_REQUIRED)

void AddObserverList(const mtsEventHandlerList &argin, mtsEventHandlerList &argout)

bool RemoveObserver(const std::string &eventName, mtsCommandVoid *handler)

Remove an observer for the specified event. These methods are used when disconnecting from the provided interface.

Parameters:

name – Name of event
handler – command object that implements event handler

Returns:

true if successful; false otherwise

bool RemoveObserver(const std::string &eventName, mtsCommandWriteBase *handler)

void RemoveObserverList(const mtsEventHandlerList &argin, mtsEventHandlerList &argout)

void AddMessageEvents(void): Human readable messages. This method adds 3 events to the provided interface: Status, Warning and Error. Each of them uses the payload mtsMessage which contains a string, a timestamp and a counter. The event triggers are protected, users can only call the methods SendStatus, SendWarning and SendError with a user message. These methods will maintain the event counter, timestamp the messages, log using cmnLogger and finally emit the message event.

void SendStatus(const std::string &message)

void SendWarning(const std::string &message)

void SendError(const std::string &message)

mtsInterfaceProvided *GetOriginalInterface(void) const: Get the original interface. This allows to retrieve the original interface from a copy created using GetEndUserInterface.

mtsInterfaceProvided *FindEndUserInterfaceByName(const std::string &userName): Find an end-user interface given a client name.

std::vector<std::string> GetListOfUserNames(void) const: Returns a list of user names (name of connected required interface). Used to remove provided interface in a thread-safe way

int GetNumberOfEndUsers() const: Return number of active end-user interfaces.

size_t ProcessMailBoxes(void): Method used to process all commands queued in mailboxes. This method should only be used by the component that owns the interface for thread safety.

virtual void ToStream(std::ostream &outputStream) const override: Send a human readable description of the interface.

mtsInterfaceProvided *GetEndUserInterface(const std::string &userName)

This method creates a copy of the existing interface. The copy is required for each new user, i.e. for each required interface connected to this provided interface if queueing has been enabled. This method should not be called on a provided interface if queueing is not enable. The newly created provided interface is created using the current MailBoxSize (see SetMailBoxSize) and ArgumentQueuesSize (see SetArgumentQueuesSize). Commands and events should only be added to the original interface.

Parameters:: userName – name of the required interface being connected to this provided interface. This information is used for logging only.
Returns:: pointer to end-user interface (0 if error)

template<class _elementType, class _outputType, class _filterMethod> mtsCommandRead *AddCommandFilteredReadStateInternal(const mtsStateTable &stateTable, const _elementType &stateData, _filterMethod filterMethod, const std::string &commandName)

Public Members

mtsFunctionWrite StatusEvent

mtsMessage StatusMessage

mtsFunctionWrite WarningEvent

mtsMessage WarningMessage

mtsFunctionWrite ErrorEvent

mtsMessage ErrorMessage

Public Static Functions

static bool IsSystemEventVoid(const std::string &name): Returns true if the event is a system event (e.g., BlockingCommandExecuted or BlockingCommandReturnExecuted)

class mtsInterfaceRequired : public mtsInterface

This class implements the required interface for a component (mtsComponent, mtsTask, …). The required interface gets populated with pointers to command objects, which have four signatures:

Void: no parameters Read: one non-const parameter Write: one const parameter QualifiedRead: one non-const (read) and one const (write) parameter

The required interface may also have command object pointers for the following types of event handlers:

Void: no parameters Write: one const parameter

When the required interface of this component is connected to the provided interface of another component, the command object pointers are “bound” to command objects provided by the other component. Similarly, the event handlers are added as observers of events that are generated by the provided interface of the other component.

This implementation is simpler than the provided interface because we assume that a required interface is never connected to more than one provided interface, whereas a provided interface can be used by multiple required interfaces. While one can conceive of cases where it may be useful to have a required interface connect to multiple provided interfaces (e.g., running a robot simulation in parallel with a real robot), at this time it is not worth the trouble.

Public Types

enum [anonymous]

Default size for mail boxes and argument queues used by event handlers.

Values:

enumerator DEFAULT_MAIL_BOX_AND_ARGUMENT_QUEUES_SIZE

typedef FunctionOrReceiverInfo<mtsFunctionBase> FunctionInfo

typedef FunctionOrReceiverInfo<mtsEventReceiverVoid> ReceiverVoidInfo

typedef FunctionOrReceiverInfo<mtsEventReceiverWrite> ReceiverWriteInfo

Public Functions

mtsInterfaceRequired(const std::string &interfaceName, mtsComponent *component, mtsMailBox *mailBox, mtsRequiredType required = MTS_REQUIRED)

Constructor. Sets the name, device pointer, and mailbox for queued events.

Parameters:

interfaceName – Name of required interface
mbox – Mailbox to use for queued events (for tasks); set to 0 for devices (i.e. mtsComponent) while tasks (derived from mtsTask) create a mailbox and then provide the mailbox to the required interface.
isRequired – Used to indicate if the component should function even if this interface is not connected to a provided interface.

virtual ~mtsInterfaceRequired(): Default destructor.

const mtsInterfaceProvided *GetConnectedInterface(void) const

bool SetMailBoxSize(size_t desiredSize)

Set the desired size for the event handlers mail box. If queueing has been enabled for this interface, a single mailbox is created to handle all events. Each write event handler manages it’s own queue for the event argument. To change the argument queue size, use SetArgumentQueuesSize. To change both parameters at once, use SetMailBoxAndArgumentQueuesSize.

The size of the mail box can’t be changed while being used (i.e. while this required interface is connected to a provided interface.

bool SetArgumentQueuesSize(size_t desiredSize)

Set the desired size for all argument queues. If queueing has been enabled for this interface, each write event handler manages it’s own queue of arguments. The command itself is queued in the interface mailbox (see SetMailBoxSize) and the argument is queued by the command itself. There is no reason to have an argument queue larger than the event handlers mail box as there can’t be more arguments queued than events. The reciprocal is not true as different events can be queued. So, the argument queue size should be lesser or equal to the mail box size.

The size of the mail box can’t be changed while being used (i.e. while this required interface is connected to a provided interface.

bool SetMailBoxAndArgumentQueuesSize(size_t desiredSize): Set the desired size for the event handlers mail box and argument queues. See SetMailBoxSize and SetArgumentQueuesSize.

mtsInterfaceRequiredDescription GetDescription() const: Get the description of this interface.

virtual std::vector<std::string> GetNamesOfFunctions(void) const: Get the names of commands required by this interface.

virtual std::vector<std::string> GetNamesOfFunctionsVoid(void) const

virtual std::vector<std::string> GetNamesOfFunctionsVoidReturn(void) const

virtual std::vector<std::string> GetNamesOfFunctionsWrite(void) const

virtual std::vector<std::string> GetNamesOfFunctionsWriteReturn(void) const

virtual std::vector<std::string> GetNamesOfFunctionsRead(void) const

virtual std::vector<std::string> GetNamesOfFunctionsQualifiedRead(void) const

mtsFunctionVoid *GetFunctionVoid(const std::string &functionName) const: Find a function based on its name.

mtsFunctionVoidReturn *GetFunctionVoidReturn(const std::string &functionName) const

mtsFunctionWrite *GetFunctionWrite(const std::string &functionName) const

mtsFunctionWriteReturn *GetFunctionWriteReturn(const std::string &functionName) const

mtsFunctionRead *GetFunctionRead(const std::string &functionName) const

mtsFunctionQualifiedRead *GetFunctionQualifiedRead(const std::string &functionName) const

virtual std::vector<std::string> GetNamesOfEventHandlersVoid(void) const: Get the names of event handlers that exist in this interface

virtual std::vector<std::string> GetNamesOfEventHandlersWrite(void) const

virtual mtsCommandVoid *GetEventHandlerVoid(const std::string &eventName) const: Find an event handler based on its name.

virtual mtsCommandWriteBase *GetEventHandlerWrite(const std::string &eventName) const

bool ConnectTo(mtsInterfaceProvided *interfaceProvided)

mtsRequiredType IsRequired(void) const: Check if this interface is required or not for the component to function.

bool AddSystemEventHandlers(void)

Todo:: update documentation Bind command and events. This method needs to provide a user Id so that GetCommandVoid and GetCommandWrite (queued commands) know which mailbox to use. The user Id is provided by the provided interface when calling AllocateResources.

void DisableAllEvents(void)

void EnableAllEvents(void)

size_t ProcessMailBoxes(void): Process any queued events.

virtual void ToStream(std::ostream &outputStream) const override: Send a human readable description of the interface.

bool AddFunction(const std::string &functionName, mtsFunctionVoid &function, mtsRequiredType required = MTS_REQUIRED)

bool AddFunction(const std::string &functionName, mtsFunctionVoidReturn &function, mtsRequiredType required = MTS_REQUIRED)

bool AddFunction(const std::string &functionName, mtsFunctionWrite &function, mtsRequiredType required = MTS_REQUIRED)

bool AddFunction(const std::string &functionName, mtsFunctionWriteReturn &function, mtsRequiredType required = MTS_REQUIRED)

bool AddFunction(const std::string &functionName, mtsFunctionRead &function, mtsRequiredType required = MTS_REQUIRED)

bool AddFunction(const std::string &functionName, mtsFunctionQualifiedRead &function, mtsRequiredType required = MTS_REQUIRED)

bool AddEventReceiver(const std::string &eventName, mtsEventReceiverVoid &receiver, mtsRequiredType required = MTS_REQUIRED)

bool AddEventReceiver(const std::string &eventName, mtsEventReceiverWrite &receiver, mtsRequiredType required = MTS_REQUIRED)

mtsCommandVoid *AddEventHandlerVoid(mtsCallableVoidBase *callable, const std::string &eventName, mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY)

template<class __classType> inline mtsCommandVoid *AddEventHandlerVoid(void (__classType::* method)(void), __classType *classInstantiation, const std::string &eventName, mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY)

inline mtsCommandVoid *AddEventHandlerVoid(void (*function)(void), const std::string &eventName, mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY)

template<class __classType, class __argumentType> inline mtsCommandWriteBase *AddEventHandlerWrite(void (__classType::* method)(const __argumentType&), __classType *classInstantiation, const std::string &eventName, mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY)

template<class __classType> inline mtsCommandWriteBase *AddEventHandlerWriteGeneric(void (__classType::* method)(const mtsGenericObject&), __classType *classInstantiation, const std::string &eventName, mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY, mtsGenericObject *argumentPrototype = 0)

bool RemoveEventHandlerVoid(const std::string &eventName)

bool RemoveEventHandlerWrite(const std::string &eventName)

template<class _PointerType> class FunctionOrReceiverInfo

Public Functions

inline FunctionOrReceiverInfo(_PointerType &func_or_recv, mtsRequiredType required)

inline ~FunctionOrReceiverInfo()

inline void Detach(void)

inline void ToStream(std::ostream &outputStream) const

class mtsStateTable : public cmnGenericObject 

The state data table is the storage for the state of the task that the table is associated with. It is a heterogenous circular buffer and can contain data of any type so long as it is derived from mtsGenericObject. The state data table also resolves conflicts between reads and writes to the state, by ensuring that the reader head is always one behind the write head. To ensure this we have an assumption here that there is only one writer, though there can be multiple readers. State Data Table is also refered as Data Table or State Table elsewhere in the documentation.

Public Functions

mtsStateTable(size_t size, const std::string &name): Constructor. Constructs a state table with a default size of 256 rows.

~mtsStateTable(): Default destructor.

bool SetSize(const size_t size): Method to change the size of the table

mtsStateIndex GetIndexReader(void) const: Get a handle for data to be used by a reader. All the const methods, that can be called from a reader and writer.

inline void GetIndexReader(mtsStateIndex &timeIndex) const

mtsStateIndex GetIndexDelayed(void) const: Get a handle for data to be used by a reader with a given delay. All the const methods, that can be called from a reader and writer.

size_t SetDelay(size_t newDelay): Set delay in number of rows.

inline bool ValidateReadIndex(const mtsStateIndex &timeIndex) const: Verifies if the data is valid.

inline const bool &AutomaticAdvance(void) const: Get method for auto advance flag. See AutomaticAdvanceFlag

inline void SetAutomaticAdvance(bool automaticAdvance): Set method for auto advance flag. See AutoAdvanceFlag.

int GetStateVectorID(const std::string &dataName) const: Check if the signal has been registered.

template<class _elementType> mtsStateDataId NewElement(const std::string &name = "", _elementType *element = 0): Add an element to the table. Should be called during startup of a real time loop. All the non-const methods, that can be called from a writer only. Returns index of data within state data table.

template<class _elementType> inline void AddData(_elementType &element, const std::string &name = ""): Add an element to the table (alternative to NewElement).

template<class _elementType> inline _elementType *GetStateDataElement(mtsStateDataId id) const: Return pointer to the state data element specified by the id. This element is the same type as the state data table entry.

inline mtsGenericObject *GetStateVectorElement(size_t id) const

template<class _elementType> mtsStateTable::AccessorBase *GetAccessorByInstance(const _elementType &element) const

Return pointer to accessor functions for the state data element.

Parameters:: element – Pointer to state data element (i.e., working copy)
Returns:: Pointer to accessor class (0 if not found)

mtsStateTable::AccessorBase *GetAccessorByName(const std::string &name) const

Return pointer to accessor functions for the state data element.

Parameters:: name – Name of state data element
Returns:: Pointer to accessor class (0 if not found)

mtsStateTable::AccessorBase *GetAccessorByName(const char *name) const

mtsStateTable::AccessorBase *GetAccessorById(const size_t id) const

Return pointer to accessor functions for the state data element.

Parameters:: id – Id of state data element
Returns:: Pointer to accessor class (0 if not found)

template<class _elementType> inline CISST_DEPRECATED mtsStateTable::AccessorBase * GetAccessor (const _elementType &element) const

inline CISST_DEPRECATED mtsStateTable::AccessorBase * GetAccessor (const std::string &name) const

inline CISST_DEPRECATED mtsStateTable::AccessorBase * GetAccessor (const char *name) const

inline CISST_DEPRECATED mtsStateTable::AccessorBase * GetAccessor (const size_t id) const

mtsStateIndex GetIndexWriter(void) const: Get a handle for data to be used by a writer

void Start(void): Start the current cycle. This just records the starting timestamp (Tic).

void StartIfAutomatic(void): Start if automatic advance is set and does nothing otherwise.

inline bool Started(void) const: Check if state table is “started”, i.e. between Start() and Advance() calls.

void Advance(void): Advance the pointers of the circular buffer. Note that since there is only a single writer, it is not necessary to use mutual exclusion primitives; the critical section can be handled by updating (incrementing) the write index before the read index.

void AdvanceIfAutomatic(void): Advance if automatic advance is set and does nothing otherwise.

bool ReplayAdvance(void): Advance for replay mode, be very careful this should only be used in replay mode as this method only increments the reader index.

void Cleanup(void): Cleanup called when the task is being stopped.

inline double GetTic(void) const

inline double GetToc(void) const

inline size_t GetHistoryLength(void) const

inline size_t GetNumberOfElements(void) const

inline const std::vector<std::string> &GetDataNames(void) const

inline double GetAveragePeriod(void) const: Return the moving average of the measured period (i.e., average of last HistoryLength values).

virtual void ToStream(std::ostream &out) const override: For debugging, dumps the current data table to output stream.

void Debug(std::ostream &out, unsigned int *listColumn, unsigned int number) const: For debugging, dumps some values of the current data table to output stream.

void CSVWrite(std::ostream &out, bool nonZeroOnly = false): This method is to dump the state data table in the csv format, allowing easy import into matlab. Assumes that individual columns are also printed in csv format. By default print all rows, if nonZeroOnly == true then print only those rows which have a nonzero Ticks value i.e, those rows that have been written to at least once.

void CSVWrite(std::ostream &out, unsigned int *listColumn, unsigned int number, bool nonZeroOnly = false)

void CSVWrite(std::ostream &out, mtsGenericObject **listColumn, unsigned int number, bool nonZeroOnly = false)

inline const std::string &GetName(void) const: Return the name of this state table.

void DataCollectionEventTriggeringRatio(const mtsDouble &eventTriggeringRatio): Determine a ratio to generate a data collection event.

void DataCollectionStart(const mtsDouble &delay): Methods used to control the data collection start/stop

void DataCollectionStop(const mtsDouble &delay)

Public Members

mtsDouble Tic

mtsDouble Toc

mtsDouble Period: The measured task period (difference between current Tic and previous Tic).

mtsIntervalStatistics PeriodStats: Periodicist Statistics

template<class _elementType> class Accessor : public mtsStateTable::AccessorBase 

Public Functions

inline Accessor(const mtsStateTable &table, mtsStateDataId id, const mtsStateArray<value_type> *history, value_ref_type *data)

inline void ToStream(std::ostream &outputStream, const mtsStateIndex &when) const

inline bool Get(const mtsStateIndex &when, value_type &data) const

inline const value_type *GetPointer(const mtsStateIndex &when) const

inline bool Get(const mtsStateIndex &when, mtsGenericObject &data) const

inline bool GetLatest(value_type &data) const

inline bool GetLatest(mtsGenericObject &data) const

inline bool GetDelayed(value_type &data) const

inline bool GetDelayed(mtsGenericObject &data) const

inline void SetCurrent(const value_type &data)

class AccessorBase

Subclassed by mtsStateTable::Accessor< _elementType >

Public Functions

inline AccessorBase(const mtsStateTable &table, mtsStateDataId id)

inline virtual ~AccessorBase()

virtual void ToStream(std::ostream &outputStream, const mtsStateIndex &when) const = 0

class DataCollectionInfo

Data structure used for state table data collection. Stores information related to data collection as well as methods for callbacks

Public Functions

inline DataCollectionInfo(void): Default constructors

inline ~DataCollectionInfo()

Public Members

bool Collecting: True if data collection event can be triggered, this state table is currently collecting data (false by default).

double StartTime: Delay in second before data collection should start. This is measured in seconds based on the state table Tic and Toc. 0 means that there is no defined start time.

double StopTime: Delay in second before data collection should stop. This is measured in seconds based on the state table Tic and Toc. 0 means that there is no defined stop time.

mtsStateTable::IndexRange BatchRange: Range for the batch

size_t BatchSize: Maximum number of elements to collect in one batch.

size_t BatchCounter: Number of elements to be collected so far.

size_t CounterForEvent: Number of elements collected since the last event

double TimeIntervalForProgressEvent: Interval between two progress events (in seconds)

double TimeOfLastProgressEvent: Time of last progress event

mtsFunctionWrite BatchReady: Function used to trigger event sent to state collector when the data collection is needed. The payload is the range defined by state indices.

mtsFunctionVoid CollectionStarted: Function used to trigger an event when the collection has started

mtsFunctionWrite CollectionStopped: Function used to trigger an event when the collection has stopped

mtsFunctionWrite Progress: Function used to trigger an event to indicate progress

class IndexRange : public mtsGenericObject

Collection is performed by batches, this requires to save the state indices for begin/end.

Public Functions

virtual void ToStreamRaw(std::ostream &outputStream, const char delimiter = ' ', bool headerOnly = false, const std::string &headerPrefix = "") const override: Raw text output to stream

Public Members

mtsStateIndex First

mtsStateIndex Last

class mtsManagerLocal : public cmnGenericObject 

Public Functions

void Cleanup(void): Cleanup. Left in the public API for backwards compatibility. Client code should not call this method directly, and should instead call DeleteInstance prior to quitting. DeleteInstance calls this method before deleting the singleton.

inline const std::string CISST_DEPRECATED GetName (void) const: Returns name of this local component manager (for mtsProxyBaseCommon.h)

mtsComponent *CreateComponentDynamically(const std::string &className, const std::string &componentName, const std::string &constructorArgSerialized): Create a component. Does not add it to the local component manager. In this method, componentName is only used if constructorArgSerialized is an empty string.

mtsComponent *CreateComponentDynamically(const std::string &className, const mtsGenericObject &constructorArg): Create a component. Does not add it to the local component manager. In this method, the component name is obtained from constructorArg.

bool AddComponent(mtsComponent *component)

Add a component to the component manager.

Parameters:: component – Component instance to be added

bool CISST_DEPRECATED AddTask (mtsTask *component)

bool CISST_DEPRECATED AddDevice (mtsComponent *component)

bool RemoveComponent(mtsComponent *component): Remove component from component manager.

bool RemoveComponent(const std::string &componentName)

size_t RemoveAllUserComponents(void)

Remove all user components from this local component manager.

Returns:: the number of user components removed.

mtsComponent *GetComponent(const std::string &componentName) const: Retrieve a component by name.

mtsTask *GetComponentAsTask(const std::string &componentName) const

mtsComponent CISST_DEPRECATED * GetDevice (const std::string &deviceName)

mtsTask CISST_DEPRECATED * GetTask (const std::string &taskName)

bool FindComponent(const std::string &componentName) const: Check if a component exists by its name.

bool WaitForStateAll(mtsComponentState desiredState, double timeout = 3.0 * cmn_minute) const: Wait until all components reach a certain state. If all components have reach the given state within the time alloted, the method returns true.

void CreateAll(void): Create all components. If a component is of type mtsTask, mtsTask::Create() is called internally.

bool CreateAllAndWait(double timeoutInSeconds): Call CreateAll method followed by WaitForStateAll.

void StartAll(void): Start all components. If a component is of type mtsTask, mtsTask::Start() is called internally.

bool StartAllAndWait(double timeoutInSeconds): Call StartAll method followed by WaitForStateAll.

void KillAll(void): Stop all components. If a component is of type mtsTask, mtsTask::Kill() is called internally.

bool KillAllAndWait(double timeoutInSeconds): Call KillAll method followed by WaitForStateAll.

bool Connect(const std::string &clientComponentName, const std::string &clientInterfaceRequiredName, const std::string &serverComponentName, const std::string &serverInterfaceProvidedName)

Connect two local interfaces.

Note

If connection is established successfully, this information is reported to the global component manager (the local component manager does not keep any connection information).

Parameters:

clientComponentName – Name of client component
clientInterfaceRequiredName – Name of required interface
serverComponentName – Name of server component
serverInterfaceProvidedName – Name of provided interface

Returns:

True if success, false otherwise

bool Connect(const std::string &clientProcessName, const std::string &clientComponentName, const std::string &clientInterfaceRequiredName, const std::string &serverProcessName, const std::string &serverComponentName, const std::string &serverInterfaceProvidedName)

Connect two remote interfaces.

Note

If connection is established successfully, this information is reported to the global component manager. Since connection between two interfaces should be established twice—once in the client process and once in the server process—there are two internal connection management methods: ConnectClientSideInterface() and ConnectServerSideInterface(). ConnectClientSideInterface() is always executed first and calls ConnectServerSideInterface() internally in a blocking way (i.e., it waits for ConnectServerSideInterface() to finish). Connection request can be made by any process — server process, client process, or even third process — and the result should be the same regardless the request process. If this method is called against two local interfaces, the other Connect() method is internally called instead.

Parameters:

clientProcessName – Name of client process
clientComponentName – Name of client component
clientInterfaceRequiredName – Name of required interface
serverProcessName – Name of server process
serverComponentName – Name of server component
serverInterfaceProvidedName – Name of provided interface

Returns:

True if success, false otherwise

bool Disconnect(const ConnectionIDType connectionID): Disconnect two interfaces

bool Disconnect(const std::string &clientComponentName, const std::string &clientInterfaceRequiredName, const std::string &serverComponentName, const std::string &serverInterfaceProvidedName)

bool Disconnect(const std::string &clientProcessName, const std::string &clientComponentName, const std::string &clientInterfaceRequiredName, const std::string &serverProcessName, const std::string &serverComponentName, const std::string &serverInterfaceProvidedName)

inline const std::string GetProcessName(void) const: Returns name of this local component manager

void GetNamesOfProcesses(std::vector<std::string> &namesOfProcesses) const: Get names of all processes

std::vector<std::string> GetNamesOfComponents(void) const: Enumerate all the names of components added

void GetNamesOfComponents(std::vector<std::string> &namesOfComponents) const

void GetNamesOfComponents(const std::string &processName, std::vector<std::string> &namesOfComponents) const

std::vector<mtsDescriptionComponent> GetDescriptionsOfComponents(const std::string &processName = "") const

bool GetNamesOfInterfaces(const std::string &processName, const std::string &componentName, std::vector<std::string> &namesOfInterfacesRequired, std::vector<std::string> &namesOfInterfacesProvided) const

inline bool GetNamesOfInterfaces(const std::string &componentName, std::vector<std::string> &namesOfInterfacesRequired, std::vector<std::string> &namesOfInterfacesProvided) const

bool GetDescriptionsOfInterfaces(const std::string &processName, const std::string &componentName, std::vector<mtsDescriptionInterfaceFullName> &descriptionsRequired, std::vector<mtsDescriptionInterfaceFullName> &descriptionsProvided) const

inline bool GetDescriptionsOfInterfaces(const std::string &componentName, std::vector<mtsDescriptionInterfaceFullName> &descriptionsRequired, std::vector<mtsDescriptionInterfaceFullName> &descriptionsProvided) const

std::vector<mtsDescriptionConnection> GetListOfConnections(void) const

std::vector<mtsDescriptionComponentClass> GetListOfComponentClasses(const std::string &processName = "") const

mtsInterfaceProvidedDescription GetInterfaceProvidedDescription(const std::string &processName, const std::string &componentName, const std::string &interfaceName) const

inline mtsInterfaceProvidedDescription GetInterfaceProvidedDescription(const std::string &componentName, const std::string &interfaceName) const

mtsInterfaceRequiredDescription GetInterfaceRequiredDescription(const std::string &processName, const std::string &componentName, const std::string &interfaceName) const

inline mtsInterfaceRequiredDescription GetInterfaceRequiredDescription(const std::string &componentName, const std::string &interfaceName) const

const osaTimeServer &GetTimeServer(void) const: Return a reference to the time server.

inline void SetMainThreadId(void): Set main thread id based on the current thread. In most situations, it is not necessary to call this function because the main thread id is initialized in GetInstance.

inline void SetMainThreadId(const osaThreadId &threadId): Set main thread id based on the passed parameter. In most situations, it is not necessary to call this function because the main thread id is initialized in GetInstance.

inline osaThreadId GetMainThreadId(void) const: Return main thread id.

void GetNamesOfCommands(std::vector<std::string> &namesOfCommands, const std::string &componentName, const std::string &providedInterfaceName): Get names of all commands in a provided interface

void GetNamesOfEventGenerators(std::vector<std::string> &namesOfEventGenerators, const std::string &componentName, const std::string &providedInterfaceName): Get names of all event generators in a provided interface

void GetNamesOfFunctions(std::vector<std::string> &namesOfFunctions, const std::string &componentName, const std::string &requiredInterfaceName): Get names of all functions in a required interface

void GetNamesOfEventHandlers(std::vector<std::string> &namesOfEventHandlers, const std::string &componentName, const std::string &requiredInterfaceName): Get names of all event handlers in a required interface

void GetDescriptionOfCommand(std::string &description, const std::string &componentName, const std::string &providedInterfaceName, const std::string &commandName): Get description of a command in a provided interface

void GetDescriptionOfEventGenerator(std::string &description, const std::string &componentName, const std::string &providedInterfaceName, const std::string &eventGeneratorName): Get description of a event generator in a provided interface

void GetDescriptionOfFunction(std::string &description, const std::string &componentName, const std::string &requiredInterfaceName, const std::string &functionName): Get description of a function in a required interface

void GetDescriptionOfEventHandler(std::string &description, const std::string &componentName, const std::string &requiredInterfaceName, const std::string &eventHandlerName): Get description of a function in a required interface

inline std::string CISST_DEPRECATED GetIPAddress (void) const: Return IP address of this process

bool IsValidComponentTag(const std::string &tag) const

bool IsValidInterfaceTag(const std::string &tag) const

void AddValidComponentTag(const std::string &tag)

void AddValidInterfaceTag(const std::string &tag)

const std::set<std::string> &GetValidComponentTags(void) const

const std::set<std::string> &GetValidInterfaceTags(void) const

Public Static Functions

static mtsManagerLocal *GetInstance(void): Get a singleton object of local component manager.

static void DeleteInstance(void): DeleteInstance. Since a local component manager is a singleton, and demand-created by the first caller of GetInstance, the destructor will never be called unless an application calls this method just prior to quitting. GetInstance should NOT be used again after this method is called. This method calls Cleanup from its implementation, so a separate call to Cleanup is unnecessary.

static std::vector<std::string> GetIPAddressList(void): Return a list of all IP addresses detected on this machine.

static void GetIPAddressList(std::vector<std::string> &ipAddresses)

static bool CISST_DEPRECATED IsLogAllowed (void): Check if further logs are allowed (used in mtsTask); this could be moved to cmnLogger.

static bool IsLogForwardingEnabled(void): Is system-wide thread-safe logging enabled?

static void SetLogForwarding(bool activate): Enable or disable system-wide thread-safe logging. As of 6/2026, system-wide logging will only be initialized on first call to this method.

static void GetLogForwardingState(bool &state): Get whether system-wide logging is enabled or not

static bool GetLogForwardingState(void)

static void LogDispatcher(const char *str, int len): Callback function for system-wide thread-safe logging