A mini-server for network communication. More...
#include <yarp/os/Port.h>
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).
For examples and help, see:
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... | |
Port::Port | ( | ) |
Constructor.
The port begins life in a dormant state. Call Port::open to start things happening.
|
overridevirtual |
Access unstructured port properties.
readOnly | set this if you won't be modifying the properties. |
Implements yarp::os::Contactable.
|
overridevirtual |
Add an output connection to the specified port, using specified network parameters.
contact | information on how to reach the target |
Implements yarp::os::Contactable.
|
overridevirtual |
Add an output connection to the specified port.
name | the name of the target port |
Implements yarp::os::Contactable.
|
overridevirtual |
Add an output connection to the specified port, using a specified carrier.
name | the name of the target port |
carrier | the carrier (network protocol) to use, e.g. "tcp", "udp", "mcast", "text", ... |
Implements yarp::os::Contactable.
|
overridevirtual |
void Port::enableBackgroundWrite | ( | bool | backgroundFlag | ) |
control whether writing from this port is done in the background.
backgroundFlag | if true, calls to Port::write should return immediately |
|
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.
envelope | recipient for envelope information for last message received by port. |
Implements yarp::os::Contactable.
|
overridevirtual |
Determine how many connections are arriving into this port.
In other words, how many other ports have this port listed as an output?
Implements yarp::os::Contactable.
|
overridevirtual |
Determine how many output connections this port has.
Implements yarp::os::Contactable.
|
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.
reporter | callback for port event/state information |
Implements yarp::os::Contactable.
|
overridevirtual |
Get the type of data the port has committed to send/receive.
Not all ports commit to a particular type of data.
Implements yarp::os::Contactable.
int Port::getVerbosity | ( | ) |
|
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.
flag | true if the node name should be added to port names |
Implements yarp::os::Contactable.
|
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.
bool Port::isOpen | ( | ) | const |
|
overridevirtual |
Report whether the port is currently writing data.
Implements yarp::os::Contactable.
|
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.
Implements yarp::os::Contactable.
|
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).
Implements yarp::os::Contactable.
|
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.
Implements yarp::os::Contactable.
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().
name | an arbitrary name that connections from this port will claim to be from. |
|
overridevirtual |
Commit the port to a particular type of data.
typ | the type of data the port will send/receive |
Implements yarp::os::Contactable.
|
overridevirtual |
Read an object from the port.
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() |
Implements yarp::os::UnbufferedContactable.
|
overridevirtual |
End access unstructured port properties.
prop | the port property object provided by acquireProperties() |
Implements yarp::os::Contactable.
|
overridevirtual |
Remove a lock on callbacks added with setCallbackLock()
Implements yarp::os::Contactable.
|
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.
writer | any object that knows how to write itself to a network connection - see for example Bottle |
Implements yarp::os::UnbufferedContactable.
|
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.
writer | any object that knows how to write itself to a network connection - see for example Bottle |
Implements yarp::os::UnbufferedContactable.
|
overridevirtual |
Remove the callback which is called upon any future connections and disconnections to/from the port.
Implements yarp::os::Contactable.
|
overridevirtual |
Put the port back in an operative state after interrupt() has been called.
Implements yarp::os::Contactable.
void Port::setAdminMode | ( | bool | adminMode = true | ) |
|
overridevirtual |
Set an external reader for unrecognized administrative port messages.
reader | the external reader to use |
Implements yarp::os::Contactable.
|
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.
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.
|
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.
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.
|
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.
envelope | information to add to the next message which will be sent |
Implements yarp::os::Contactable.
|
overridevirtual |
Configure the port to allow or forbid inputs.
By default, ports allow anything.
expectInput | set to true if this port will be used for input |
Implements yarp::os::Contactable.
|
overridevirtual |
Configure the port to allow or forbid outputs.
By default, ports allow anything.
expectOutput | set to true if this port will be used for output |
Implements yarp::os::Contactable.
|
overridevirtual |
Set an external reader for port data.
reader | the external reader to use |
Implements yarp::os::Contactable.
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.
creator | the "factory" for creating PortReader object |
|
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.
reporter | callback for port event/state information |
Implements yarp::os::Contactable.
|
overridevirtual |
Configure the port to be RPC only.
By default all ports can be used for RPC or streaming communication.
expectRpc | set to true if this port will be used for RPC only |
Implements yarp::os::Contactable.
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.
timeout | number of seconds to wait for individual network operations to complete (negative to wait forever). |
void Port::setVerbosity | ( | int | level | ) |
Set whether the port should issue messages about its operations.
level | verbosity level, -1 to inhibit messages. |
bool Port::sharedOpen | ( | Port & | port | ) |
|
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.
Implements yarp::os::Contactable.
|
overridevirtual |
|
overridevirtual |
Returns information about how this port can be reached.
Implements yarp::os::Contactable.
|
overridevirtual |
Write an object to the port.
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) |
Implements yarp::os::UnbufferedContactable.
|
overridevirtual |
Write an object to the port, then expect one back.
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) |
Implements yarp::os::UnbufferedContactable.