ERC CISST - cisst software

mtsInterfaceProvided Class Reference
[Multi Task Support]

#include <mtsInterfaceProvided.h>

Inheritance diagram for mtsInterfaceProvided:

Inheritance graph
[legend]
Collaboration diagram for mtsInterfaceProvided:

Collaboration graph
[legend]
List of all members.

Detailed Description

This class implements the provided interface for a component of type 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 (tasks or devices) 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.

Tasks use the mtsInterfaceProvided class. Although it provides many of the same capabilities, it makes use of queues for many of the commands to obtain thread safety.

The main difference between a task interface and a device interface is that the former 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 internal ThreadResources class, which provides a separate "instance" of the provided interface to the client task.

Definition at line 90 of file mtsInterfaceProvided.h.

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Friends

Member Typedef Documentation

typedef mtsInterfaceProvided mtsInterfaceProvided::ThisType

This type

Definition at line 100 of file mtsInterfaceProvided.h.

typedef mtsInterfaceProvidedOrOutput mtsInterfaceProvided::BaseType

Base class

Definition at line 103 of file mtsInterfaceProvided.h.

typedef cmnNamedMap<mtsCommandVoid> mtsInterfaceProvided::CommandVoidMapType

Typedef for a map of name and void commands.

Definition at line 109 of file mtsInterfaceProvided.h.

typedef cmnNamedMap<mtsCommandVoidReturn> mtsInterfaceProvided::CommandVoidReturnMapType

Typedef for a map of name and void return commands.

Definition at line 112 of file mtsInterfaceProvided.h.

typedef cmnNamedMap<mtsCommandWriteBase> mtsInterfaceProvided::CommandWriteMapType

Typedef for a map of name and write commands.

Definition at line 115 of file mtsInterfaceProvided.h.

typedef cmnNamedMap<mtsCommandWriteReturn> mtsInterfaceProvided::CommandWriteReturnMapType

Typedef for a map of name and write return commands.

Definition at line 118 of file mtsInterfaceProvided.h.

typedef cmnNamedMap<mtsCommandRead> mtsInterfaceProvided::CommandReadMapType

Typedef for a map of name and read commands.

Definition at line 121 of file mtsInterfaceProvided.h.

typedef cmnNamedMap<mtsCommandQualifiedReadBase> mtsInterfaceProvided::CommandQualifiedReadMapType

Typedef for a map of name and qualified read commands.

Definition at line 124 of file mtsInterfaceProvided.h.

typedef cmnNamedMap<mtsMulticastCommandVoid> mtsInterfaceProvided::EventVoidMapType

Typedef for a map of event name and void event generators.

Definition at line 127 of file mtsInterfaceProvided.h.

typedef cmnNamedMap<mtsMulticastCommandWriteBase> mtsInterfaceProvided::EventWriteMapType

Typedef for a map of event name and write event generators.

Definition at line 130 of file mtsInterfaceProvided.h.

typedef cmnNamedMap<mtsCommandBase> mtsInterfaceProvided::CommandInternalMapType

Typedef for a map of internally-generated commands (only used for garbage collection).

Definition at line 133 of file mtsInterfaceProvided.h.

typedef std::pair<unsigned int, ThisType *> mtsInterfaceProvided::InterfaceProvidedCreatedPairType [protected]

types and containers to store interfaces cloned for thread safety

Definition at line 468 of file mtsInterfaceProvided.h.

Member Enumeration Documentation

anonymous enum

Default length for argument buffers

Definition at line 106 of file mtsInterfaceProvided.h.

Constructor & Destructor Documentation

mtsInterfaceProvided::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::~mtsInterfaceProvided (  )  [virtual]

Default Destructor.

mtsInterfaceProvided::mtsInterfaceProvided ( mtsInterfaceProvided *  interfaceProvided,
const std::string &  userName,
size_t  mailBoxSize 
) [protected]

Constructor used to create an end user interface (object factory) for each user.

Member Function Documentation

void mtsInterfaceProvided::Cleanup ( void   )  [virtual]

The member function that is executed once the task terminates. This does some cleanup work

Reimplemented from mtsInterfaceProvidedOrOutput.

std::vector<std::string> mtsInterfaceProvided::GetNamesOfCommands ( void   )  const

Get the names of commands provided by this interface.

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

Get the names of commands provided by this interface.

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

Get the names of commands provided by this interface.

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

Get the names of commands provided by this interface.

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

Get the names of commands provided by this interface.

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

Get the names of commands provided by this interface.

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

Get the names of commands provided by this interface.

std::vector<std::string> mtsInterfaceProvided::GetNamesOfEventsVoid ( void   )  const

Get the names of events coming from this interface

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

Get the names of events coming from this interface

mtsCommandVoid* mtsInterfaceProvided::GetCommandVoid ( const std::string &  commandName  )  const

Find a command based on its name.

mtsCommandVoidReturn* mtsInterfaceProvided::GetCommandVoidReturn ( const std::string &  commandName  )  const

Find a command based on its name.

mtsCommandWriteBase* mtsInterfaceProvided::GetCommandWrite ( const std::string &  commandName  )  const

Find a command based on its name.

mtsCommandWriteReturn* mtsInterfaceProvided::GetCommandWriteReturn ( const std::string &  commandName  )  const

Find a command based on its name.

mtsCommandRead* mtsInterfaceProvided::GetCommandRead ( const std::string &  commandName  )  const

Find a command based on its name.

mtsCommandQualifiedReadBase* mtsInterfaceProvided::GetCommandQualifiedRead ( const std::string &  commandName  )  const

Find a command based on its name.

mtsMulticastCommandVoid* mtsInterfaceProvided::GetEventVoid ( const std::string &  eventName  )  const

Find an event based on its name.

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

Find an event based on its name.

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

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)

Definition at line 195 of file mtsInterfaceProvided.h.

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

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)

Definition at line 210 of file mtsInterfaceProvided.h.

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

Add a void command with result.

Definition at line 219 of file mtsInterfaceProvided.h.

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

Add a void command with result.

Definition at line 231 of file mtsInterfaceProvided.h.

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

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)

Definition at line 255 of file mtsInterfaceProvided.h.

Referenced by AddCommandWriteState(), and mtsStateData< _elementType >::AddWriteCommandToInterface().

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

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)

Definition at line 265 of file mtsInterfaceProvided.h.

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

Add a write command with result.

Definition at line 277 of file mtsInterfaceProvided.h.

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

Add a write command with result.

Definition at line 291 of file mtsInterfaceProvided.h.

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

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)

Definition at line 314 of file mtsInterfaceProvided.h.

Referenced by AddCommandReadState(), and mtsStateData< _elementType >::AddReadCommandToInterface().

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

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)

Definition at line 324 of file mtsInterfaceProvided.h.

template<class _elementType>
mtsCommandRead * mtsInterfaceProvided::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.

Definition at line 567 of file mtsInterfaceProvided.h.

References AddCommandQualifiedRead(), AddCommandRead(), CMN_LOG_CLASS_INIT_ERROR, and mtsStateTable::GetAccessor().

template<class _elementType>
mtsCommandQualifiedReadBase * mtsInterfaceProvided::AddCommandReadHistory ( const mtsStateTable &  stateTable,
const _elementType &  stateData,
const std::string &  commandName 
)

Adds command object to read history (i.e., vector of data) from the state table.

Definition at line 586 of file mtsInterfaceProvided.h.

References AddCommandQualifiedRead(), CMN_LOG_CLASS_INIT_ERROR, and mtsStateTable::GetAccessor().

template<class _elementType>
mtsCommandWriteBase * mtsInterfaceProvided::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.

Definition at line 602 of file mtsInterfaceProvided.h.

References AddCommandWrite(), CMN_LOG_CLASS_INIT_ERROR, and mtsStateTable::GetAccessor().

mtsCommandVoid* mtsInterfaceProvided::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 mtsInterfaceProvided::AddEventVoid ( mtsFunctionVoid &  eventTrigger,
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.

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

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.

Definition at line 621 of file mtsInterfaceProvided.h.

References CMN_LOG_CLASS_INIT_ERROR.

Referenced by AddEventWrite().

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

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.

Definition at line 640 of file mtsInterfaceProvided.h.

References AddEventWrite(), and mtsFunctionWrite::Bind().

bool mtsInterfaceProvided::AddObserver ( const std::string &  eventName,
mtsCommandVoid *  handler 
)

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 mtsInterfaceProvided::AddObserver ( const std::string &  eventName,
mtsCommandWriteBase *  handler 
)

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

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

Todo:
documentation outdated This method need to called to create a unique Id and queues for a potential user. When using the methods "GetCommandXyz" later on, the unique Id should be used to define which queues to use. To avoid any issue, each potential thread should require a unique Id and then use it. If two or more tasks are running from the same thread, they can use different Ids but this is not required.

size_t mtsInterfaceProvided::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.

void mtsInterfaceProvided::ToStream ( std::ostream &  outputStream  )  const [virtual]

Send a human readable description of the interface.

Reimplemented from cmnGenericObject.

bool mtsInterfaceProvided::UseQueueBasedOnInterfacePolicy ( mtsCommandQueueingPolicy  queueingPolicy,
const std::string &  methodName,
const std::string &  commandName 
) [protected]

Utility method to determine if a command should be queued or not based on the default policy for the interface and the user's requested policy. This method also generates a warning or error in the log if needed.

mtsCommandVoid* mtsInterfaceProvided::AddCommandVoid ( mtsCommandVoid *  command  )  [protected]

Methods to add an existing command to the interface. These methods will not check the queueing policy of the interface nor the type of command (queued or not). These methods must be used with extreme caution since they bypass the built-in thread safety mechanisms.

mtsCommandVoidReturn* mtsInterfaceProvided::AddCommandVoidReturn ( mtsCommandVoidReturn *  command  )  [protected]

Methods to add an existing command to the interface. These methods will not check the queueing policy of the interface nor the type of command (queued or not). These methods must be used with extreme caution since they bypass the built-in thread safety mechanisms.

mtsCommandRead* mtsInterfaceProvided::AddCommandRead ( mtsCommandRead *  command  )  [protected]

Methods to add an existing command to the interface. These methods will not check the queueing policy of the interface nor the type of command (queued or not). These methods must be used with extreme caution since they bypass the built-in thread safety mechanisms.

Member Data Documentation

mtsMailBox* mtsInterfaceProvided::MailBox [protected]

Mailbox (if supported). Mailboxes should only be provided for end user provided interfaces (if needed). Factory interfaces should not use the mailbox.

Definition at line 477 of file mtsInterfaceProvided.h.

mtsInterfaceQueueingPolicy mtsInterfaceProvided::QueueingPolicy [protected]

Flag to determine if by default void and write commands are queued.

Definition at line 481 of file mtsInterfaceProvided.h.

ThisType* mtsInterfaceProvided::OriginalInterface [protected]

If this interface was created using an existing one, keep a pointer on the original one.

Definition at line 485 of file mtsInterfaceProvided.h.

bool mtsInterfaceProvided::EndUserInterface [protected]

Flag to indicate if this interface can be used directly or if it should be used as a factory to create a new interface. When the interface relies assumes queued commands, the first interface should be created as a factory or template. All users should use their own copy created using GetEndUserInterface().

Definition at line 492 of file mtsInterfaceProvided.h.

size_t mtsInterfaceProvided::UserCounter [protected]

Counter for number of users, i.e. number or required interfaces connected to this provided interface. This number should remain consistent with the size of created interfaces list.

Definition at line 498 of file mtsInterfaceProvided.h.

CommandVoidMapType mtsInterfaceProvided::CommandsVoid [protected]

Containers of commands

Definition at line 501 of file mtsInterfaceProvided.h.

mtsCallableVoidBase* mtsInterfaceProvided::PostCommandQueuedCallable [protected]

Post command queued command

Definition at line 512 of file mtsInterfaceProvided.h.

osaMutex mtsInterfaceProvided::Mutex [protected]

Semaphore used internally

Definition at line 515 of file mtsInterfaceProvided.h.

The documentation for this class was generated from the following file:
erc-cisst-devel<at>lists.johnshopkins.edu