Driver Class Reference

#include <driver.h>

Inheritance diagram for Driver:

Inheritance graph
[legend]
Collaboration diagram for Driver:

Collaboration graph
[legend]
List of all members.

Detailed Description

Base class for all drivers.

This class manages driver subscriptions, threads, and data marshalling to/from device interfaces. All drivers inherit from this class, and most will overload the Setup(), Shutdown() and Main() methods.

Definition at line 97 of file driver.h.


Public Member Functions

virtual void Lock (void)
 Lock access to driver internals.
virtual void Unlock (void)
 Unlock access to driver internals.
virtual void Publish (player_devaddr_t addr, QueuePointer &queue, uint8_t type, uint8_t subtype, void *src=NULL, size_t deprecated=0, double *timestamp=NULL, bool copy=true)
 Publish a message via one of this driver's interfaces.
virtual void Publish (player_devaddr_t addr, uint8_t type, uint8_t subtype, void *src=NULL, size_t deprecated=0, double *timestamp=NULL, bool copy=true)
 Publish a message via one of this driver's interfaces.
virtual void Publish (QueuePointer &queue, player_msghdr_t *hdr, void *src, bool copy=true)
 Publish a message via one of this driver's interfaces.
virtual void Publish (player_msghdr_t *hdr, void *src, bool copy=true)
 Publish a message via one of this driver's interfaces.
 Driver (ConfigFile *cf, int section, bool overwrite_cmds, size_t queue_maxlen, int interf)
 Constructor for single-interface drivers.
 Driver (ConfigFile *cf, int section, bool overwrite_cmds=true, size_t queue_maxlen=PLAYER_MSGQUEUE_DEFAULT_MAXLEN)
 Constructor for multiple-interface drivers.
virtual ~Driver ()
 Destructor.
int GetError ()
 Get last error value.
virtual int Subscribe (player_devaddr_t addr)
 Subscribe to this driver.
virtual int Subscribe (QueuePointer &queue, player_devaddr_t addr)
 Subscribe to this driver.
virtual int Unsubscribe (player_devaddr_t addr)
 Unsubscribe from this driver.
virtual int Unsubscribe (QueuePointer &queue, player_devaddr_t addr)
 Unsubscribe from this driver.
virtual int Setup ()=0
 Initialize the driver.
virtual int Shutdown ()=0
 Finalize the driver.
virtual void Main (void)
 Main method for driver thread.
virtual void MainQuit (void)
 Cleanup method for driver thread (called when main exits).
void ProcessMessages (int maxmsgs)
 Process pending messages.
void ProcessMessages (void)
 Process pending messages.
virtual int ProcessMessage (QueuePointer &resp_queue, player_msghdr *hdr, void *data)
 Message handler.
virtual void Update ()
 Update non-threaded drivers.
virtual int ProcessInternalMessages (QueuePointer &resp_queue, player_msghdr *hdr, void *data)
 Internal message handler.
virtual bool RegisterProperty (const char *key, Property *prop, ConfigFile *cf, int section)
 Property registration.
virtual bool RegisterProperty (Property *prop, ConfigFile *cf, int section)
 Property registration.

Public Attributes

pthread_t driverthread
 The driver's thread.
QueuePointer ret_queue
 Last requester's queue.
player_devaddr_t device_addr
 Default device address (single-interface drivers).
int subscriptions
 Number of subscriptions to this driver.
int entries
 Total number of entries in the device table using this driver.
bool alwayson
 Always on flag.
QueuePointer InQueue
 Queue for all incoming messages for this driver.

Protected Member Functions

virtual void StartThread (void)
virtual void StopThread (void)
 Cancel (and wait for termination) of the driver thread.
int AddInterface (player_devaddr_t addr)
 Add an interface.
int AddInterface (player_devaddr_t *addr, ConfigFile *cf, int section, int code, char *key=NULL)
 Add an interface.
void SetError (int code)
 Set/reset error code.
bool Wait (double TimeOut=0.0)
 Wait for new data to arrive on the driver's queue.
int AddFileWatch (int fd, bool ReadWatch=true, bool WriteWatch=false, bool ExceptWatch=true)
 Wake up the driver if the specified event occurs on the file descriptor.
int RemoveFileWatch (int fd, bool ReadWatch=true, bool WriteWatch=false, bool ExceptWatch=true)
 Remove a previously added watch, call with the same arguments as when adding the watch.

Static Protected Member Functions

static void * DummyMain (void *driver)
 Dummy main (just calls real main).
static void DummyMainQuit (void *driver)
 Dummy main cleanup (just calls real main cleanup).

Private Attributes

pthread_mutex_t accessMutex
 Mutex used to lock access, via Lock() and Unlock(), to driver internals, like the list of subscribed queues.
int error
PropertyBag propertyBag

Constructor & Destructor Documentation

Driver::Driver ( ConfigFile *  cf,
int  section,
bool  overwrite_cmds,
size_t  queue_maxlen,
int  interf 
)

Constructor for single-interface drivers.

Parameters:
cf Current configuration file
section Current section in configuration file
overwrite_cmds Do new commands overwrite old ones?
queue_maxlen How long can the incoming queue grow?
interf Player interface code; e.g., PLAYER_POSITION2D_CODE

Driver::Driver ( ConfigFile *  cf,
int  section,
bool  overwrite_cmds = true,
size_t  queue_maxlen = PLAYER_MSGQUEUE_DEFAULT_MAXLEN 
)

Constructor for multiple-interface drivers.

Use AddInterface() to specify individual interfaces.

Parameters:
cf Current configuration file
section Current section in configuration file
overwrite_cmds Do new commands overwrite old ones?
queue_maxlen How long can the incoming queue grow?

Member Function Documentation

virtual void Driver::StopThread ( void   )  [protected, virtual]

Cancel (and wait for termination) of the driver thread.

This method is usually called from the overloaded Shutdown() method to terminate the driver thread.

Reimplemented in RFLEX.

Referenced by wbr914::Shutdown(), StatGrabDriver::Shutdown(), SphereDriver::Shutdown(), SegwayRMP::Shutdown(), REB::Shutdown(), P2OS::Shutdown(), Khepera::Shutdown(), ImageBase::Shutdown(), GarciaDriver::Shutdown(), ER::Shutdown(), ClodBuster::Shutdown(), CameraUvc::Shutdown(), AdaptiveMCL::Shutdown(), Alsa::Shutdown(), and Erratic::StopThreads().

static void* Driver::DummyMain ( void *  driver  )  [static, protected]

Dummy main (just calls real main).

This is used to simplify thread creation.

Referenced by RFLEX::StartThread().

static void Driver::DummyMainQuit ( void *  driver  )  [static, protected]

Dummy main cleanup (just calls real main cleanup).

This is used to simplify thread termination.

int Driver::AddInterface ( player_devaddr_t  addr  )  [protected]

Add an interface.

Parameters:
addr Player device address.
Returns:
0 on success, non-zero otherwise.

Referenced by GarciaDriver::GarciaDriver(), and SphereDriver::SphereDriver().

int Driver::AddInterface ( player_devaddr_t *  addr,
ConfigFile *  cf,
int  section,
int  code,
char *  key = NULL 
) [protected]

Add an interface.

This form loads the address details from the config file and then adds the interface.

Parameters:
addr Pointer to Player device address, this is filled in with the address details.
Returns:
0 on success, non-zero otherwise.

bool Driver::Wait ( double  TimeOut = 0.0  )  [inline, protected]

Wait for new data to arrive on the driver's queue.

Call this method to block until a new message arrives on Driver::InQueue. This method will return true immediately if at least one message is already waiting.

If TimeOut is set to a positive value this method will return false if the timeout occurs before and update is recieved.

Definition at line 161 of file driver.h.

References InQueue.

virtual void Driver::Publish ( player_devaddr_t  addr,
QueuePointer &  queue,
uint8_t  type,
uint8_t  subtype,
void *  src = NULL,
size_t  deprecated = 0,
double *  timestamp = NULL,
bool  copy = true 
) [virtual]

Publish a message via one of this driver's interfaces.

This form of Publish will assemble the message header for you.

Parameters:
addr The origin address
queue If non-NULL, the target queue; if NULL, then the message is sent to all interested parties.
type The message type
subtype The message subtype
src The message body
deprecated Used to be the length of the message this is now calculated
timestamp Timestamp for the message body (if NULL, then the current time will be filled in)
copy if set to false the data will be claimed and the caller should no longer use or free it

Referenced by P2OS::ActarrayPutData(), P2OS::BlobfinderPutData(), P2OS::GyroPutData(), wbr914::HandleConfig(), P2OS::HandleConfig(), Erratic::HandleConfig(), Alsa::HandleMixerChannelLevelReq(), Alsa::HandleMixerChannelListReq(), SegwayRMP::HandlePosition3DConfig(), SegwayRMP::HandlePositionConfig(), Alsa::HandleSampleLoadReq(), Alsa::HandleSampleRecordReq(), Alsa::HandleSampleRetrieveReq(), SegwayRMP::Main(), RFLEX::Main(), ER::Main(), ClodBuster::Main(), CameraUvc::Main(), AdaptiveMCL::ProcessGeom(), GarciaDriver::ProcessIrPoseReq(), ToRanger::ProcessMessage(), SphereDriver::ProcessMessage(), RFLEX::ProcessMessage(), MapTransform::ProcessMessage(), LaserTransform::ProcessMessage(), Khepera::ProcessMessage(), ER::ProcessMessage(), ClodBuster::ProcessMessage(), AdaptiveMCL::ProcessMessage(), GarciaDriver::ProcessPos2dGeomReq(), Erratic::PublishAIn(), wbr914::PublishData(), Erratic::PublishIR(), Alsa::PublishMixerData(), Erratic::PublishPosition2D(), Erratic::PublishPower(), Alsa::PublishRecordedData(), Erratic::PublishSonar(), AdaptiveMCL::PutDataLocalize(), AdaptiveMCL::PutDataPosition(), StatGrabDriver::RefreshData(), SphereDriver::RefreshData(), GarciaDriver::RefreshData(), Khepera::ResetOdometry(), Alsa::SendStateMessage(), P2OS::StandardSIPPutData(), and Khepera::UpdateData().

virtual void Driver::Publish ( player_devaddr_t  addr,
uint8_t  type,
uint8_t  subtype,
void *  src = NULL,
size_t  deprecated = 0,
double *  timestamp = NULL,
bool  copy = true 
) [virtual]

Publish a message via one of this driver's interfaces.

This form of Publish will assemble the message header for you. The message is broadcast to all interested parties

Parameters:
addr The origin address
type The message type
subtype The message subtype
src The message body
deprecated Used to be the length of the message this is now calculated
timestamp Timestamp for the message body (if NULL, then the current time will be filled in)
copy if set to false the data will be claimed and the caller should no longer use or free it

virtual void Driver::Publish ( QueuePointer &  queue,
player_msghdr_t *  hdr,
void *  src,
bool  copy = true 
) [virtual]

Publish a message via one of this driver's interfaces.

Use this form of Publish if you already have the message header assembled and have a target queue to send to.

Parameters:
queue the target queue.
hdr The message header
src The message body
copy if set to false the data will be claimed and the caller should no longer use or free it

virtual void Driver::Publish ( player_msghdr_t *  hdr,
void *  src,
bool  copy = true 
) [virtual]

Publish a message via one of this driver's interfaces.

Use this form of Publish if you already have the message header assembled and wish to broadcast the message to all subscribed parties.

Parameters:
hdr The message header
src The message body
copy if set to false the data will be claimed and the caller should no longer use or free it

int Driver::GetError (  )  [inline]

Get last error value.

Call this after the constructor to check whether anything went wrong.

Definition at line 311 of file driver.h.

virtual int Driver::Subscribe ( player_devaddr_t  addr  )  [virtual]

Subscribe to this driver.

The Subscribe() and Unsubscribe() methods are used to control subscriptions to the driver; a driver MAY override them, but usually won't.

Parameters:
addr Address of the device to subscribe to (the driver may have more than one interface).
Returns:
Returns 0 on success.

Reimplemented in Erratic, Khepera, P2OS, RFLEX, and wbr914.

Referenced by wbr914::Subscribe(), RFLEX::Subscribe(), REB::Subscribe(), P2OS::Subscribe(), Khepera::Subscribe(), and Erratic::Subscribe().

virtual int Driver::Subscribe ( QueuePointer &  queue,
player_devaddr_t  addr 
) [inline, virtual]

Subscribe to this driver.

The Subscribe() and Unsubscribe() methods are used to control subscriptions to the driver; a driver MAY override them, but usually won't. This alternative form includes the clients queue so you can map future requests and unsubscriptions to a specific queue.

If this methods returns a value other than 1 then the other form of subscribe wont be called

Parameters:
queue The queue of the subscribing client
addr Address of the device to subscribe to (the driver may have more than one interface).
Returns:
Returns 0 on success, -ve on error and 1 for unimplemented.

Definition at line 337 of file driver.h.

virtual int Driver::Unsubscribe ( player_devaddr_t  addr  )  [virtual]

Unsubscribe from this driver.

The Subscribe() and Unsubscribe() methods are used to control subscriptions to the driver; a driver MAY override them, but usually won't.

Parameters:
addr Address of the device to unsubscribe from (the driver may have more than one interface).
Returns:
Returns 0 on success.

Reimplemented in Erratic, Khepera, P2OS, RFLEX, and wbr914.

Referenced by AMCLImu::Shutdown(), AMCLGps::Shutdown(), wbr914::Unsubscribe(), RFLEX::Unsubscribe(), REB::Unsubscribe(), P2OS::Unsubscribe(), Khepera::Unsubscribe(), and Erratic::Unsubscribe().

virtual int Driver::Unsubscribe ( QueuePointer &  queue,
player_devaddr_t  addr 
) [inline, virtual]

Unsubscribe from this driver.

The Subscribe() and Unsubscribe() methods are used to control subscriptions to the driver; a driver MAY override them, but usually won't.This alternative form includes the clients queue so you can map future requests and unsubscriptions to a specific queue.

If this methods returns a value other than 1 then the other form of subscribe wont be called

Parameters:
queue The queue of the subscribing client
addr Address of the device to unsubscribe from (the driver may have more than one interface).
Returns:
Returns 0 on success.

Definition at line 363 of file driver.h.

virtual int Driver::Setup (  )  [pure virtual]

Initialize the driver.

This function is called with the first client subscribes; it MUST be implemented by the driver.

Returns:
Returns 0 on success.

Implemented in Alsa, ImageBase, SphereDriver, CameraUvc, StatGrabDriver, LaserTransform, AdaptiveMCL, MapTransform, LifoMCom, ClodBuster, Erratic, ER, GarciaDriver, Khepera, P2OS, REB, RFLEX, SegwayRMP, wbr914, and ToRanger.

virtual int Driver::Shutdown (  )  [pure virtual]

Finalize the driver.

This function is called with the last client unsubscribes; it MUST be implemented by the driver.

Returns:
Returns 0 on success.

Implemented in Alsa, ImageBase, SphereDriver, CameraUvc, StatGrabDriver, LaserTransform, AdaptiveMCL, MapTransform, LifoMCom, ClodBuster, Erratic, ER, GarciaDriver, Khepera, P2OS, REB, RFLEX, SegwayRMP, wbr914, and ToRanger.

virtual void Driver::Main ( void   )  [virtual]

Main method for driver thread.

drivers have their own thread of execution, created using StartThread(); this is the entry point for the driver thread, and must be overloaded by all threaded drivers.

Reimplemented in Alsa, ImageBase, SphereDriver, CameraUvc, StatGrabDriver, AdaptiveMCL, ClodBuster, Erratic, ER, GarciaDriver, Khepera, P2OS, REB, RFLEX, SegwayRMP, and wbr914.

virtual void Driver::MainQuit ( void   )  [virtual]

Cleanup method for driver thread (called when main exits).

Overload this method and to do additional cleanup when the driver thread exits.

Reimplemented in AdaptiveMCL.

void Driver::ProcessMessages ( int  maxmsgs  ) 

Process pending messages.

Call this to automatically process messages using registered handler, Driver::ProcessMessage.

Parameters:
maxmsgs The maximum number of messages to process. If -1, then process until the queue is empty (this may result in an infinite loop if messages are being added to the queue faster than they are processed). If 0, then check the current length and process up to that many messages. If > 0, process up to the indicated number of messages.

Referenced by Nav200::ReadFromNav200(), and Nav200::WriteCommand().

void Driver::ProcessMessages ( void   ) 

Process pending messages.

Equivalent to ProcessMessages(0).

Referenced by wbr914::Main(), StatGrabDriver::Main(), SphereDriver::Main(), SegwayRMP::Main(), RFLEX::Main(), REB::Main(), P2OS::Main(), Khepera::Main(), ImageBase::Main(), GarciaDriver::Main(), Erratic::Main(), ER::Main(), ClodBuster::Main(), CameraUvc::Main(), AdaptiveMCL::Main(), Alsa::Main(), Update(), and AdaptiveMCL::UpdateFilter().

virtual int Driver::ProcessMessage ( QueuePointer &  resp_queue,
player_msghdr *  hdr,
void *  data 
) [virtual]

Message handler.

This function is called once for each message in the incoming queue. Reimplement it to provide message handling. Return 0 if you handled the message and -1 otherwise

Parameters:
resp_queue The queue to which any response should go.
hdr The message header
data The message body

Reimplemented in Alsa, ImageBase, SphereDriver, CameraUvc, LaserTransform, AdaptiveMCL, MapTransform, ClodBuster, Erratic, ER, GarciaDriver, Khepera, P2OS, RFLEX, SegwayRMP, wbr914, and ToRanger.

virtual int Driver::ProcessInternalMessages ( QueuePointer &  resp_queue,
player_msghdr *  hdr,
void *  data 
) [virtual]

Internal message handler.

This function handles messages internal to the driver's operation.

Parameters:
resp_queue The queue to which any response should go.
hdr The message header
data The message body

virtual bool Driver::RegisterProperty ( const char *  key,
Property *  prop,
ConfigFile *  cf,
int  section 
) [virtual]

Property registration.

Parameters:
key Property key
property Pointer to a Property object - must exist for as long as the property bag does
cf Configuration file
section Configuration file section that may define the property value
Returns:
True if the property was registered, false otherwise

virtual bool Driver::RegisterProperty ( Property *  prop,
ConfigFile *  cf,
int  section 
) [virtual]

Property registration.

Simplified form that uses the key already in the property

Parameters:
property Pointer to a Property object - must exist for as long as the property bag does
cf Configuration file
section Configuration file section that may define the property value
Returns:
True if the property was registered, false otherwise

Member Data Documentation

pthread_t Driver::driverthread

The driver's thread.

The driver's thread, when managed by StartThread() and StopThread().

Definition at line 175 of file driver.h.

Referenced by RFLEX::StartThread(), and RFLEX::StopThread().

QueuePointer Driver::ret_queue

Last requester's queue.

Pointer to a queue to which this driver owes a reply. Used mainly by non-threaded drivers to cache the return address for requests that get forwarded to other devices.

Definition at line 186 of file driver.h.

Referenced by ToRanger::ProcessMessage(), and LaserTransform::ProcessMessage().

int Driver::entries

Total number of entries in the device table using this driver.

This is updated and read by the Device class.

Definition at line 267 of file driver.h.

bool Driver::alwayson

Always on flag.

If true, driver should be "always on", i.e., player will "subscribe" at startup, before any clients subscribe. The "alwayson" parameter in the config file can be used to turn this feature on as well (in which case this flag will be set to reflect that setting).

Definition at line 276 of file driver.h.

The documentation for this class was generated from the following file:
Last updated 12 September 2005 21:38:45