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 AbstractSocket *	clone () 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 Object &	getConnecteeAsObject (int index=-1) const
	Generic access to the connectee. More...

virtual bool	canConnectTo (const Object &) const =0
	Returns `true` if the socket can connect to the object (i.e. 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 &path, int index=-1)
	Set the connectee path. More...

const std::string &	getConnecteePath (int index=-1) const
	Get the connectee path. More...

void	appendConnecteePath (const std::string &path)
	Append a connectee path to this socket. More...

void	assignConnecteePath (const std::string &path)
	Assign the connectee path to this socket. More...

void	clearConnecteePath ()
	Clear all connectee paths in the connectee path property. More...

bool	isConnecteePathEmpty () const
	Check to see if the connectee path property is "empty". More...

const Component &	getOwner () 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...

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

name	name of the socket, usually describes its dependency.
connecteePathIndex	Index of the property in the containing Component that holds this Socket's connectee path(s).
connectAtStage	Stage at which Socket should be connected.
owner	Component to which this Socket belongs.

Member Function Documentation

◆ appendConnecteePath()

void OpenSim::AbstractSocket::appendConnecteePath ( const std::string & path )

inline

Append a connectee path to this socket.

Only valid for list sockets.

◆ assignConnecteePath()

void OpenSim::AbstractSocket::assignConnecteePath ( const std::string & path )

inline

Assign the connectee path to this socket.

For single-object sockets, this overwrites the singular connectee path value. For list sockets, this appends this path to the list of connectee paths. Use this to update the connectee path property based on existing connectees generically (e.g., during serialization).

◆ canConnectTo()

virtual bool OpenSim::AbstractSocket::canConnectTo ( const Object & ) const

pure virtual

Returns true if the socket can connect to the object (i.e.

because the object is a matching type for the socket)

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

◆ 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(), and OpenSim::ComponentPath::isLegalPathElement().

◆ 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 >.

◆ 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 >.

◆ 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 ( int index = -1 ) 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 >.

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

◆ getConnecteePath()

const std::string& OpenSim::AbstractSocket::getConnecteePath ( int index = -1 ) const

inline

Get the connectee path.

Referenced by OpenSim::Input< T >::setAlias().

◆ 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

Referenced by OpenSim::Socket< T >::connect(), OpenSim::ConnecteeNotSpecified::ConnecteeNotSpecified(), OpenSim::Input< T >::getAlias(), OpenSim::Input< T >::getChannel(), OpenSim::Input< T >::getLabel(), OpenSim::Input< T >::getValue(), and OpenSim::Input< T >::setAlias().

◆ 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().

Referenced by OpenSim::Input< T >::getAlias(), OpenSim::Input< T >::getChannel(), OpenSim::Input< T >::getLabel(), OpenSim::Input< T >::getValue(), OpenSim::Input< T >::isConnected(), and OpenSim::Input< T >::setAlias().

◆ 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().

◆ isConnecteePathEmpty()

bool OpenSim::AbstractSocket::isConnecteePathEmpty ( ) const

inline

Check to see if the connectee path property is "empty".

For single-object sockets, we check if the default connectee path string is empty. For list sockets, we check if the list of connectee paths is empty. Use this if making a connection based on connectee path to check connectee path validity (e.g., during deserialization).

◆ isListSocket()

bool OpenSim::AbstractSocket::isListSocket ( ) const

inline

Can this Socket have more than one connectee?

Referenced by OpenSim::Input< T >::getAlias(), OpenSim::Input< T >::getChannel(), OpenSim::Socket< T >::getConnecteeAsObject(), OpenSim::Input< T >::getLabel(), and OpenSim::Input< T >::getValue().

◆ setConnecteePath()

void OpenSim::AbstractSocket::setConnecteePath	(	const std::string &	path,
		int	index = `-1`
	)

inline

Set the 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.

Referenced by OpenSim::Input< T >::setAlias().

◆ 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.

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

OpenSim/Common/ComponentSocket.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~AbstractSocket()

◆ AbstractSocket()

Member Function Documentation

◆ appendConnecteePath()

◆ assignConnecteePath()

◆ canConnectTo()

◆ checkConnecteePathProperty()

◆ clearConnecteePath()

◆ clone()

◆ connect()

◆ disconnect()

◆ finalizeConnection()

◆ findAndConnect() [1/2]

◆ findAndConnect() [2/2]

◆ getConnectAtStage()

◆ getConnecteeAsObject()

◆ getConnecteePath()

◆ getConnecteeTypeName()

◆ getName()

◆ getNumConnectees()

◆ getOwner()

◆ hasOwner()

◆ isConnected()

◆ isConnecteePathEmpty()

◆ isListSocket()

◆ setConnecteePath()

◆ setOwner()