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

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

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 & name )

inline

References OpenSim::Exception::OPENSIM_THROW_IF.

◆ 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::ComponentPath::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

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

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

OpenSim/Common/ComponentSocket.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~AbstractSocket()

◆ AbstractSocket()

Member Function Documentation

◆ appendConnecteePath()

◆ checkConnecteePathProperty()

◆ clearConnecteePath()

◆ clone()

◆ connect()

◆ disconnect()

◆ finalizeConnection()

◆ findAndConnect() [1/2]

◆ findAndConnect() [2/2]

◆ getConnectAtStage()

◆ getConnecteeAsObject()

◆ getConnecteePath() [1/2]

◆ getConnecteePath() [2/2]

◆ getConnecteePathProp()

◆ getConnecteeTypeName()

◆ getName()

◆ getNumConnectees()

◆ getOwner()

◆ hasOwner()

◆ isConnected()

◆ isListSocket()

◆ setConnecteePath() [1/2]

◆ setConnecteePath() [2/2]

◆ setOwner()

◆ updConnecteePathProp()