yarp::os::Port Class Reference

A mini-server for network communication. More...

#include <yarp/os/Port.h>

Inheritance diagram for yarp::os::Port:

Public Member Functions
	Port ()
	Constructor. More...
	~Port () override
	Destructor. More...
bool	open (const std::string &name) override
	Start port operation, with a specific name, with automatically-chosen network parameters. More...
bool	open (const Contact &contact, bool registerName=true) override
	Start port operation with user-chosen network parameters. More...
bool	sharedOpen (Port &port)
	Open a port wrapping an existing port. More...
bool	openFake (const std::string &name)
	Start port without making it accessible from the network. More...
bool	addOutput (const std::string &name) override
	Add an output connection to the specified port. More...
bool	addOutput (const std::string &name, const std::string &carrier) override
	Add an output connection to the specified port, using a specified carrier. More...
bool	addOutput (const Contact &contact) override
	Add an output connection to the specified port, using specified network parameters. More...
void	close () override
	Stop port activity. More...
void	interrupt () override
	Interrupt any current reads or writes attached to the port. More...
void	resume () override
	Put the port back in an operative state after interrupt() has been called. More...
Contact	where () const override
	Returns information about how this port can be reached. More...
bool	write (const PortWriter &writer, const PortWriter *callback=nullptr) const override
	Write an object to the port. More...
bool	write (const PortWriter &writer, PortReader &reader, const PortWriter *callback=nullptr) const override
	Write an object to the port, then expect one back. More...
bool	read (PortReader &reader, bool willReply=false) override
	Read an object from the port. More...
bool	reply (PortWriter &writer) override
	Send an object as a reply to an object read from the port. More...
bool	replyAndDrop (PortWriter &writer) override
	Same as reply(), but closes connection after reply. More...
void	setReader (PortReader &reader) override
	Set an external reader for port data. More...
void	setAdminReader (PortReader &reader) override
	Set an external reader for unrecognized administrative port messages. More...
void	setReaderCreator (PortReaderCreator &creator)
	Set a creator for readers for port data. More...
void	enableBackgroundWrite (bool backgroundFlag)
	control whether writing from this port is done in the background. More...
bool	isWriting () override
	Report whether the port is currently writing data. More...
bool	setEnvelope (PortWriter &envelope) override
	Set an envelope (e.g., a timestamp) to the next message which will be sent. More...
bool	getEnvelope (PortReader &envelope) override
	Get the envelope information (e.g., a timestamp) from the last message received on the port. More...
int	getInputCount () override
	Determine how many connections are arriving into this port. More...
int	getOutputCount () override
	Determine how many output connections this port has. More...
void	getReport (PortReport &reporter) override
	Get information on the state of the port - connections etc. More...
void	setReporter (PortReport &reporter) override
	Set a callback to be called upon any future connections and disconnections to/from the port. More...
void	resetReporter () override
	Remove the callback which is called upon any future connections and disconnections to/from the port. More...
void	setAdminMode (bool adminMode=true)
	Turn on/off "admin" mode. More...
void	setInputMode (bool expectInput) override
	Configure the port to allow or forbid inputs. More...
void	setOutputMode (bool expectOutput) override
	Configure the port to allow or forbid outputs. More...
void	setRpcMode (bool expectRpc) override
	Configure the port to be RPC only. More...
bool	setTimeout (float timeout)
	Set a timeout on network operations. More...
void	setVerbosity (int level)
	Set whether the port should issue messages about its operations. More...
int	getVerbosity ()
	Get port verbosity level. More...
Type	getType () override
	Get the type of data the port has committed to send/receive. More...
void	promiseType (const Type &typ) override
	Commit the port to a particular type of data. More...
Property *	acquireProperties (bool readOnly) override
	Access unstructured port properties. More...
void	releaseProperties (Property *prop) override
	End access unstructured port properties. More...
void	includeNodeInName (bool flag) override
	Choose whether to prepend a node name (if one is available) to the port's name. More...
bool	isOpen () const
	Check if the port has been opened. More...
bool	setCallbackLock (yarp::os::Mutex *mutex) override
	Add a lock to use when invoking callbacks. More...
bool	setCallbackLock (std::mutex *mutex=nullptr) override
	Add a lock to use when invoking callbacks. More...
bool	removeCallbackLock () override
	Remove a lock on callbacks added with setCallbackLock() More...
bool	lockCallback () override
	Lock callbacks until unlockCallback() is called. More...
bool	tryLockCallback () override
	Try to lock callbacks until unlockCallback() is called. More...
void	unlockCallback () override
	Unlock callbacks. More...
Public Member Functions inherited from yarp::os::Contactable
virtual	~Contactable ()
	Destructor. More...
virtual std::string	getName () const
	Get name of port. 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...

Detailed Description

A mini-server for network communication.

It maintains a dynamic collection of incoming and outgoing connections. Data coming from any incoming connection can be received by calling Port::read. Calls to Port::write result in data being sent to all the outgoing connections.

Communication with Port objects is blocking by default, this means that YARP will not drop messages and timing between readers and senders will be coupled (notice that messages may still get dropped in the network if you use an unreliable protocol like UDP).

See also

For help sending and receiving data in the background and decouple timing, see BufferedPort, or PortReaderBuffer and PortWriterBuffer.

For examples and help, see:

• What is a Port?
• Getting Started with YARP Ports
• Port Power, Going Further with Ports
• Buffering Policies in YARP

Examples

os/database/database.cpp, os/image_process_module/image_process_module.cpp, os/portable_pair/portable_pair.cpp, os/simple_receiver/simple_receiver.cpp, os/simple_sender/simple_sender.cpp, port_power/ex0000_receiver.cpp, port_power/ex0001_sender.cpp, port_power/ex0300_port_callback.cpp, port_power/ex0400_expect_reply.cpp, port_power/ex0401_give_reply.cpp, port_power/ex0402_port_callback_reply.cpp, port_power/ex0500_raw_target_receiver.cpp, port_power/ex0501_raw_target_sender.cpp, port_power/ex0503_serial_target_receiver.cpp, port_power/ex0504_serial_target_sender.cpp, port_power/ex0505_compliant_target_receiver.cpp, port_power/ex0506_compliant_target_sender.cpp, port_power/ex0507_alternative_compliant_target_receiver.cpp, and port_power/ex0508_alternative_compliant_target_sender.cpp.

Definition at line 49 of file Port.h.

Constructor & Destructor Documentation

Port()

Port::Port

(

)

Constructor.

The port begins life in a dormant state. Call Port::open to start things happening.

Definition at line 48 of file Port.cpp.

~Port()

Port::~Port ( )

override

Destructor.

Definition at line 54 of file Port.cpp.

Member Function Documentation

acquireProperties()

Property * Port::acquireProperties ( bool  readOnly )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 656 of file Port.cpp.

addOutput() [1/3]

bool Port::addOutput ( const Contact &  contact )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 406 of file Port.cpp.

addOutput() [2/3]

bool Port::addOutput ( const std::string &  name )

overridevirtual

Add an output connection to the specified port.

Parameters

name	the name of the target port

Returns

true iff the connection is successfully created

Implements yarp::os::Contactable.

Definition at line 347 of file Port.cpp.

addOutput() [3/3]

bool Port::addOutput ( const std::string &  name, const std::string &  carrier  )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 352 of file Port.cpp.

close()

void Port::close ( )

overridevirtual

Stop port activity.

Implements yarp::os::Contactable.

Definition at line 357 of file Port.cpp.

enableBackgroundWrite()

void Port::enableBackgroundWrite

(

bool

backgroundFlag

)

control whether writing from this port is done in the background.

Parameters

backgroundFlag

if true, calls to Port::write should return immediately

Definition at line 527 of file Port.cpp.

getEnvelope()

bool Port::getEnvelope ( PortReader &  envelope )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 548 of file Port.cpp.

getInputCount()

int Port::getInputCount ( )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 554 of file Port.cpp.

getOutputCount()

int Port::getOutputCount ( )

overridevirtual

Determine how many output connections this port has.

Returns

number of output connections

Implements yarp::os::Contactable.

Definition at line 561 of file Port.cpp.

getReport()

void Port::getReport ( PortReport &  reporter )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 568 of file Port.cpp.

getType()

Type Port::getType ( )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 646 of file Port.cpp.

getVerbosity()

int Port::getVerbosity

(

)

Get port verbosity level.

Returns

port verbosity level.

Deprecated:

since YARP 3.4

Definition at line 640 of file Port.cpp.

includeNodeInName()

void Port::includeNodeInName ( bool  flag )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 666 of file Port.cpp.

interrupt()

void Port::interrupt ( )

overridevirtual

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.

Implements yarp::os::Contactable.

Definition at line 377 of file Port.cpp.

isOpen()

bool Port::isOpen

(

)

const

Check if the port has been opened.

Definition at line 671 of file Port.cpp.

isWriting()

bool Port::isWriting ( )

overridevirtual

Report whether the port is currently writing data.

Returns

true iff the port is writing in the background.

Implements yarp::os::Contactable.

Definition at line 534 of file Port.cpp.

lockCallback()

bool Port::lockCallback ( )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 699 of file Port.cpp.

open() [1/2]

bool Port::open ( const Contact &  contact, bool  registerName = true  )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 87 of file Port.cpp.

open() [2/2]

bool Port::open ( const std::string &  name )

overridevirtual

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

Implements yarp::os::Contactable.

Examples

port_power/ex0000_receiver.cpp, port_power/ex0001_sender.cpp, port_power/ex0300_port_callback.cpp, port_power/ex0400_expect_reply.cpp, port_power/ex0401_give_reply.cpp, port_power/ex0402_port_callback_reply.cpp, port_power/ex0500_raw_target_receiver.cpp, port_power/ex0501_raw_target_sender.cpp, port_power/ex0503_serial_target_receiver.cpp, port_power/ex0504_serial_target_sender.cpp, port_power/ex0505_compliant_target_receiver.cpp, port_power/ex0506_compliant_target_sender.cpp, port_power/ex0507_alternative_compliant_target_receiver.cpp, and port_power/ex0508_alternative_compliant_target_sender.cpp.

Definition at line 82 of file Port.cpp.

openFake()

bool Port::openFake

(

const std::string &

name

)

Start port without making it accessible from the network.

The port is unusable for many purposes, other than sending out data to specific outputs added with addOutput().

Parameters

name	an arbitrary name that connections from this port will claim to be from.

Returns

true on success

Definition at line 77 of file Port.cpp.

promiseType()

void Port::promiseType ( const Type &  typ )

overridevirtual

Commit the port to a particular type of data.

Parameters

typ	the type of data the port will send/receive

Implements yarp::os::Contactable.

Definition at line 651 of file Port.cpp.

read()

bool Port::read ( PortReader &  reader, bool  willReply = false  )

overridevirtual

Read an object from the port.

Parameters

reader	any object that knows how to read itself from a network connection - see for example Bottle
willReply	you must set this to true if you intend to call reply()

Returns

true iff the object is successfully read

Implements yarp::os::UnbufferedContactable.

Examples

port_power/ex0000_receiver.cpp, port_power/ex0401_give_reply.cpp, port_power/ex0500_raw_target_receiver.cpp, port_power/ex0503_serial_target_receiver.cpp, port_power/ex0505_compliant_target_receiver.cpp, and port_power/ex0507_alternative_compliant_target_receiver.cpp.

Definition at line 475 of file Port.cpp.

releaseProperties()

void Port::releaseProperties ( Property *  prop )

overridevirtual

End access unstructured port properties.

Parameters

prop	the port property object provided by acquireProperties()

Warning

Must be called in the same thread as acquireProperties

Implements yarp::os::Contactable.

Definition at line 661 of file Port.cpp.

removeCallbackLock()

bool Port::removeCallbackLock ( )

overridevirtual

Remove a lock on callbacks added with setCallbackLock()

Implements yarp::os::Contactable.

Definition at line 694 of file Port.cpp.

reply()

bool Port::reply ( PortWriter &  writer )

overridevirtual

Send an object as a reply to an object read from the port.

Only call this method if you set the willReply flag to true when you called Port::read.

Parameters

writer

any object that knows how to write itself to a network connection - see for example Bottle

Returns

true iff the object is successfully written

Implements yarp::os::UnbufferedContactable.

Examples

port_power/ex0401_give_reply.cpp.

Definition at line 492 of file Port.cpp.

replyAndDrop()

bool Port::replyAndDrop ( PortWriter &  writer )

overridevirtual

Same as reply(), but closes connection after reply.

This is useful for interoperation with XML/RPC clients that do not expect to reuse a connection.

Parameters

writer

any object that knows how to write itself to a network connection - see for example Bottle

Returns

true iff the object is successfully written

Implements yarp::os::UnbufferedContactable.

Definition at line 498 of file Port.cpp.

resetReporter()

void Port::resetReporter ( )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 582 of file Port.cpp.

resume()

void Port::resume ( )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 386 of file Port.cpp.

setAdminMode()

void Port::setAdminMode

(

bool

adminMode = true

)

Turn on/off "admin" mode.

With admin mode on, messages received from this port will be treated by other ports as administrative messages, rather than as data to pass on to the owner of the port.

Parameters

adminMode

administration flag

Definition at line 589 of file Port.cpp.

setAdminReader()

void Port::setAdminReader ( PortReader &  reader )

overridevirtual

Set an external reader for unrecognized administrative port messages.

Parameters

reader

the external reader to use

Implements yarp::os::Contactable.

Definition at line 512 of file Port.cpp.

setCallbackLock() [1/2]

bool Port::setCallbackLock ( std::mutex *  mutex = nullptr )

overridevirtual

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.

Implements yarp::os::Contactable.

Definition at line 689 of file Port.cpp.

setCallbackLock() [2/2]

bool Port::setCallbackLock ( yarp::os::Mutex *  mutex )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 682 of file Port.cpp.

setEnvelope()

bool Port::setEnvelope ( PortWriter &  envelope )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 541 of file Port.cpp.

setInputMode()

void Port::setInputMode ( bool  expectInput )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 604 of file Port.cpp.

setOutputMode()

void Port::setOutputMode ( bool  expectOutput )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 612 of file Port.cpp.

setReader()

void Port::setReader ( PortReader &  reader )

overridevirtual

Set an external reader for port data.

Parameters

reader

the external reader to use

Implements yarp::os::Contactable.

Examples

port_power/ex0300_port_callback.cpp, and port_power/ex0402_port_callback_reply.cpp.

Definition at line 505 of file Port.cpp.

setReaderCreator()

void Port::setReaderCreator

(

PortReaderCreator &

creator

)

Set a creator for readers for port data.

Every port that input is received from will be automatically given its own reader. Handy if you care about the identity of the receiver.

Parameters

creator

the "factory" for creating PortReader object

Definition at line 519 of file Port.cpp.

setReporter()

void Port::setReporter ( PortReport &  reporter )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 575 of file Port.cpp.

setRpcMode()

void Port::setRpcMode ( bool  expectRpc )

overridevirtual

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

Implements yarp::os::Contactable.

Definition at line 620 of file Port.cpp.

setTimeout()

bool Port::setTimeout

(

float

timeout

)

Set a timeout on network operations.

Use a negative number to wait forever (this is the default behavior). Call this method early, since it won't affect connections that have already been made.

Parameters

timeout

number of seconds to wait for individual network operations to complete (negative to wait forever).

Definition at line 628 of file Port.cpp.

setVerbosity()

void Port::setVerbosity

(

int

level

)

Set whether the port should issue messages about its operations.

Parameters

level

verbosity level, -1 to inhibit messages.

Deprecated:

since YARP 3.4

Definition at line 635 of file Port.cpp.

sharedOpen()

bool Port::sharedOpen

(

Port &

port

)

Open a port wrapping an existing port.

Definition at line 66 of file Port.cpp.

tryLockCallback()

bool Port::tryLockCallback ( )

overridevirtual

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.

Implements yarp::os::Contactable.

Definition at line 707 of file Port.cpp.

unlockCallback()

void Port::unlockCallback ( )

overridevirtual

Unlock callbacks.

Implements yarp::os::Contactable.

Definition at line 712 of file Port.cpp.

where()

Contact Port::where ( ) const

overridevirtual

Returns information about how this port can be reached.

Returns

network parameters for this port

Implements yarp::os::Contactable.

Definition at line 399 of file Port.cpp.

write() [1/2]

bool Port::write ( const PortWriter &  writer, const PortWriter *  callback = nullptr  ) const

overridevirtual

Write an object to the port.

Parameters

writer	any object that knows how to write itself to a network connection - see for example Bottle
callback	object on which to call onCompletion() after write is done (otherwise writer.onCompletion() is called)

Returns

true iff the object is successfully written

Implements yarp::os::UnbufferedContactable.

Examples

port_power/ex0001_sender.cpp, port_power/ex0400_expect_reply.cpp, port_power/ex0501_raw_target_sender.cpp, port_power/ex0504_serial_target_sender.cpp, port_power/ex0506_compliant_target_sender.cpp, and port_power/ex0508_alternative_compliant_target_sender.cpp.

Definition at line 430 of file Port.cpp.

write() [2/2]

bool Port::write ( const PortWriter &  writer, PortReader &  reader, const PortWriter *  callback = nullptr  ) const

overridevirtual

Write an object to the port, then expect one back.

Parameters

writer	any object that knows how to write itself to a network connection - see for example Bottle
reader	any object that knows how to read itself from a network connection - see for example Bottle
callback	object on which to call onCompletion() after write is done (otherwise writer.onCompletion() is called)

Returns

true iff an object is successfully written and read

Implements yarp::os::UnbufferedContactable.

Definition at line 452 of file Port.cpp.

---

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

• src/libYARP_os/src/yarp/os/Port.h
• src/libYARP_os/src/yarp/os/Port.cpp