Tekkotsu Homepage | Demos | Overview | Downloads | Dev. Resources | Reference | Credits |
CommPort Class Reference#include <CommPort.h>
Inheritance diagram for CommPort:
![]() Detailed DescriptionA 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:
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. ThreadNS::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.
Member Typedef Documentation
the streambuf which does the actual work should inherit from basic_streambuf, using the system's default character type
Definition at line 68 of file CommPort.h.
short hand for the instance tracker, which allows dynamic reconfiguration of CommPort instances
Definition at line 146 of file CommPort.h.
Constructor & Destructor Documentation
destructor, removes from registry in case we're deleting it from some other source than registry's own destroy()
Definition at line 65 of file CommPort.h.
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 152 of file CommPort.h.
Member Function Documentation
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. Referenced by registerInstance().
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 79 of file CommPort.h. Referenced by NetworkCommPort::close(), CreateDriver::connect(), SSC32Driver::getData(), CreateDriver::getData(), SSC32Driver::motionCheck(), DynamixelDriver::motionCheck(), CreateDriver::motionCheck(), and NetworkCommPort::plistValueChanged().
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.
Implemented in ExecutableCommPort, FileSystemCommPort, NetworkCommPort, RedirectionCommPort, and SerialCommPort. Referenced by SSC32Driver::motionStarting(), DynamixelDriver::motionStarting(), CreateDriver::motionStarting(), SSC32Driver::plistValueChanged(), ImageStreamDriver::plistValueChanged(), DynamixelDriver::plistValueChanged(), CreateDriver::plistValueChanged(), SSC32Driver::setDataSourceThread(), ImageStreamDriver::setDataSourceThread(), and CreateDriver::setDataSourceThread().
Called when communication is complete, should handle recursive open/close calls.
Implemented in ExecutableCommPort, FileSystemCommPort, NetworkCommPort, RedirectionCommPort, and SerialCommPort. Referenced by SSC32Driver::motionStopping(), DynamixelDriver::motionStopping(), CreateDriver::motionStopping(), SSC32Driver::plistValueChanged(), ImageStreamDriver::plistValueChanged(), DynamixelDriver::plistValueChanged(), CreateDriver::plistValueChanged(), SSC32Driver::setDataSourceThread(), ImageStreamDriver::setDataSourceThread(), and CreateDriver::setDataSourceThread().
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 98 of file CommPort.h. Referenced by SSC32Driver::getData(), ImageStreamDriver::getData(), CreateDriver::getData(), RedirectionCommPort::isReadable(), SSC32Driver::nextTimestamp(), ImageStreamDriver::nextTimestamp(), and CreateDriver::nextTimestamp().
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 102 of file CommPort.h. Referenced by SSC32Driver::getData(), CreateDriver::getData(), RedirectionCommPort::isWriteable(), SSC32Driver::motionCheck(), DynamixelDriver::motionCheck(), CreateDriver::motionCheck(), and DynamixelDriver::motionStarting().
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::getData(), ImageStreamDriver::getData(), CreateDriver::getData(), RedirectionCommPort::getReadStreambuf(), and read().
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 CreateDriver::connect(), SSC32Driver::getData(), CreateDriver::getData(), RedirectionCommPort::getWriteStreambuf(), SSC32Driver::motionCheck(), DynamixelDriver::motionCheck(), CreateDriver::motionCheck(), DynamixelDriver::motionStarting(), and write().
returns up to n bytes from the streambuf, returns the number read
Definition at line 125 of file CommPort.h. Referenced by read().
writes up to n bytes from the streambuf, returns the number written
Definition at line 127 of file CommPort.h. Referenced by write().
registry from which current instances can be discovered and new instances allocated based on their class names
Definition at line 148 of file CommPort.h. Referenced by Simulator::cmdDelete(), CreateDriver::connect(), SSC32Driver::getData(), ImageStreamDriver::getData(), CreateDriver::getData(), RedirectionCommPort::getInputCP(), RedirectionCommPort::getOutputCP(), SSC32Driver::motionCheck(), DynamixelDriver::motionCheck(), CreateDriver::motionCheck(), SSC32Driver::motionStarting(), DynamixelDriver::motionStarting(), CreateDriver::motionStarting(), SSC32Driver::motionStopping(), DynamixelDriver::motionStopping(), CreateDriver::motionStopping(), SSC32Driver::nextTimestamp(), ImageStreamDriver::nextTimestamp(), CreateDriver::nextTimestamp(), SSC32Driver::plistValueChanged(), ImageStreamDriver::plistValueChanged(), DynamixelDriver::plistValueChanged(), CreateDriver::plistValueChanged(), registerInstance(), SSC32Driver::setDataSourceThread(), ImageStreamDriver::setDataSourceThread(), CreateDriver::setDataSourceThread(), Simulator::Simulator(), ~CommPort(), and Simulator::~Simulator().
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 161 of file CommPort.h.
Member Data Documentation
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 178 of file CommPort.h. Referenced by NetworkCommPort::doOpen(), registerInstance(), and ~CommPort().
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 184 of file CommPort.h. Referenced by getLock(), releaseResource(), and useResource().
The documentation for this class was generated from the following file: |
Tekkotsu Hardware Abstraction Layer 4.0 |
Generated Thu Nov 22 01:01:19 2007 by Doxygen 1.5.4 |