API  4.1
For C++ developers
OpenSim::AbstractSocket Class Referenceabstract

A Socket formalizes the dependency between a Component and another object (typically another Component) without owning that object. More...

+ Inheritance diagram for OpenSim::AbstractSocket:

Public Member Functions

virtual ~AbstractSocket ()
 
virtual AbstractSocketclone () const =0
 Create a dynamically-allocated copy. More...
 
const std::string & getName () const
 
SimTK::Stage getConnectAtStage () const
 Get the system Stage when the connection should be made. More...
 
bool isListSocket () const
 Can this Socket have more than one connectee? More...
 
unsigned getNumConnectees () const
 The number of slots to fill in order to satisfy this socket. More...
 
virtual bool isConnected () const =0
 Derived classes must satisfy this Interface. More...
 
virtual std::string getConnecteeTypeName () const =0
 Get the type of object this socket connects to. More...
 
virtual const ObjectgetConnecteeAsObject () const
 Generic access to the connectee. More...
 
virtual void connect (const Object &connectee)=0
 Connect this Socket to the provided connectee object. More...
 
virtual void findAndConnect (const ComponentPath &connectee)
 Find the connectee using a search with a partial path. More...
 
void findAndConnect (const std::string &connectee)
 Same as findAndConnect(const ComponentPath&), but using a string argument. More...
 
virtual void finalizeConnection (const Component &root)
 Connect this Socket according to its connectee path property given a root Component to search its subcomponents for the connect_to Component. More...
 
virtual void disconnect ()=0
 Clear references to connectees. More...
 
void setConnecteePath (const std::string &name)
 Set connectee path. More...
 
void setConnecteePath (const std::string &name, unsigned ix)
 Set connectee path of a connectee among a list of connectees. More...
 
const std::string & getConnecteePath () const
 Get connectee path. More...
 
const std::string & getConnecteePath (unsigned ix) const
 Get connectee path of a connectee among a list of connectees. More...
 
void appendConnecteePath (const std::string &name)
 
void clearConnecteePath ()
 Clear all connectee paths in the connectee path property. More...
 
const ComponentgetOwner () const
 Get owner component of this socket. More...
 

Protected Member Functions

 AbstractSocket (const std::string &name, const PropertyIndex &connecteePathIndex, const SimTK::Stage &connectAtStage, Component &owner)
 Create a Socket with specified name and stage at which it should be connected. More...
 
void setOwner (Component &o)
 Set an internal pointer to the Component that contains this Socket. More...
 
bool hasOwner () const
 This will be false immediately after copy construction or assignment. More...
 
void checkConnecteePathProperty ()
 Check if entries of the connectee path property's value is valid (if it contains spaces, etc.); if so, print out a warning. More...
 
const Property< std::string > & getConnecteePathProp () const
 Const access to the connectee path property from the Component in which this Socket resides. More...
 
Property< std::string > & updConnecteePathProp ()
 Writable access to the connectee path property from the Component in which this Socket resides. More...
 

Detailed Description

A Socket formalizes the dependency between a Component and another object (typically another Component) without owning that object.

While Components can be composites (of multiple components) they often depend on unrelated objects/components that are defined and owned elsewhere. The object that satisfies the requirements of the Socket we term the "connectee". When a Socket is satisfied by a connectee we have a successful "connection" or is said to be connected.

The purpose of a Socket is to specify: 1) the connectee type that the Component is dependent on, 2) by when (what stage) the socket must be connected in order for the component to function, 3) the name of a connectee that can be found at run-time to satisfy the socket, and 4) whether or not it is connected. A Socket maintains a reference to the instance (connectee) until it is disconnected.

For example, a Joint has two Sockets for the parent and child Bodies that it joins. The type for the socket is a PhysicalFrame and any attempt to connect to a non-Body (or frame rigidly attached to a Body) will throw an exception. The connectAt Stage is Topology. That is, the Joint's connection to a Body must be performed at the Topology system stage, and any attempt to change the connection status will invalidate that Stage and above.

Other Components like a Marker or a Probe that do not change the system topology or add new states could potentially be connected at later stages like Model or Instance.

Programmatically, the connectee can be specified as an object reference or via a connectee path:

// Specifying the connectee using an object reference.
socket.connect(myConnectee);
// Specifying the connectee via a path.
socket.setConnecteePath("/path/to/connectee");

Use finalizeConnection() to synchronize the object reference and connectee name. It is preferable to use connect() instead of setConnecteePath(). If both are set, then the object reference overrides the connectee path.

The connectee path appears in XML files and is how a connection is maintained across serialization (writing to an XML file) and deserialization (reading from an XML file).

Author
Ajay Seth

Constructor & Destructor Documentation

◆ ~AbstractSocket()

virtual OpenSim::AbstractSocket::~AbstractSocket ( )
inlinevirtual

◆ AbstractSocket()

OpenSim::AbstractSocket::AbstractSocket ( const std::string &  name,
const PropertyIndex &  connecteePathIndex,
const SimTK::Stage &  connectAtStage,
Component owner 
)
inlineprotected

Create a Socket with specified name and stage at which it should be connected.

Parameters
namename of the socket, usually describes its dependency.
connecteePathIndexIndex of the property in the containing Component that holds this Socket's connectee path(s).
connectAtStageStage at which Socket should be connected.
ownerComponent to which this Socket belongs.

Member Function Documentation

◆ appendConnecteePath()

void OpenSim::AbstractSocket::appendConnecteePath ( const std::string &  name)
inline

◆ checkConnecteePathProperty()

void OpenSim::AbstractSocket::checkConnecteePathProperty ( )
inlineprotected

Check if entries of the connectee path property's value is valid (if it contains spaces, etc.); if so, print out a warning.

References OpenSim::ComponentPath::getComponentName(), OpenSim::Path::isLegalPathElement(), and OpenSim::Exception::OPENSIM_THROW.

◆ clearConnecteePath()

void OpenSim::AbstractSocket::clearConnecteePath ( )
inline

Clear all connectee paths in the connectee path property.

◆ clone()

virtual AbstractSocket* OpenSim::AbstractSocket::clone ( ) const
pure virtual

Create a dynamically-allocated copy.

You must manage the memory for the returned pointer. This function exists to facilitate the use of SimTK::ClonePtr<AbstractSocket>.

Implemented in OpenSim::Input< T >, OpenSim::AbstractInput, and OpenSim::Socket< T >.

◆ connect()

virtual void OpenSim::AbstractSocket::connect ( const Object connectee)
pure virtual

Connect this Socket to the provided connectee object.

If this is a list socket, the connectee is appended to the list of connectees; otherwise, the provided connectee replaces the single connectee.

Implemented in OpenSim::AbstractInput, and OpenSim::Socket< T >.

◆ disconnect()

virtual void OpenSim::AbstractSocket::disconnect ( )
pure virtual

Clear references to connectees.

The connectee path property is not affected. Calling finalizeConnection() will use the connectee path property to satisfy the socket.

Implemented in OpenSim::Input< T >, and OpenSim::Socket< T >.

◆ finalizeConnection()

virtual void OpenSim::AbstractSocket::finalizeConnection ( const Component root)
inlinevirtual

Connect this Socket according to its connectee path property given a root Component to search its subcomponents for the connect_to Component.

Reimplemented in OpenSim::Input< T >, and OpenSim::Socket< T >.

References OpenSim::Exception::Exception().

◆ findAndConnect() [1/2]

virtual void OpenSim::AbstractSocket::findAndConnect ( const ComponentPath connectee)
inlinevirtual

Find the connectee using a search with a partial path.

Use this if you do not want to specify an exact path (maybe you don't quite know where the connectee is located).

Reimplemented in OpenSim::Socket< T >.

References OpenSim::Exception::OPENSIM_THROW.

◆ findAndConnect() [2/2]

void OpenSim::AbstractSocket::findAndConnect ( const std::string &  connectee)
inline

Same as findAndConnect(const ComponentPath&), but using a string argument.

◆ getConnectAtStage()

SimTK::Stage OpenSim::AbstractSocket::getConnectAtStage ( ) const
inline

Get the system Stage when the connection should be made.

◆ getConnecteeAsObject()

virtual const Object& OpenSim::AbstractSocket::getConnecteeAsObject ( ) const
inlinevirtual

Generic access to the connectee.

Not all sockets support this method (e.g., the connectee for an Input is not an Object).

Reimplemented in OpenSim::Socket< T >.

References OpenSim::Exception::OPENSIM_THROW.

Referenced by OpenSim::Component::getConnectee().

◆ getConnecteePath() [1/2]

const std::string& OpenSim::AbstractSocket::getConnecteePath ( ) const
inline

Get connectee path.

This function can only be used if this socket is not a list socket.

References OpenSim::Exception::OPENSIM_THROW_IF.

◆ getConnecteePath() [2/2]

const std::string& OpenSim::AbstractSocket::getConnecteePath ( unsigned  ix) const
inline

Get connectee path of a connectee among a list of connectees.

◆ getConnecteePathProp()

const Property<std::string>& OpenSim::AbstractSocket::getConnecteePathProp ( ) const
protected

Const access to the connectee path property from the Component in which this Socket resides.

The name of that property is something like 'socket_<name>'. This is a special type of property that users cannot easily access (e.g., there is no macro-generated get_socket_<name>() function).

◆ getConnecteeTypeName()

virtual std::string OpenSim::AbstractSocket::getConnecteeTypeName ( ) const
pure virtual

Get the type of object this socket connects to.

Implemented in OpenSim::Input< T >, and OpenSim::Socket< T >.

Referenced by OpenSim::ConnecteeNotSpecified::ConnecteeNotSpecified().

◆ getName()

const std::string& OpenSim::AbstractSocket::getName ( ) const
inline

◆ getNumConnectees()

unsigned OpenSim::AbstractSocket::getNumConnectees ( ) const
inline

The number of slots to fill in order to satisfy this socket.

This is 1 for a non-list socket. This is the number of elements in the connectee path property; to sync this with the number of connectee objects, call finalizeConnection().

◆ getOwner()

const Component& OpenSim::AbstractSocket::getOwner ( ) const
inline

Get owner component of this socket.

◆ hasOwner()

bool OpenSim::AbstractSocket::hasOwner ( ) const
inlineprotected

This will be false immediately after copy construction or assignment.

◆ isConnected()

virtual bool OpenSim::AbstractSocket::isConnected ( ) const
pure virtual

Derived classes must satisfy this Interface.

Is the Socket connected to its connectee(s)? For a list socket, this is only true if this socket is connected to all its connectees.

Implemented in OpenSim::Input< T >, and OpenSim::Socket< T >.

Referenced by OpenSim::Component::getConnectee(), and OpenSim::Component::getInputValue().

◆ isListSocket()

bool OpenSim::AbstractSocket::isListSocket ( ) const
inline

Can this Socket have more than one connectee?

◆ setConnecteePath() [1/2]

void OpenSim::AbstractSocket::setConnecteePath ( const std::string &  name)
inline

Set connectee path.

This function can only be used if this socket is not a list socket. If a connectee reference is set (with connect()) the connectee path is ignored; call disconnect() if you want the socket to be connected using the connectee path.

It is preferable to use connect() instead of this function.

References OpenSim::Exception::OPENSIM_THROW_IF.

◆ setConnecteePath() [2/2]

void OpenSim::AbstractSocket::setConnecteePath ( const std::string &  name,
unsigned  ix 
)
inline

Set connectee path of a connectee among a list of connectees.

This function is used if this socket is a list socket. If a connectee reference is set (with connect()) the connectee path is ignored; call disconnect() if you want the socket to be connected using the connectee name.

It is preferable to use connect() instead of this function.

◆ setOwner()

void OpenSim::AbstractSocket::setOwner ( Component o)
inlineprotected

Set an internal pointer to the Component that contains this Socket.

This should only be called by Component. This exists so that after the containing Component is copied, the 'owner' is the new Component. This Socket needs to be able to modify the associated connectee path property in the Component. Thus, we require a writable reference.

◆ updConnecteePathProp()

Property<std::string>& OpenSim::AbstractSocket::updConnecteePathProp ( )
protected

Writable access to the connectee path property from the Component in which this Socket resides.

Calling this will mark the Component as not "up to date with properties" (Object::isObjectUpToDateWithProperties()).


The documentation for this class was generated from the following file: