YARP
Yet Another Robot Platform
yarp::os::impl::BufferedConnectionWriter Class Reference

A helper for creating cached object descriptions. More...

#include <yarp/os/impl/BufferedConnectionWriter.h>

+ Inheritance diagram for yarp::os::impl::BufferedConnectionWriter:

Public Member Functions

 BufferedConnectionWriter (bool textMode=false, bool bareMode=false)
 Constructor. More...
 
 ~BufferedConnectionWriter () override
 Destructor. More...
 
void reset (bool textMode)
 Completely clear the writer and start afresh. More...
 
void restart ()
 Tell the writer that we will be serializing a new object, but to keep any cached buffers that already exist. More...
 
void clear () override
 Clear all cached data. More...
 
bool addPool (const yarp::os::Bytes &data)
 Add the specified bytes to the current pool buffer. More...
 
void stopPool ()
 Stop adding to the current pool buffer. More...
 
void push (const Bytes &data, bool copy)
 Add the specified buffer to the list of buffers to be written. More...
 
bool isTextMode () const override
 Check if the connection is text mode. More...
 
bool isBareMode () const override
 Check if the connection is bare mode. More...
 
bool convertTextMode () override
 Converts a standard description in binary into a textual description, if the connection is in text-mode. More...
 
void declareSizes (int argc, int *argv) override
 If you can easily determine how many blocks there are in a message, call this first, before anything else. More...
 
void setReplyHandler (PortReader &reader) override
 This sets a handler to deal with replies to the message. More...
 
void appendInt8 (std::int8_t data) override
 Send a representation of a 8-bit integer to the network connection. More...
 
void appendInt16 (std::int16_t data) override
 Send a representation of a 16-bit integer to the network connection. More...
 
void appendInt32 (std::int32_t data) override
 Send a representation of a 32-bit integer to the network connection. More...
 
void appendInt64 (std::int64_t data) override
 Send a representation of a 64-bit integer to the network connection. More...
 
void appendFloat32 (yarp::conf::float32_t data) override
 Send a representation of a 32-bit floating point number to the network connection. More...
 
void appendFloat64 (yarp::conf::float64_t data) override
 Send a representation of a 64-bit floating point number to the network connection. More...
 
void appendBlock (const char *data, size_t len) override
 Send a block of data to the network connection. More...
 
void appendText (const std::string &str, const char terminate='\n') override
 Send a terminated string to the network connection. More...
 
void appendExternalBlock (const char *data, size_t len) override
 Send a block of data to the network connection, without making a copy. More...
 
virtual void appendBlock (const yarp::os::Bytes &data)
 Add a buffer by recording a reference to it, without copying it. More...
 
virtual void appendBlockCopy (const Bytes &data)
 Add a buffer by copying its contents. More...
 
virtual void appendLine (const std::string &data)
 Send a string along with a carriage-return-line-feed sequence. More...
 
size_t length () const override
 
size_t headerLength () const override
 
size_t length (size_t index) const override
 
const char * data (size_t index) const override
 
bool write (ConnectionWriter &connection) const override
 Write this object to a network connection. More...
 
void write (OutputStream &os) override
 
bool write (PortReader &obj)
 Write message to a receiving object. More...
 
virtual size_t dataSize () const
 
size_t bufferCount () const
 
PortReadergetReplyHandler () override
 
void addToHeader ()
 Switch to storing a header. More...
 
yarp::os::PortablegetReference () override
 
void setReference (yarp::os::Portable *obj) override
 Stores a direct pointer to the object being sent. More...
 
bool isValid () const override
 
bool isActive () const override
 
bool isError () const override
 
void requestDrop () override
 Tag the connection to be dropped after the current message. More...
 
bool dropRequested () override
 
void startWrite () const override
 Call when writing is about to begin. More...
 
void stopWrite () const override
 Call when all writing is finished. More...
 
SizedWritergetBuffer () const override
 
void setInitialPoolSize (size_t size)
 Set a custom initial pool size, which affects the size of buffers created for temporary data storage. More...
 
std::string toString () const
 
- Public Member Functions inherited from yarp::os::ConnectionWriter
virtual ~ConnectionWriter ()
 Destructor. More...
 
virtual void appendInt (int data) final
 Send a representation of an integer to the network connection. More...
 
virtual void appendDouble (double data)
 Send a representation of a floating point number to the network connection. More...
 
virtual void appendString (const char *str, const char terminate='\n') final
 Send a character sequence to the network connection. More...
 
virtual void appendRawString (const std::string &str) final
 
void appendString (const std::string &str)
 Send a string to the network connection. More...
 
virtual bool isNull () const
 
- Public Member Functions inherited from yarp::os::SizedWriter
virtual ~SizedWriter ()
 
bool write (ConnectionWriter &connection) const override
 Write this object to a network connection. More...
 
- Public Member Functions inherited from yarp::os::PortWriter
virtual ~PortWriter ()
 Destructor. More...
 
virtual void onCompletion () const
 This is called when the port has finished all writing operations. More...
 
virtual void onCommencement () const
 This is called when the port is about to begin writing operations. More...
 
virtual yarp::os::Type getWriteType () const
 

Additional Inherited Members

- Static Public Member Functions inherited from yarp::os::ConnectionWriter
static ConnectionWritercreateBufferedConnectionWriter ()
 Create a connection writer implementation that stores to a buffer which can be read later using getBuffer() More...
 
static bool writeToStream (PortWriter &portable, OutputStream &os)
 

Detailed Description

A helper for creating cached object descriptions.

When a object is to be sent from one port to another, and we have multiple connections but don't want to serialize the object multiple times, a BufferedConnectionWriter is useful. It will create buffer space for any parts serialized on the fly, and keep track of any external blocks (e.g. arrays of pixel data) that we want to include verbatim in the message. This class plays no role in management of the lifecycle of external blocks (e.g. when they are created/destroyed, or when they may change in value). If you use external blocks, be sure to pay attention to onCompletion() events on your object.

Definition at line 44 of file BufferedConnectionWriter.h.

Constructor & Destructor Documentation

◆ BufferedConnectionWriter()

BufferedConnectionWriter::BufferedConnectionWriter ( bool  textMode = false,
bool  bareMode = false 
)

Constructor.

Parameters
textModesuggest that the object be serialized in a human readable format. BufferedConnectionWriter simply passes this flag along to read/write methods, it takes on action on it.
bareModesuggest that the object be serialized with the assumption that all type information is known by recipient. BufferedConnectionWriter simply passes this flag along to read/write methods, it takes on action on it.

Definition at line 30 of file BufferedConnectionWriter.cpp.

◆ ~BufferedConnectionWriter()

BufferedConnectionWriter::~BufferedConnectionWriter ( )
override

Destructor.

Definition at line 48 of file BufferedConnectionWriter.cpp.

Member Function Documentation

◆ addPool()

bool BufferedConnectionWriter::addPool ( const yarp::os::Bytes data)

Add the specified bytes to the current pool buffer.

The pool buffer is a place to concatenate small blocks of data that are not being held externally. This requires a memory copy, so for large blocks of data consider adding these separately. A pool buffer will be created if none already exists.

Returns
true on success

Definition at line 94 of file BufferedConnectionWriter.cpp.

◆ addToHeader()

void BufferedConnectionWriter::addToHeader ( )

Switch to storing a header.

Buffers are tracked separately for the header.

Definition at line 408 of file BufferedConnectionWriter.cpp.

◆ appendBlock() [1/2]

void BufferedConnectionWriter::appendBlock ( const char *  data,
size_t  len 
)
overridevirtual

Send a block of data to the network connection.

Since communication may not happen immediately, or may happen multiple times, a copy of this data is made. If you know the block of data will remain valid, and it is a large block of data, please call ConnectionWriter::appendExternalBlock instead.

Parameters
datathe start of the data block
lenthe length of the data block

Implements yarp::os::ConnectionWriter.

Definition at line 266 of file BufferedConnectionWriter.cpp.

◆ appendBlock() [2/2]

void BufferedConnectionWriter::appendBlock ( const yarp::os::Bytes data)
virtual

Add a buffer by recording a reference to it, without copying it.

Be careful, this is the opposite of what appendBlock(ptr, len) does. Sorry about that.

Parameters
datathe buffer to add

Definition at line 290 of file BufferedConnectionWriter.cpp.

◆ appendBlockCopy()

void BufferedConnectionWriter::appendBlockCopy ( const Bytes data)
virtual

Add a buffer by copying its contents.

Parameters
datathe buffer to add

Definition at line 296 of file BufferedConnectionWriter.cpp.

◆ appendExternalBlock()

void BufferedConnectionWriter::appendExternalBlock ( const char *  data,
size_t  len 
)
overridevirtual

Send a block of data to the network connection, without making a copy.

If you are not confident that the block of data will remain valid throughout transmission, call ConnectionWriter::appendBlock instead.

Parameters
datathe start of the data block
lenthe length of the data block

Implements yarp::os::ConnectionWriter.

Definition at line 285 of file BufferedConnectionWriter.cpp.

◆ appendFloat32()

void BufferedConnectionWriter::appendFloat32 ( yarp::conf::float32_t  data)
overridevirtual

Send a representation of a 32-bit floating point number to the network connection.

Parameters
datathe floating point number to send

Implements yarp::os::ConnectionWriter.

Definition at line 256 of file BufferedConnectionWriter.cpp.

◆ appendFloat64()

void BufferedConnectionWriter::appendFloat64 ( yarp::conf::float64_t  data)
overridevirtual

Send a representation of a 64-bit floating point number to the network connection.

Parameters
datathe floating point number to send

Implements yarp::os::ConnectionWriter.

Definition at line 261 of file BufferedConnectionWriter.cpp.

◆ appendInt16()

void BufferedConnectionWriter::appendInt16 ( std::int16_t  data)
overridevirtual

Send a representation of a 16-bit integer to the network connection.

Parameters
datathe integer to send

Implements yarp::os::ConnectionWriter.

Definition at line 241 of file BufferedConnectionWriter.cpp.

◆ appendInt32()

void BufferedConnectionWriter::appendInt32 ( std::int32_t  data)
overridevirtual

Send a representation of a 32-bit integer to the network connection.

Parameters
datathe integer to send

Implements yarp::os::ConnectionWriter.

Definition at line 246 of file BufferedConnectionWriter.cpp.

◆ appendInt64()

void BufferedConnectionWriter::appendInt64 ( std::int64_t  data)
overridevirtual

Send a representation of a 64-bit integer to the network connection.

Parameters
datathe integer to send

Implements yarp::os::ConnectionWriter.

Definition at line 251 of file BufferedConnectionWriter.cpp.

◆ appendInt8()

void BufferedConnectionWriter::appendInt8 ( std::int8_t  data)
overridevirtual

Send a representation of a 8-bit integer to the network connection.

Parameters
datathe integer to send

Implements yarp::os::ConnectionWriter.

Definition at line 236 of file BufferedConnectionWriter.cpp.

◆ appendLine()

void BufferedConnectionWriter::appendLine ( const std::string &  data)
virtual

Send a string along with a carriage-return-line-feed sequence.

This is a convenience function used by old parts of yarp, for telnet compatibility on sockets.

Parameters
datastring to write, not including carriage-return-line-feed.

Definition at line 301 of file BufferedConnectionWriter.cpp.

◆ appendText()

void BufferedConnectionWriter::appendText ( const std::string &  str,
const char  terminate = '\n' 
)
overridevirtual

Send a terminated string to the network connection.

The lenght of string is not specified in advance, therefore the reader should read until the terminating character is found.

Parameters
strthe string to send
terminatethe terminating character to use

Implements yarp::os::ConnectionWriter.

Definition at line 271 of file BufferedConnectionWriter.cpp.

◆ bufferCount()

size_t BufferedConnectionWriter::bufferCount ( ) const

Definition at line 396 of file BufferedConnectionWriter.cpp.

◆ clear()

void BufferedConnectionWriter::clear ( )
overridevirtual

Clear all cached data.

Reimplemented from yarp::os::SizedWriter.

Definition at line 75 of file BufferedConnectionWriter.cpp.

◆ convertTextMode()

bool BufferedConnectionWriter::convertTextMode ( )
overridevirtual

Converts a standard description in binary into a textual description, if the connection is in text-mode.

Useful if you only operate on the binary description usually, and just want to permit text mode for command-line interaction. If isTextMode would return false, no conversion is done.

Returns
true if the conversion was possible

Implements yarp::os::ConnectionWriter.

Definition at line 201 of file BufferedConnectionWriter.cpp.

◆ data()

const char * BufferedConnectionWriter::data ( size_t  index) const
overridevirtual

Implements yarp::os::SizedWriter.

Definition at line 331 of file BufferedConnectionWriter.cpp.

◆ dataSize()

size_t BufferedConnectionWriter::dataSize ( ) const
virtual
Returns
the size of the message that will be sent, in bytes, including the header and payload.

Definition at line 381 of file BufferedConnectionWriter.cpp.

◆ declareSizes()

void BufferedConnectionWriter::declareSizes ( int  argc,
int *  argv 
)
overridevirtual

If you can easily determine how many blocks there are in a message, call this first, before anything else.

This may improve efficiency in some situations.

Parameters
argcNumber of blocks
argvAn array of integers, giving the length of each block

Implements yarp::os::ConnectionWriter.

Definition at line 209 of file BufferedConnectionWriter.cpp.

◆ dropRequested()

bool BufferedConnectionWriter::dropRequested ( )
overridevirtual

Implements yarp::os::SizedWriter.

Definition at line 445 of file BufferedConnectionWriter.cpp.

◆ getBuffer()

SizedWriter * BufferedConnectionWriter::getBuffer ( ) const
overridevirtual
Returns
a buffer if one is present.

Implements yarp::os::ConnectionWriter.

Definition at line 460 of file BufferedConnectionWriter.cpp.

◆ getReference()

yarp::os::Portable * BufferedConnectionWriter::getReference ( )
overridevirtual

Implements yarp::os::SizedWriter.

Definition at line 415 of file BufferedConnectionWriter.cpp.

◆ getReplyHandler()

PortReader * BufferedConnectionWriter::getReplyHandler ( )
overridevirtual

Implements yarp::os::SizedWriter.

Definition at line 402 of file BufferedConnectionWriter.cpp.

◆ headerLength()

size_t BufferedConnectionWriter::headerLength ( ) const
overridevirtual

Implements yarp::os::SizedWriter.

Definition at line 316 of file BufferedConnectionWriter.cpp.

◆ isActive()

bool BufferedConnectionWriter::isActive ( ) const
overridevirtual
Returns
true if the writer is active. Writers may become inactive if the connection they are associated with breaks.

Implements yarp::os::ConnectionWriter.

Definition at line 430 of file BufferedConnectionWriter.cpp.

◆ isBareMode()

bool BufferedConnectionWriter::isBareMode ( ) const
overridevirtual

Check if the connection is bare mode.

If it is, you are encouraged to omit type information from your serialization.

Returns
true if the connection is bare

Implements yarp::os::ConnectionWriter.

Definition at line 195 of file BufferedConnectionWriter.cpp.

◆ isError()

bool BufferedConnectionWriter::isError ( ) const
overridevirtual
Returns
true if the writer encountered an error. Writers can encounter an error if there is some data loss. For unreliable protocols like UDP/Multicast, where losses are not unexpected, this error flag will be reset for the next incoming message.

Implements yarp::os::ConnectionWriter.

Definition at line 435 of file BufferedConnectionWriter.cpp.

◆ isTextMode()

bool BufferedConnectionWriter::isTextMode ( ) const
overridevirtual

Check if the connection is text mode.

If it is, you are encouraged (but by no means required) to use a human-readable representation of your data structure.

Returns
true if the connection is text mode (as opposed to binary)

Implements yarp::os::ConnectionWriter.

Definition at line 190 of file BufferedConnectionWriter.cpp.

◆ isValid()

bool BufferedConnectionWriter::isValid ( ) const
overridevirtual
Returns
true if the writer is valid. A writer may be invalid if a connection has closed.

Implements yarp::os::ConnectionWriter.

Definition at line 425 of file BufferedConnectionWriter.cpp.

◆ length() [1/2]

size_t BufferedConnectionWriter::length ( ) const
overridevirtual

Implements yarp::os::SizedWriter.

Definition at line 311 of file BufferedConnectionWriter.cpp.

◆ length() [2/2]

size_t BufferedConnectionWriter::length ( size_t  index) const
overridevirtual

Implements yarp::os::SizedWriter.

Definition at line 321 of file BufferedConnectionWriter.cpp.

◆ push()

void BufferedConnectionWriter::push ( const Bytes data,
bool  copy 
)

Add the specified buffer to the list of buffers to be written.

If the copy flag is set, the data in the buffer is copied, otherwise a reference to it is kept (be careful to keep the buffer valid until all writes that use it are complete and onComplete() has been called on the object being sent).

Parameters
datathe buffer to add
copywhether the data should be copied, or a reference stored

Definition at line 150 of file BufferedConnectionWriter.cpp.

◆ requestDrop()

void BufferedConnectionWriter::requestDrop ( )
overridevirtual

Tag the connection to be dropped after the current message.

Implements yarp::os::ConnectionWriter.

Definition at line 440 of file BufferedConnectionWriter.cpp.

◆ reset()

void BufferedConnectionWriter::reset ( bool  textMode)

Completely clear the writer and start afresh.

Parameters
textModesee parameter to constructor for details

Definition at line 54 of file BufferedConnectionWriter.cpp.

◆ restart()

void BufferedConnectionWriter::restart ( )

Tell the writer that we will be serializing a new object, but to keep any cached buffers that already exist.

If the structure of the new object matches that of what came before, the buffers will be reused without any new memory allocation being necessary. If the structure differs, memory allocation may be needed.

Definition at line 63 of file BufferedConnectionWriter.cpp.

◆ setInitialPoolSize()

void BufferedConnectionWriter::setInitialPoolSize ( size_t  size)

Set a custom initial pool size, which affects the size of buffers created for temporary data storage.

If this method is not called, the default used is BUFFERED_CONNECTION_INITIAL_POOL_SIZE

Parameters
sizethe initial buffer size (in bytes) to use

Definition at line 466 of file BufferedConnectionWriter.cpp.

◆ setReference()

void BufferedConnectionWriter::setReference ( yarp::os::Portable obj)
overridevirtual

Stores a direct pointer to the object being sent.

This is useful for local communication, to bypass serialization.

Implements yarp::os::ConnectionWriter.

Definition at line 420 of file BufferedConnectionWriter.cpp.

◆ setReplyHandler()

void BufferedConnectionWriter::setReplyHandler ( PortReader reader)
overridevirtual

This sets a handler to deal with replies to the message.

The handler will be called once per connection. There will be problems for connections using carriers that don't support replies.

Parameters
readerthe object that handles replies.

Implements yarp::os::ConnectionWriter.

Definition at line 216 of file BufferedConnectionWriter.cpp.

◆ startWrite()

void BufferedConnectionWriter::startWrite ( ) const
overridevirtual

Call when writing is about to begin.

Implements yarp::os::SizedWriter.

Definition at line 450 of file BufferedConnectionWriter.cpp.

◆ stopPool()

void BufferedConnectionWriter::stopPool ( )

Stop adding to the current pool buffer.

Any further calls to addPool() for the current write will result in creation of a new pool.

Definition at line 141 of file BufferedConnectionWriter.cpp.

◆ stopWrite()

void BufferedConnectionWriter::stopWrite ( ) const
overridevirtual

Call when all writing is finished.

Implements yarp::os::SizedWriter.

Definition at line 454 of file BufferedConnectionWriter.cpp.

◆ toString()

std::string BufferedConnectionWriter::toString ( ) const
Returns
the message serialized as a string

Definition at line 472 of file BufferedConnectionWriter.cpp.

◆ write() [1/3]

bool BufferedConnectionWriter::write ( ConnectionWriter writer) const
overridevirtual

Write this object to a network connection.

Override this for your particular class. Be aware that depending on the nature of the connections a port has, and what protocol they use, and how efficient the YARP implementation is, this method may be called once, twice, or many times, as the result of a single call to Port::write

Parameters
writeran interface to the network connection for writing
Returns
true iff the object is successfully written

Implements yarp::os::PortWriter.

Definition at line 341 of file BufferedConnectionWriter.cpp.

◆ write() [2/3]

void BufferedConnectionWriter::write ( OutputStream os)
overridevirtual

Reimplemented from yarp::os::SizedWriter.

Definition at line 356 of file BufferedConnectionWriter.cpp.

◆ write() [3/3]

bool BufferedConnectionWriter::write ( PortReader obj)

Write message to a receiving object.

This is to simplify writing tests, YARP does not use this internally.

Parameters
objobject to write into
Returns
true on success

Definition at line 370 of file BufferedConnectionWriter.cpp.


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