A mini-server for performing network communication in the background. More...

#include <yarp/os/BufferedPort.h>

Inheritance diagram for yarp::os::BufferedPort< T >:

Public Types
typedef T	ContentType
	The type of content stored by this BufferedPort. More...

Public Member Functions
	BufferedPort ()
	Constructor. More...

	BufferedPort (Port &port)
	Wrap an existing unbuffered port. More...

virtual	~BufferedPort ()
	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	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...

int	getPendingReads () override
	Get the number of objects ready to be read. More...

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

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

T &	prepare ()
	Access the object which will be transmitted by the next call to yarp::os::BufferedPort::write. More...

bool	unprepare ()
	Give the last prepared object back to YARP without writing it. More...

void	write (bool forceStrict=false)
	Write the current object being returned by BufferedPort::prepare. More...

void	writeStrict ()
	Write the current object being returned by BufferedPort::prepare, waiting until any previous sends are complete. More...

void	waitForWrite ()
	Wait for any pending writes to complete. More...

void	setStrict (bool strict=true) override
	Call this to strictly keep all messages, or allow old ones to be quietly dropped. More...

T *	read (bool shouldWait=true) override
	Read an available object from the port. More...

T *	lastRead () override
	Get the last data returned by read() More...

bool	isClosed () override
	Returns whether the port associated with this reader has been closed. More...

void	setReplier (PortReader &reader) override
	If a message is received that requires a reply, use this handler. 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	onRead (T &datum) override
	Callback method. More...

void	useCallback (TypedReaderCallback< T > &callback) override
	Set an object whose onRead method will be called when data is available. More...

void	useCallback ()
	Use own onRead() method as callback. More...

void	disableCallback () override
	Remove a callback set up with useCallback() 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...

bool	isWriting () override
	Report whether the port is currently writing data. 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 *	acquire () override
	Take control of the last object read. More...

void	release (void *handle) override
	Return control to YARP of an object previously taken control of with the acquire() method. More...

void	setTargetPeriod (double period) override
	Try to provide data periodically. 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...

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

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	setCallbackLock (yarp::os::Mutex *mutex) override
	Add a lock to use when invoking callbacks. More...

bool	setCallbackLock (std::mutex *mutex) 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...

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

Public Member Functions inherited from yarp::os::TypedReader< T >
virtual	~TypedReader ()=default
	Destructor. More...

Public Member Functions inherited from yarp::os::TypedReaderCallback< T >
virtual	~TypedReaderCallback ()
	Destructor. More...

virtual void	onRead (T &datum, const yarp::os::TypedReader< T > &reader)
	Callback method. More...

Detailed Description

template<typename T>
class yarp::os::BufferedPort< T >

A mini-server for performing network communication in the background.

If you are a beginner, you might want to use the yarp::os::Port class first, and then come back to BufferedPort when you want to send and receive messages in the background without having to stop your processing. This is convenient, but requires a little care to understand the life-cycle of objects written to and read from the network (see BufferedPort::read and BufferedPort::write).

By default a BufferedPort attempts to reduce latency between senders and receivers. To do so messages may be dropped by the writer if BufferedPort::write is called too quickly The reader may also drop old messages if BufferedPort::read is not called fast enough, so that new messages can travel with high priority. This policy is sometimes called Oldest Packet Drop (ODP).

If your application cannot afford dropping messages you can change the buffering policy. Use BufferedPort::writeStrict() when writing to a port, this waits for pending transmissions to be finished before writing new data. Call BufferedPort::setStrict() to change the buffering policy to FIFO at the receiver side. In this way all messages will be stored inside the BufferedPort and delivered to the reader. Pay attention that in this case a slow reader may cause increasing latency and memory use.

Methods that can be useful to monitor the status of read and write operations are yarp::os::BufferedPort::getPendingReads() and yarp::os::BufferedPort::isWriting().

See also

For examples and help, see:

Examples: framerate/main.cpp, os/buffered_port/buffered_port.cpp, os/image_process/image_process.cpp, os/image_process_module/image_process_module.cpp, os/image_source/image_source.cpp, os/make_count/make_count.cpp, os/summer/summer.cpp, os/view_count/view_count.cpp, port_power/ex0100_receiver.cpp, port_power/ex0101_sender.cpp, port_power/ex0200_polling.cpp, port_power/ex0301_buffered_callback.cpp, port_power/ex0302_buffered_ext_callback.cpp, and port_power/ex0403_bufferedport_callback_reply.cpp.

Definition at line 63 of file BufferedPort.h.

Member Typedef Documentation

◆ ContentType

template<typename T >

typedef T yarp::os::BufferedPort< T >::ContentType

The type of content stored by this BufferedPort.

Definition at line 71 of file BufferedPort.h.

Constructor & Destructor Documentation

◆ BufferedPort() [1/2]

template<typename T >

yarp::os::BufferedPort< T >::BufferedPort

Constructor.

Definition at line 17 of file BufferedPort-inl.h.

◆ BufferedPort() [2/2]

template<typename T >

yarp::os::BufferedPort< T >::BufferedPort ( Port & port )

Wrap an existing unbuffered port.

Definition at line 27 of file BufferedPort-inl.h.

◆ ~BufferedPort()

template<typename T >

yarp::os::BufferedPort< T >::~BufferedPort

virtual

Destructor.

Definition at line 35 of file BufferedPort-inl.h.

Member Function Documentation

◆ acquire()

template<typename T >

void * yarp::os::BufferedPort< T >::acquire ( )

overridevirtual

Take control of the last object read.

YARP will not reuse that object until it is explicitly released by the user. Be careful - if you acquire objects without releasing, YARP will keep making new ones to store incoming messages. So you need to release all objects you acquire eventually to avoid running out of memory.

Returns: the handle to call release() with in order to give YARP back control of the last object read.

Implements yarp::os::TypedReader< T >.

Definition at line 281 of file BufferedPort-inl.h.

◆ acquireProperties()

template<typename T >

yarp::os::Property * yarp::os::BufferedPort< T >::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

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

Public Types

Public Member Functions

Detailed Description

template<typename T> class yarp::os::BufferedPort< T >

Member Typedef Documentation

◆ ContentType

Constructor & Destructor Documentation

◆ BufferedPort() [1/2]

◆ BufferedPort() [2/2]

◆ ~BufferedPort()

Member Function Documentation

◆ acquire()

◆ acquireProperties()

◆ addOutput() [1/3]

◆ addOutput() [2/3]

◆ addOutput() [3/3]

◆ close()

◆ disableCallback()

◆ getEnvelope()

◆ getInputCount()

◆ getName()

◆ getOutputCount()

◆ getPendingReads()

◆ getReport()

◆ getType()

◆ includeNodeInName()

◆ interrupt()

◆ isClosed()

◆ isWriting()

◆ lastRead()

◆ lockCallback()

◆ onRead()

◆ open() [1/2]

◆ open() [2/2]

◆ prepare()

◆ promiseType()

◆ read()

◆ release()

◆ releaseProperties()

◆ removeCallbackLock()

◆ resetReporter()

◆ resume()

◆ setAdminReader()

◆ setCallbackLock() [1/2]

◆ setCallbackLock() [2/2]

◆ setEnvelope()

◆ setInputMode()

◆ setOutputMode()

◆ setReader()

◆ setReplier()

◆ setReporter()

◆ setRpcMode()

◆ setStrict()

◆ setTargetPeriod()

◆ tryLockCallback()

◆ unlockCallback()

◆ unprepare()

◆ useCallback() [1/2]

◆ useCallback() [2/2]

◆ waitForWrite()

◆ where()

◆ write()

◆ writeStrict()

template<typename T>
class yarp::os::BufferedPort< T >