An abstract port. More...

#include <yarp/os/Contactable.h>

Inheritance diagram for yarp::os::Contactable:

Public Member Functions
virtual	~Contactable ()
	Destructor. More...

virtual bool	open (const std::string &name)=0
	Start port operation, with a specific name, with automatically-chosen network parameters. More...

virtual bool	open (const Contact &contact, bool registerName=true)=0
	Start port operation with user-chosen network parameters. More...

virtual bool	addOutput (const std::string &name)=0
	Add an output connection to the specified port. More...

virtual bool	addOutput (const std::string &name, const std::string &carrier)=0
	Add an output connection to the specified port, using a specified carrier. More...

virtual bool	addOutput (const Contact &contact)=0
	Add an output connection to the specified port, using specified network parameters. More...

virtual void	close ()=0
	Stop port activity. More...

virtual void	interrupt ()=0
	Interrupt any current reads or writes attached to the port. More...

virtual void	resume ()=0
	Put the port back in an operative state after interrupt() has been called. More...

virtual Contact	where () const =0
	Returns information about how this port can be reached. More...

virtual std::string	getName () const
	Get name of port. More...

virtual bool	setEnvelope (PortWriter &envelope)=0
	Set an envelope (e.g., a timestamp) to the next message which will be sent. More...

virtual bool	getEnvelope (PortReader &envelope)=0
	Get the envelope information (e.g., a timestamp) from the last message received on the port. More...

virtual int	getInputCount ()=0
	Determine how many connections are arriving into this port. More...

virtual int	getOutputCount ()=0
	Determine how many output connections this port has. More...

virtual void	getReport (PortReport &reporter)=0
	Get information on the state of the port - connections etc. More...

virtual void	setReporter (PortReport &reporter)=0
	Set a callback to be called upon any future connections and disconnections to/from the port. More...

virtual void	resetReporter ()=0
	Remove the callback which is called upon any future connections and disconnections to/from the port. More...

virtual bool	isWriting ()=0
	Report whether the port is currently writing data. More...

virtual void	setReader (PortReader &reader)=0
	Set an external reader for port data. More...

virtual void	setAdminReader (PortReader &reader)=0
	Set an external reader for unrecognized administrative port messages. More...

virtual void	setInputMode (bool expectInput)=0
	Configure the port to allow or forbid inputs. More...

virtual void	setOutputMode (bool expectOutput)=0
	Configure the port to allow or forbid outputs. More...

virtual void	setRpcMode (bool expectRpc)=0
	Configure the port to be RPC only. More...

virtual Type	getType ()=0
	Get the type of data the port has committed to send/receive. More...

virtual void	promiseType (const Type &typ)=0
	Commit the port to a particular type of data. More...

virtual Property *	acquireProperties (bool readOnly)=0
	Access unstructured port properties. More...

virtual void	releaseProperties (Property *prop)=0
	End access unstructured port properties. More...

virtual void	includeNodeInName (bool flag)=0
	Choose whether to prepend a node name (if one is available) to the port's name. More...

void	setReadOnly ()
	Shorthand for setInputMode(true), setOutputMode(false), setRpcMode(false) More...

void	setWriteOnly ()
	Shorthand for setInputMode(false), setOutputMode(true), setRpcMode(false) More...

void	setRpcServer ()
	Shorthand for setInputMode(true), setOutputMode(false), setRpcMode(true) More...

void	setRpcClient ()
	Shorthand for setInputMode(false), setOutputMode(true), setRpcMode(true) More...

virtual bool	setCallbackLock (yarp::os::Mutex *mutex)=0
	Add a lock to use when invoking callbacks. More...

virtual bool	setCallbackLock (std::mutex *mutex=nullptr)=0
	Add a lock to use when invoking callbacks. More...

virtual bool	removeCallbackLock ()=0
	Remove a lock on callbacks added with setCallbackLock() More...

virtual bool	lockCallback ()=0
	Lock callbacks until unlockCallback() is called. More...

virtual bool	tryLockCallback ()=0
	Try to lock callbacks until unlockCallback() is called. More...

virtual void	unlockCallback ()=0
	Unlock callbacks. More...

Detailed Description

An abstract port.

Anything that can be expressed via a Contact.

Definition at line 37 of file Contactable.h.

Constructor & Destructor Documentation

◆ ~Contactable()

yarp::os::Contactable::~Contactable ( )

virtualdefault

Destructor.

Member Function Documentation

◆ acquireProperties()

virtual Property* yarp::os::Contactable::acquireProperties ( bool readOnly )

pure virtual

Access unstructured port properties.

Parameters

readOnly set this if you won't be modifying the properties.

Returns: the port properties (or nullptr if readOnly and none have been set)

Warning: Must be called in the same thread as releaseProperties

◆ addOutput() [1/3]

virtual bool yarp::os::Contactable::addOutput ( const Contact & contact )

pure virtual

Add an output connection to the specified port, using specified network parameters.

Parameters

contact information on how to reach the target

Returns: true iff the connection is successfully created

◆ addOutput() [2/3]

virtual bool yarp::os::Contactable::addOutput ( const std::string & name )

pure virtual

Add an output connection to the specified port.

Parameters

name	the name of the target port

Returns: true iff the connection is successfully created

◆ addOutput() [3/3]

virtual bool yarp::os::Contactable::addOutput	(	const std::string &	name,
		const std::string &	carrier
	)

pure virtual

Add an output connection to the specified port, using a specified carrier.

Parameters

name	the name of the target port
carrier	the carrier (network protocol) to use, e.g. "tcp", "udp", "mcast", "text", ...

Returns: true iff the connection is successfully created

◆ close()

virtual void yarp::os::Contactable::close ( )

pure virtual

Stop port activity.

◆ getEnvelope()

virtual bool yarp::os::Contactable::getEnvelope ( PortReader & envelope )

pure virtual

Get the envelope information (e.g., a timestamp) from the last message received on the port.

You must be sure to match the type of your envelope for getEnvelope with whatever is being sent using setEnvelope. The Stamp class is a typical choice for timestamps. The Bottle class also works as an envelope, but it is not specialized to be efficient.

Parameters

envelope recipient for envelope information for last message received by port.

Returns: true iff reading the envelope was successful

◆ getInputCount()

virtual int yarp::os::Contactable::getInputCount ( )

pure virtual

Determine how many connections are arriving into this port.

In other words, how many other ports have this port listed as an output?

Returns: number of input connections

◆ getName()

std::string yarp::os::Contactable::getName ( ) const

virtual

Get name of port.

Returns: name of port

Reimplemented in yarp::os::BufferedPort< T >, and yarp::os::AbstractContactable.

Definition at line 17 of file Contactable.cpp.

◆ getOutputCount()

virtual int yarp::os::Contactable::getOutputCount ( )

pure virtual

Determine how many output connections this port has.

Returns: number of output connections

◆ getReport()

virtual void yarp::os::Contactable::getReport ( PortReport & reporter )

pure virtual

Get information on the state of the port - connections etc.

PortReport::report will be called once for each connection to the port that exists right now. To request callbacks for any future connections/disconnections, use the setReporter method instead.

Parameters

reporter callback for port event/state information

◆ getType()

virtual Type yarp::os::Contactable::getType ( )

pure virtual

Get the type of data the port has committed to send/receive.

Not all ports commit to a particular type of data.

Returns: type of data to expect/provide

◆ includeNodeInName()

virtual void yarp::os::Contactable::includeNodeInName ( bool flag )

pure virtual

Choose whether to prepend a node name (if one is available) to the port's name.

Node names are set using yarp::os::Node.

Parameters

flag	true if the node name should be added to port names

◆ interrupt()

virtual void yarp::os::Contactable::interrupt ( )

pure virtual

Interrupt any current reads or writes attached to the port.

This is useful prior to calling close(), if there are multiple threads operating on the port. Any reads or writes after the call to interrupt() will fail - unless resume() is called.

◆ isWriting()

virtual bool yarp::os::Contactable::isWriting ( )

pure virtual

Report whether the port is currently writing data.

Returns: true iff the port is writing in the background.

◆ lockCallback()

virtual bool yarp::os::Contactable::lockCallback ( )

pure virtual

Lock callbacks until unlockCallback() is called.

Has no effect if no lock has been set via a call to setCallbackLock(). Will block if callbacks are already locked.

Returns: true if callbacks were locked

◆ open() [1/2]

virtual bool yarp::os::Contactable::open	(	const Contact &	contact,
		bool	registerName = `true`
	)

pure virtual

Start port operation with user-chosen network parameters.

Contact information is supplied by the user rather than the name server. If the Contact information is incomplete, the name server is used to complete it (set registerName to false if you don't want name server help).

Returns: true iff the port started operation successfully and is now visible on the YARP network

◆ open() [2/2]

virtual bool yarp::os::Contactable::open ( const std::string & name )

pure virtual

Start port operation, with a specific name, with automatically-chosen network parameters.

The port is registered with the given name, and allocated network resources, by communicating with the YARP name server.

Returns: true iff the port started operation successfully and is now visible on the YARP network

◆ promiseType()

virtual void yarp::os::Contactable::promiseType ( const Type & typ )

pure virtual

Commit the port to a particular type of data.

Parameters

typ	the type of data the port will send/receive

◆ releaseProperties()

virtual void yarp::os::Contactable::releaseProperties ( Property * prop )

pure virtual

End access unstructured port properties.

Parameters

prop	the port property object provided by acquireProperties()

Warning: Must be called in the same thread as acquireProperties

◆ removeCallbackLock()

virtual bool yarp::os::Contactable::removeCallbackLock ( )

pure virtual

Remove a lock on callbacks added with setCallbackLock()

◆ resetReporter()

virtual void yarp::os::Contactable::resetReporter ( )

pure virtual

Remove the callback which is called upon any future connections and disconnections to/from the port.

◆ resume()

virtual void yarp::os::Contactable::resume ( )

pure virtual

Put the port back in an operative state after interrupt() has been called.

◆ setAdminReader()

virtual void yarp::os::Contactable::setAdminReader ( PortReader & reader )

pure virtual

Set an external reader for unrecognized administrative port messages.

Parameters

reader the external reader to use

◆ setCallbackLock() [1/2]

virtual bool yarp::os::Contactable::setCallbackLock ( std::mutex * mutex = nullptr )

pure virtual

Add a lock to use when invoking callbacks.

mutex.lock() will be called before and mutex.unlock() will be called after the callback. This applies at least to callbacks set by setReader and setAdminReader, and in future may apply to other callbacks.

Parameters

mutex the lock to use. If nullptr, a mutex will be allocated internally by the port, and destroyed with the port.

◆ setCallbackLock() [2/2]

virtual bool yarp::os::Contactable::setCallbackLock ( yarp::os::Mutex * mutex )

pure virtual

Add a lock to use when invoking callbacks.

mutex.lock() will be called before and mutex.unlock() will be called after the callback. This applies at least to callbacks set by setReader and setAdminReader, and in future may apply to other callbacks.

Parameters

mutex the lock to use. If nullptr, a mutex will be allocated internally by the port, and destroyed with the port.

Deprecated:: since YARP 3.3

◆ setEnvelope()

virtual bool yarp::os::Contactable::setEnvelope ( PortWriter & envelope )

pure virtual

Set an envelope (e.g., a timestamp) to the next message which will be sent.

You must be sure to match the type of your envelope for setEnvelope with whatever will be read using getEnvelope. The Stamp class is a typical choice for timestamps. The Bottle class also works as an envelope, but it is not specialized to be efficient.

Currently, for proper operation, the envelope must serialize correctly in text-mode (even if you do not explicitly use text-mode connections). Bottle or Stamp are good choices.

Parameters

envelope information to add to the next message which will be sent

Returns: true iff setting the envelope was successful

◆ setInputMode()

virtual void yarp::os::Contactable::setInputMode ( bool expectInput )

pure virtual

Configure the port to allow or forbid inputs.

By default, ports allow anything.

Parameters

expectInput set to true if this port will be used for input

◆ setOutputMode()

virtual void yarp::os::Contactable::setOutputMode ( bool expectOutput )

pure virtual

Configure the port to allow or forbid outputs.

By default, ports allow anything.

Parameters

expectOutput set to true if this port will be used for output

◆ setReader()

virtual void yarp::os::Contactable::setReader ( PortReader & reader )

pure virtual

Set an external reader for port data.

Parameters

reader the external reader to use

◆ setReadOnly()

void yarp::os::Contactable::setReadOnly ( )

Shorthand for setInputMode(true), setOutputMode(false), setRpcMode(false)

Definition at line 22 of file Contactable.cpp.

◆ setReporter()

virtual void yarp::os::Contactable::setReporter ( PortReport & reporter )

pure virtual

Set a callback to be called upon any future connections and disconnections to/from the port.

To get information on the current connections that exist, use the getReport method instead.

Parameters

reporter callback for port event/state information

◆ setRpcClient()

void yarp::os::Contactable::setRpcClient ( )

Shorthand for setInputMode(false), setOutputMode(true), setRpcMode(true)

Definition at line 43 of file Contactable.cpp.

◆ setRpcMode()

virtual void yarp::os::Contactable::setRpcMode ( bool expectRpc )

pure virtual

Configure the port to be RPC only.

By default all ports can be used for RPC or streaming communication.

Parameters

expectRpc set to true if this port will be used for RPC only

◆ setRpcServer()

void yarp::os::Contactable::setRpcServer ( )

Shorthand for setInputMode(true), setOutputMode(false), setRpcMode(true)

Definition at line 36 of file Contactable.cpp.

◆ setWriteOnly()

void yarp::os::Contactable::setWriteOnly ( )

Shorthand for setInputMode(false), setOutputMode(true), setRpcMode(false)

Definition at line 29 of file Contactable.cpp.

◆ tryLockCallback()

virtual bool yarp::os::Contactable::tryLockCallback ( )

pure virtual

Try to lock callbacks until unlockCallback() is called.

Has no effect if no lock has been set via a call to setCallbackLock(). Returns immediately.

Returns: true if callbacks were locked by this call, false if they were already locked.

◆ unlockCallback()

virtual void yarp::os::Contactable::unlockCallback ( )

pure virtual

Unlock callbacks.

◆ where()

virtual Contact yarp::os::Contactable::where ( ) const

pure virtual

Returns information about how this port can be reached.

Returns: network parameters for this port

Implemented in yarp::os::Port, yarp::os::BufferedPort< T >, and yarp::os::AbstractContactable.

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

src/libYARP_os/src/yarp/os/Contactable.h
src/libYARP_os/src/yarp/os/Contactable.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Contactable()

Member Function Documentation

◆ acquireProperties()

◆ addOutput() [1/3]

◆ addOutput() [2/3]

◆ addOutput() [3/3]

◆ close()

◆ getEnvelope()

◆ getInputCount()

◆ getName()

◆ getOutputCount()

◆ getReport()

◆ getType()

◆ includeNodeInName()

◆ interrupt()

◆ isWriting()

◆ lockCallback()

◆ open() [1/2]

◆ open() [2/2]

◆ promiseType()

◆ releaseProperties()

◆ removeCallbackLock()

◆ resetReporter()

◆ resume()

◆ setAdminReader()

◆ setCallbackLock() [1/2]

◆ setCallbackLock() [2/2]

◆ setEnvelope()

◆ setInputMode()

◆ setOutputMode()

◆ setReader()

◆ setReadOnly()

◆ setReporter()

◆ setRpcClient()

◆ setRpcMode()

◆ setRpcServer()

◆ setWriteOnly()

◆ tryLockCallback()

◆ unlockCallback()

◆ where()