CommPort Class Reference
A CommPort provides an abstract interface to a communication resource, based on wrapping a standard library stream buffer. More...
#include <CommPort.h>
Detailed Description
A CommPort provides an abstract interface to a communication resource, based on wrapping a standard library stream buffer.
Key extensions provided beyond the std::basic_streambuf are a mutual exclusion lock, explicitly separate read/write buffers (which, depending on implementation, could refer to the same stream), recursive open/close, plist-based configuration parameters, and integration with an InstanceTracker registry and factory for dynamic reconfigurability.
Usually you can get by using one of the standard stream buffers (streambuf, filebuf, stringbuf) but if you need to implement a custom stream, these links may help get you started:
- An article by Paul Grenyer stepping through the process: http://accu.org/index.php/journals/264
- Sample code from Chris Frey for a network class: http://www.netdirect.ca/~cdfrey/software/sockstream.cc.txt
See also our own network stream class, ionetstream (Wireless/netstream.h/.cc). Although intended for networking, you can pass it any file descriptor, which makes it handy for pipes as well.
Clients should be careful to use the locking mechanism if there is a possibility of confusing query-responses or competing command/query-polls!
Example usage: look up an instance named "Foo", and send it a query.
CommPort* comm = CommPort::getRegistry().getInstance("Foo"); std::ostream is(&comm->getReadStreambuf()); std::ostream os(&comm->getWriteStreambuf()); is.tie(&os); // fancy failsafe -- make sure 'os' is flushed anytime we read from 'is' // Locking a CommPort across query-response pairs: int value; { MarkScope autolock(*comm); // marks the comm port as "in use" until the end of its scope os << "query-value-command" << endl; is >> value; // because we have the lock, we know 'value' is in response // to the 'query-value-command', and not a response to any other thread }
Advanced locking: try to get a lock, then transfer it to a MarkScope to ensure exception-safety.
Thread::Lock& l = comm->getLock(); if(l.trylock()) { MarkScope autolock(l); l.unlock(); // transfer lock to MarkScope // use comm ... }
Definition at line 62 of file CommPort.h.
Public Types | |
| typedef std::basic_streambuf < std::ios::char_type > | streambuf |
| the streambuf which does the actual work should inherit from basic_streambuf, using the system's default character type | |
| typedef InstanceTracker < CommPort, std::string, Factory1Arg< CommPort, std::string > > | registry_t |
| short hand for the instance tracker, which allows dynamic reconfiguration of CommPort instances | |
Public Member Functions | |
| virtual | ~CommPort () |
| destructor, removes from registry in case we're deleting it from some other source than registry's own destroy() | |
| virtual std::string | getClassName () const =0 |
| Returns the name of the class (aka its type). | |
| virtual Thread::Lock & | getLock () |
| Provides serialized access to the comm port. | |
| virtual bool | open ()=0 |
| Called when communication is about to begin, should handle recursive open/close calls. | |
| virtual bool | close ()=0 |
| Called when communication is complete, should handle recursive open/close calls. | |
| virtual bool | isReadable () |
| Allows you to check whether the reference from getReadStreambuf() is currently functional (if checking is supported!). | |
| virtual bool | isWriteable () |
| Allows you to check whether the reference from getWriteStreambuf() is currently functional (if checking is supported!). | |
| virtual streambuf & | getReadStreambuf ()=0 |
| Returns a std::basic_streambuf, which is expected to implement the actual work. | |
| virtual streambuf & | getWriteStreambuf ()=0 |
| Returns a std::basic_streambuf, which is expected to implement the actual work. | |
| virtual size_t | read (char *buf, size_t n) |
| returns up to n bytes from the streambuf, returns the number read | |
| virtual size_t | write (const char *buf, size_t n) |
| writes up to n bytes from the streambuf, returns the number written | |
| virtual void | read (std::string &s) |
| reads all available data from getReadStreambuf() | |
| virtual size_t | write (const std::string &s) |
| writes the string into getWriteStreambuf() | |
Static Public Member Functions | |
| static registry_t & | getRegistry () |
| registry from which current instances can be discovered and new instances allocated based on their class names | |
Protected Member Functions | |
| CommPort (const std::string &, const std::string &instancename) | |
| constructor, pass the name of the class's type so we can use it in error messages, and a name for the instance so we can register it for MotionHook's to lookup | |
| virtual void | registerInstance () |
| To be called be "deepest" subclass constructor at the end of construction. | |
| virtual void | useResource (Data &d) |
| Provides a Resource interface, allowing you to use MarkScope directly on the CommPort instead of calling through getLock(). | |
| virtual void | releaseResource (Data &d) |
| provides a Resource interface, allowing you to use MarkScope directly on the CommPort instead of calling through getLock(). | |
| virtual void | opened () |
| should be called by open() once the connection is successfully made, so deeper subclasses can do initialization | |
| virtual void | closing () |
| should be called by close() before the connection is closed, so deeper subclasses can do cleanup | |
Protected Attributes | |
| const std::string | instanceName |
| holds the name of this instance of CommPort (mainly for error message reporting by the class itself) | |
| Thread::Lock | lock |
Private Member Functions | |
| CommPort (const CommPort &) | |
| CommPort & | operator= (const CommPort &) |
Member Typedef Documentation
| typedef InstanceTracker<CommPort,std::string,Factory1Arg<CommPort,std::string> > registry_t |
short hand for the instance tracker, which allows dynamic reconfiguration of CommPort instances
Definition at line 93 of file CommPort.h.
| typedef std::basic_streambuf<std::ios::char_type> streambuf |
the streambuf which does the actual work should inherit from basic_streambuf, using the system's default character type
Definition at line 15 of file CommPort.h.
Constructor & Destructor Documentation
| virtual ~CommPort | ( | ) | [virtual] |
destructor, removes from registry in case we're deleting it from some other source than registry's own destroy()
Definition at line 12 of file CommPort.h.
| CommPort | ( | const std::string & | , | |
| const std::string & | instancename | |||
| ) | [protected] |
constructor, pass the name of the class's type so we can use it in error messages, and a name for the instance so we can register it for MotionHook's to lookup
Definition at line 99 of file CommPort.h.
Member Function Documentation
| virtual bool close | ( | ) | [pure virtual] |
Called when communication is complete, should handle recursive open/close calls.
- Returns:
- true if successful, false if still open (in use elsewhere)
Implemented in ExecutableCommPort, FileSystemCommPort, NetworkCommPort, RedirectionCommPort, and SerialCommPort.
Referenced by SSC32Driver::deregisterSource(), DynamixelDriver::deregisterSource(), CreateDriver::deregisterSource(), DataStreamDriver::disconnect(), SSC32Driver::motionStopping(), DynamixelDriver::motionStopping(), CreateDriver::motionStopping(), SSC32Driver::plistValueChanged(), DynamixelDriver::plistValueChanged(), and CreateDriver::plistValueChanged().
| virtual void closing | ( | ) | [protected, virtual] |
should be called by close() before the connection is closed, so deeper subclasses can do cleanup
Reimplemented in Subscription< T >, Subscription< PListSensorDriver >, and Subscription< ImageStreamDriver >.
Definition at line 126 of file CommPort.h.
Referenced by RedirectionCommPort::close(), NetworkCommPort::close(), FileSystemCommPort::close(), and ExecutableCommPort::close().
| virtual std::string getClassName | ( | ) | const [pure virtual] |
Returns the name of the class (aka its type).
Suggested implementation is to declare a static string member, set it to the result of calling the registry's registerType, and then return that member here
Implemented in ExecutableCommPort, FileSystemCommPort, NetworkCommPort, RedirectionCommPort, and SerialCommPort.
| virtual Thread::Lock& getLock | ( | ) | [virtual] |
Provides serialized access to the comm port.
Multiple drivers might be using the same comm port, callers should get the lock when doing operations on the comm port, particularly across sending a command and waiting for the reply. See MarkScope for usage.
Definition at line 26 of file CommPort.h.
Referenced by SSC32Driver::advance(), CommThread::clearBuffer(), NetworkCommPort::close(), NetworkCommPort::doOpen(), NetworkCommPort::isReadable(), SSC32Driver::motionCheck(), NetworkCommPort::open(), NetworkCommPort::plistValueChanged(), CommThread::runloop(), and CreateDriver::sendCommand().
| virtual streambuf& getReadStreambuf | ( | ) | [pure virtual] |
Returns a std::basic_streambuf, which is expected to implement the actual work.
You can pass this to an istream to use the nice C++ style input and output, or you can call the streambuf functions directly. However, if you're going the latter route, probably easier to just call CommPort's own read() and write().
Depending on implementation, the streambuf this returns might be a different instance than getWriteStreambuf. If they are the same instance, then you could use an iostream instead of separate istream and ostream.
Implemented in ExecutableCommPort, FileSystemCommPort, NetworkCommPort, and RedirectionCommPort.
Referenced by SSC32Driver::advance(), DataStreamDriver::advance(), CreateDriver::advance(), CommThread::clearBuffer(), RedirectionCommPort::getReadStreambuf(), opened(), DataStreamDriver::run(), and CommThread::runloop().
| static registry_t& getRegistry | ( | ) | [static] |
registry from which current instances can be discovered and new instances allocated based on their class names
Definition at line 95 of file CommPort.h.
Referenced by Simulator::cmdDelete(), Simulator::cmdHelp(), Simulator::cmdNew(), RedirectionCommPort::getInputCP(), RedirectionCommPort::getOutputCP(), DynamixelDriver::pingServos(), Simulator::Simulator(), and Simulator::~Simulator().
| virtual streambuf& getWriteStreambuf | ( | ) | [pure virtual] |
Returns a std::basic_streambuf, which is expected to implement the actual work.
You can pass this to an ostream to use the nice C++ style input and output, or you can call the streambuf functions directly. However, if you're going the latter route, probably easier to just call CommPort's own read() and write().
Depending on implementation, the streambuf this returns might be a different instance than getReadStreambuf. If they are the same instance, then you could use an iostream instead of separate istream and ostream.
Implemented in ExecutableCommPort, FileSystemCommPort, NetworkCommPort, and RedirectionCommPort.
Referenced by SSC32Driver::advance(), closing(), RedirectionCommPort::getWriteStreambuf(), SSC32Driver::motionCheck(), DynamixelDriver::motionStarting(), CommThread::runloop(), CreateDriver::sendCommand(), and DynamixelDriver::sendZeroTorqueCmd().
| virtual bool isReadable | ( | ) | [virtual] |
Allows you to check whether the reference from getReadStreambuf() is currently functional (if checking is supported!).
For streambufs which don't have a way to check this, always returns true.
Reimplemented in ExecutableCommPort, FileSystemCommPort, NetworkCommPort, and RedirectionCommPort.
Definition at line 45 of file CommPort.h.
Referenced by SSC32Driver::advance(), DynamixelDriver::advance(), DataStreamDriver::advance(), CreateDriver::advance(), CommThread::clearBuffer(), DynamixelDriver::isConnected(), RedirectionCommPort::isReadable(), SSC32Driver::nextTimestamp(), DynamixelDriver::nextTimestamp(), DataStreamDriver::nextTimestamp(), CreateDriver::nextTimestamp(), DataStreamDriver::run(), and CommThread::runloop().
| virtual bool isWriteable | ( | ) | [virtual] |
Allows you to check whether the reference from getWriteStreambuf() is currently functional (if checking is supported!).
For streambufs which don't have a way to check this, always returns true.
Reimplemented in ExecutableCommPort, FileSystemCommPort, NetworkCommPort, and RedirectionCommPort.
Definition at line 49 of file CommPort.h.
Referenced by SSC32Driver::advance(), DynamixelDriver::advance(), CreateDriver::advance(), CommThread::clearBuffer(), SSC32Driver::isConnected(), DynamixelDriver::isConnected(), CreateDriver::isConnected(), RedirectionCommPort::isWriteable(), SSC32Driver::motionCheck(), CreateDriver::motionCheck(), DynamixelDriver::motionStarting(), DynamixelDriver::nextTimestamp(), DynamixelDriver::registerSource(), CommThread::runloop(), and DynamixelDriver::sendZeroTorqueCmd().
| virtual bool open | ( | ) | [pure virtual] |
Called when communication is about to begin, should handle recursive open/close calls.
The subclass is expected to have its own configuration settings which define the parameters of what is to be "opened". Hence, no arguments are passed.
You should be able to handle recursive levels of open/close in case multiple drivers are using the same CommPort.
- Returns:
- true if successful (or already open)
Implemented in ExecutableCommPort, FileSystemCommPort, NetworkCommPort, RedirectionCommPort, and SerialCommPort.
Referenced by DataStreamDriver::connect(), SSC32Driver::motionStarting(), DynamixelDriver::motionStarting(), CreateDriver::motionStarting(), SSC32Driver::plistValueChanged(), CreateDriver::plistValueChanged(), SSC32Driver::registerSource(), DynamixelDriver::registerSource(), and CreateDriver::registerSource().
| virtual void opened | ( | ) | [protected, virtual] |
should be called by open() once the connection is successfully made, so deeper subclasses can do initialization
Reimplemented in Subscription< T >, SensorSubscription, ImageSubscription, DepthSubscription, Subscription< PListSensorDriver >, and Subscription< ImageStreamDriver >.
Definition at line 125 of file CommPort.h.
Referenced by NetworkCommPort::doOpen(), RedirectionCommPort::open(), FileSystemCommPort::open(), and ExecutableCommPort::open().
| virtual void read | ( | std::string & | s | ) | [virtual] |
reads all available data from getReadStreambuf()
Definition at line 77 of file CommPort.h.
| virtual size_t read | ( | char * | buf, | |
| size_t | n | |||
| ) | [virtual] |
returns up to n bytes from the streambuf, returns the number read
Definition at line 72 of file CommPort.h.
| virtual void registerInstance | ( | ) | [protected, virtual] |
To be called be "deepest" subclass constructor at the end of construction.
Don't want to register until completed construction! plist::Collection listeners would be triggered and might start performing operations on instance while partially constructed
Definition at line 108 of file CommPort.h.
| virtual void releaseResource | ( | Data & | d | ) | [protected, virtual] |
| virtual void useResource | ( | Data & | d | ) | [protected, virtual] |
| virtual size_t write | ( | const std::string & | s | ) | [virtual] |
writes the string into getWriteStreambuf()
Definition at line 90 of file CommPort.h.
| virtual size_t write | ( | const char * | buf, | |
| size_t | n | |||
| ) | [virtual] |
writes up to n bytes from the streambuf, returns the number written
Definition at line 74 of file CommPort.h.
Member Data Documentation
const std::string instanceName [protected] |
holds the name of this instance of CommPort (mainly for error message reporting by the class itself)
ensures that serialized access is maintained (assuming clients use the lock...)
Definition at line 128 of file CommPort.h.
Referenced by FileSystemCommPort::connectionError(), and NetworkCommPort::doOpen().
Thread::Lock lock [protected] |
Often devices have either half-duplex communication, or may give responses to command strings. It is important to get a lock across a query-response pair so that there is no risk of a second thread attempting a competing command or query.
Definition at line 134 of file CommPort.h.
Referenced by read(), and FileSystemCommPort::~FileSystemCommPort().
The documentation for this class was generated from the following file:
