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

#include <BufferedPort.h>

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

Public Types
typedef T	ContentType
	The type of content stored by this BufferedPort.
Public Member Functions
	BufferedPort ()
	Constructor.
virtual	~BufferedPort ()
	Destructor.
virtual bool	open (const char *name)
virtual bool	open (const Contact &contact, bool registerName=true)
virtual bool	addOutput (const char *name)
virtual bool	addOutput (const char name, const char carrier)
virtual bool	addOutput (const Contact &contact)
virtual void	close ()
virtual void	interrupt ()
virtual int	getPendingReads ()
	Get the number of objects ready to be read.
virtual Contact	where () const
virtual ConstString	getName () const
T &	prepare ()
	Access the object which will be transmitted by the next call to yarp::os::BufferedPort::write.
bool	unprepare ()
	Give the last prepared object back to YARP without writing it.
void	write (bool forceStrict=false)
	Write the current object being returned by BufferedPort::prepare.
void	writeStrict ()
	Write the current object being returned by BufferedPort::prepare, waiting until any previous sends are complete.
void	setStrict (bool strict=true)
virtual T *	read (bool shouldWait=true)
virtual T *	lastRead ()
virtual bool	isClosed ()
void	setReplier (PortReader &reader)
virtual void	onRead (T &datum)
	this method will be called with new data, as long as you've requested this be done by calling useCallback()
void	useCallback (TypedReaderCallback< T > &callback)
	Set an object whose onRead method will be called when data is available.
void	useCallback ()
	Call own onRead() method -- user can override that method to be informed about data as it arrives.
void	disableCallback ()
virtual bool	setEnvelope (PortWriter &envelope)
virtual bool	getEnvelope (PortReader &envelope)
virtual int	getInputCount ()
virtual int	getOutputCount ()
bool	isWriting ()
virtual void	getReport (PortReport &reporter)
virtual void	setReporter (PortReport &reporter)
virtual void *	acquire ()
virtual void	release (void *handle)
bool	open ()
	Start port operation, with automatically-chosen network parameters.
virtual bool	open (const char *name)=0
	Start port operation, with a specific name, with automatically-chosen network parameters.
virtual bool	open (const Contact &contact, bool registerName=true)=0
	Start port operation with user-chosen network parameters.
virtual bool	addOutput (const char *name)=0
	Add an output connection to the specified port.
virtual bool	addOutput (const char name, const char carrier)=0
	Add an output connection to the specified port, using a specified carrier.
virtual bool	addOutput (const Contact &contact)=0
	Add an output connection to the specified port, using specified network parameters.
virtual void	close ()=0
	Stop port activity.
virtual void	interrupt ()=0
	Interrupt any current reads or writes attached to the port.
virtual Contact	where () const =0
	Returns information about how this port can be reached.
virtual ConstString	getName () const
	Get name of port.
virtual bool	setEnvelope (PortWriter &envelope)=0
	Every message sent by a port can have some information added to it called an envelope (this could be a timestamp, for example).
virtual bool	getEnvelope (PortReader &envelope)=0
	Every message sent by a port can have some information added to it called an envelope (this could be a timestamp, for example).
virtual int	getInputCount ()=0
	Determine how many connections are arriving into this port.
virtual int	getOutputCount ()=0
	Determine how many output connections this port has.
virtual void	getReport (PortReport &reporter)=0
	Get information on the state of the port - connections etc.
virtual void	setReporter (PortReport &reporter)=0
	Set a callback to be called upon any future connections and disconnections to/from the port.
virtual bool	isWriting ()=0
	Report whether the port is currently writing data.
virtual void	setStrict (bool strict=true)=0
	Call this to strictly keep all messages, or allow old ones to be quietly dropped.
virtual T *	read (bool shouldWait=true)=0
	Read an available object from the port.
virtual void	interrupt ()=0
	Abort any read operation currently in progress.
virtual T *	lastRead ()=0
	Get the last data returned by read().
virtual bool	isClosed ()=0
virtual void	useCallback (TypedReaderCallback< T > &callback)=0
	Set an object whose onRead method will be called when data is available.
virtual void	disableCallback ()=0
	Remove a callback set up with useCallback().
virtual int	getPendingReads ()=0
	Check how many messages are waiting to be read.
virtual ConstString	getName () const =0
	Get name of port being read from.
virtual void	setReplier (PortReader &reader)=0
	If a message is received that requires a reply, use this handler.
virtual void *	acquire ()=0
	Take control of the last object read.
virtual void	release (void *handle)=0
	Return control to YARP of an object previously taken control of with the acquire() method.
virtual void	onRead (T &datum, const yarp::os::TypedReader< T > &reader)
	Callback method.

Detailed Description

template<class 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 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).

Examples:: os/image_process.cpp, os/image_process_module.cpp, os/image_source.cpp, and port_power/ex0301_buffered_callback.cpp.

Member Typedef Documentation

template<class T>

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

The type of content stored by this BufferedPort.

Constructor & Destructor Documentation

template<class T>

yarp::os::BufferedPort< T >::BufferedPort ( ) [inline]

Constructor.

template<class T>

virtual yarp::os::BufferedPort< T >::~BufferedPort ( ) [inline, virtual]

Destructor.

Member Function Documentation

template<class T>

virtual void* yarp::os::BufferedPort< T >::acquire ( ) [inline, virtual]

Referenced by PortTest::testAcquire().

template<class T>

virtual void* yarp::os::TypedReader< T >::acquire ( ) [pure virtual, inherited]

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.

template<class T>

virtual bool yarp::os::BufferedPort< T >::addOutput	(	const char *	name,
		const char *	carrier
	)			`[inline, virtual]`

virtual bool yarp::os::Contactable::addOutput ( const char * name ) [pure virtual, inherited]

Add an output connection to the specified port.

Parameters:

name

the name of the target port

Returns:: true iff the connection is successfully created

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

virtual bool yarp::os::Contactable::addOutput	(	const char *	name,
		const char *	carrier
	)			`[pure virtual, inherited]`

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

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

virtual bool yarp::os::Contactable::addOutput ( const Contact & contact ) [pure virtual, inherited]

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

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual bool yarp::os::BufferedPort< T >::addOutput ( const Contact & contact ) [inline, virtual]

template<class T>

virtual bool yarp::os::BufferedPort< T >::addOutput ( const char * name ) [inline, virtual]

Referenced by PortTest::testBufferedPort().

virtual void yarp::os::Contactable::close ( ) [pure virtual, inherited]

Stop port activity.

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual void yarp::os::BufferedPort< T >::close ( void ) [inline, virtual]

Referenced by yarp::dev::AnalogSensorClient::close(), PortTest::testAdmin(), PortTest::testUnbufferedClose(), and SDLPanel::~SDLPanel().

template<class T>

void yarp::os::BufferedPort< T >::disableCallback ( ) [inline]

Referenced by PortReaderBufferTest::checkCallback().

template<class T>

virtual void yarp::os::TypedReader< T >::disableCallback ( ) [pure virtual, inherited]

Remove a callback set up with useCallback().

virtual bool yarp::os::Contactable::getEnvelope ( PortReader & envelope ) [pure virtual, inherited]

Every message sent by a port can have some information added to it called an envelope (this could be a timestamp, for example).

If a port has received a message with such information, you can extract that envelope with this method.

You must be sure to match the type of your envelope for getEnvelope with whatever is being sent using setEnvelope. The Bottle class can read any kind of envelope (but is not specialized to be efficient).

Parameters:

envelope

recipient for envelope information for last message received by port.

Returns:: true iff read was successful

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual bool yarp::os::BufferedPort< T >::getEnvelope ( PortReader & envelope ) [inline, virtual]

Referenced by StampTest::checkEnvelope().

virtual int yarp::os::Contactable::getInputCount ( ) [pure virtual, inherited]

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

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual int yarp::os::BufferedPort< T >::getInputCount ( ) [inline, virtual]

template<class T>

virtual ConstString yarp::os::BufferedPort< T >::getName ( ) const [inline, virtual]

virtual ConstString yarp::os::Contactable::getName ( ) const [inline, virtual, inherited]

Get name of port.

Returns:: name of port

Reimplemented in yarp::os::RpcClient, and yarp::os::RpcServer.

References yarp::os::Contact::getName(), and yarp::os::Contactable::where().

template<class T>

virtual ConstString yarp::os::TypedReader< T >::getName ( ) const [pure virtual, inherited]

Get name of port being read from.

Returns:: name of port

virtual int yarp::os::Contactable::getOutputCount ( ) [pure virtual, inherited]

Determine how many output connections this port has.

Returns:: number of output connections

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual int yarp::os::BufferedPort< T >::getOutputCount ( ) [inline, virtual]

template<class T>

virtual int yarp::os::BufferedPort< T >::getPendingReads ( ) [inline, virtual]

Get the number of objects ready to be read.

Referenced by StampTest::checkEnvelope().

template<class T>

virtual int yarp::os::TypedReader< T >::getPendingReads ( ) [pure virtual, inherited]

Check how many messages are waiting to be read.

Returns:

virtual void yarp::os::Contactable::getReport ( PortReport & reporter ) [pure virtual, inherited]

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

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual void yarp::os::BufferedPort< T >::getReport ( PortReport & reporter ) [inline, virtual]

template<class T>

virtual void yarp::os::BufferedPort< T >::interrupt ( ) [inline, virtual]

virtual void yarp::os::Contactable::interrupt ( ) [pure virtual, inherited]

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. The port should not be used again after a call to interrupt().

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual void yarp::os::TypedReader< T >::interrupt ( ) [pure virtual, inherited]

Abort any read operation currently in progress.

template<class T>

virtual bool yarp::os::BufferedPort< T >::isClosed ( ) [inline, virtual]

template<class T>

virtual bool yarp::os::TypedReader< T >::isClosed ( ) [pure virtual, inherited]

Returns:: true if Port associated with this reader has been closed

template<class T>

bool yarp::os::BufferedPort< T >::isWriting ( ) [inline]

virtual bool yarp::os::Contactable::isWriting ( ) [pure virtual, inherited]

Report whether the port is currently writing data.

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

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual T* yarp::os::BufferedPort< T >::lastRead ( ) [inline, virtual]

template<class T>

virtual T* yarp::os::TypedReader< T >::lastRead ( ) [pure virtual, inherited]

Get the last data returned by read().

Returns:: pointer to last data returned by read(), or NULL on failure.

template<class T>

virtual void yarp::os::BufferedPort< T >::onRead ( T & datum ) [inline, virtual]

this method will be called with new data, as long as you've requested this be done by calling useCallback()

Reimplemented from yarp::os::TypedReaderCallback< T >.

Reimplemented in InputPortProcessor, and PortReaderBufferTestHelper.

template<class T>

virtual void yarp::os::TypedReaderCallback< T >::onRead	(	T &	datum,
		const yarp::os::TypedReader< T > &	reader
	)			`[inline, virtual, inherited]`

Callback method.

Passes along source of callback. By default, this calls the version of onRead that just takes a datum.

Parameters:

	datum	data read from a port
	reader	the original port (or delegate object)

bool yarp::os::Contactable::open ( ) [inline, inherited]

Start port operation, with automatically-chosen network parameters.

The port is assigned an arbitrary 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

template<class T>

virtual bool yarp::os::BufferedPort< T >::open	(	const Contact &	contact,
		bool	registerName = `true`
	)			`[inline, virtual]`

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

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

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

virtual bool yarp::os::Contactable::open ( const char * name ) [pure virtual, inherited]

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

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual bool yarp::os::BufferedPort< T >::open ( const char * name ) [inline, virtual]

Referenced by PortReaderBufferTest::checkCallback(), StampTest::checkEnvelope(), PortReaderBufferTest::checkLocal(), yarp::dev::AnalogSensorClient::open(), PortTest::testAcquire(), PortTest::testAdmin(), PortTest::testBufferedPort(), ModuleTest::testBufferedPort(), PortTest::testCloseOpenRepeats(), PortTest::testReaderHandler2(), PortTest::testRecentReader(), PortTest::testStrictWriter(), and PortTest::testUnbufferedClose().

template<class T>

T& yarp::os::BufferedPort< T >::prepare ( ) [inline]

Access the object which will be transmitted by the next call to yarp::os::BufferedPort::write.

The object can safely be modified by the user of this class, to prepare it. Extra objects will be created or reused as necessary depending on the state of communication with the output(s) of the port. Be careful! If prepare() gives you a reused object, it is up to the user to clear the object if that is appropriate. If you are sending yarp::os::Bottle objects, you may want to call yarp::os::Bottle::clear(), for example. YARP doesn't clear objects for you, since there are many cases in which overwriting old data is suffient and reallocation of memory would be unnecessary and inefficient.

Returns:: the next object that will be written

Referenced by PortReaderBufferTest::checkCallback(), StampTest::checkEnvelope(), PortReaderBufferTest::checkLocal(), PortTest::testAcquire(), PortTest::testBufferedPort(), PortTest::testCloseOpenRepeats(), PortTest::testRecentReader(), PortTest::testStrictWriter(), and PortTest::testUnbufferedClose().

template<class T>

virtual T* yarp::os::BufferedPort< T >::read ( bool shouldWait = true ) [inline, virtual]

Referenced by PortReaderBufferTest::checkCallback(), StampTest::checkEnvelope(), PortReaderBufferTest::checkLocal(), PortTest::testAcquire(), PortTest::testBufferedPort(), PortTest::testCloseOpenRepeats(), PortTest::testRecentReader(), and PortTest::testStrictWriter().

template<class T>

virtual T* yarp::os::TypedReader< T >::read ( bool shouldWait = true ) [pure virtual, inherited]

Read an available object from the port.

Parameters:

shouldWait

true if the method should wait until an object is available

Returns:: A pointer to an object read from the port, or NULL if none is available and waiting was not requested. This object is owned by the communication system and should not be deleted by the user. The object is available to the user until the next call to one of the read methods, after which it should not be accessed again.

template<class T>

virtual void yarp::os::BufferedPort< T >::release ( void * handle ) [inline, virtual]

Referenced by PortTest::testAcquire().

template<class T>

virtual void yarp::os::TypedReader< T >::release ( void * handle ) [pure virtual, inherited]

Return control to YARP of an object previously taken control of with the acquire() method.

Parameters:

handle

the pointer returned by acquire() when control of the object was taken by the user.

virtual bool yarp::os::Contactable::setEnvelope ( PortWriter & envelope ) [pure virtual, inherited]

Every message sent by a port can have some information added to it called an envelope (this could be a timestamp, for example).

You can set that envelope with this method.

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

Parameters:

envelope

some information to add to the next message sent

Returns:: true iff write was successful

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual bool yarp::os::BufferedPort< T >::setEnvelope ( PortWriter & envelope ) [inline, virtual]

Referenced by StampTest::checkEnvelope().

template<class T>

virtual void yarp::os::TypedReader< T >::setReplier ( PortReader & reader ) [pure virtual, inherited]

If a message is received that requires a reply, use this handler.

No buffering happens.

Parameters:

reader

the handler to use

Referenced by ModuleHelper::attach(), and yarp::dev::DeviceResponder::attach().

template<class T>

void yarp::os::BufferedPort< T >::setReplier ( PortReader & reader ) [inline]

virtual void yarp::os::Contactable::setReporter ( PortReport & reporter ) [pure virtual, inherited]

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

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

template<class T>

virtual void yarp::os::BufferedPort< T >::setReporter ( PortReport & reporter ) [inline, virtual]

template<class T>

void yarp::os::BufferedPort< T >::setStrict ( bool strict = true ) [inline]

Referenced by StampTest::checkEnvelope(), PortTest::testAcquire(), PortTest::testReaderHandler2(), PortTest::testRecentReader(), and PortTest::testStrictWriter().

template<class T>

virtual void yarp::os::TypedReader< T >::setStrict ( bool strict = true ) [pure virtual, inherited]

Call this to strictly keep all messages, or allow old ones to be quietly dropped.

If you don't call this, old messages will be quietly dropped.

Parameters:

strict

True to keep all messages until they are read, false to drop old messages when a new one comes in.

template<class T>

bool yarp::os::BufferedPort< T >::unprepare ( ) [inline]

Give the last prepared object back to YARP without writing it.

Returns:: true if there was a prepared object to return.

template<class T>

void yarp::os::BufferedPort< T >::useCallback ( ) [inline]

Call own onRead() method -- user can override that method to be informed about data as it arrives.

template<class T>

void yarp::os::BufferedPort< T >::useCallback ( TypedReaderCallback< T > & callback ) [inline]

Set an object whose onRead method will be called when data is available.

Referenced by PortReaderBufferTest::checkCallback(), yarp::dev::AnalogSensorClient::open(), and PortTest::testReaderHandler2().

template<class T>

virtual void yarp::os::TypedReader< T >::useCallback ( TypedReaderCallback< T > & callback ) [pure virtual, inherited]

Set an object whose onRead method will be called when data is available.

Parameters:

callback

the object whose onRead method will be called with data

Referenced by ModuleHelper::attach(), and yarp::dev::DeviceResponder::attach().

virtual Contact yarp::os::Contactable::where ( ) const [pure virtual, inherited]

Returns information about how this port can be reached.

Returns:: network parameters for this port

Implemented in yarp::os::RpcClient, and yarp::os::RpcServer.

Referenced by yarp::os::Contactable::getName().

template<class T>

virtual Contact yarp::os::BufferedPort< T >::where ( ) const [inline, virtual]

Referenced by yarp::os::BufferedPort< Sound >::getName().

template<class T>

void yarp::os::BufferedPort< T >::write ( bool forceStrict = false ) [inline]

Write the current object being returned by BufferedPort::prepare.

That object should no longer be touched by the user of this class -- it is now owned by the communications system. The BufferedPort::prepare method should be called again to get a fresh (or reused) object guaranteed to be not in use by the communications system.

Parameters:

forceStrict

If this is true, wait until any previous sends are complete. If false, the current object will not be sent on connections that are currently busy.

Referenced by PortReaderBufferTest::checkCallback(), StampTest::checkEnvelope(), PortReaderBufferTest::checkLocal(), PortTest::testAcquire(), PortTest::testBufferedPort(), PortTest::testCloseOpenRepeats(), PortTest::testRecentReader(), PortTest::testStrictWriter(), PortTest::testUnbufferedClose(), and yarp::os::BufferedPort< Sound >::writeStrict().

template<class T>

void yarp::os::BufferedPort< T >::writeStrict ( ) [inline]

Write the current object being returned by BufferedPort::prepare, waiting until any previous sends are complete.

That object should no longer be touched by the user of this class -- it is now owned by the communications system. The BufferedPort::prepare method should be called again to get a fresh (or reused) object guaranteed to be not in use by the communications system.

Referenced by StampTest::checkEnvelope().

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

BufferedPort.h

All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

yarp::os::BufferedPort< T > Class Template Reference [Communication Classes]

Public Types

Public Member Functions

Detailed Description

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

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

yarp::os::BufferedPort< T > Class Template Reference
[Communication Classes]

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