Driver Class Reference

Base class for all drivers. More...

#include <driver.h>

Inheritance diagram for Driver:
Collaboration diagram for Driver:

List of all members.


Detailed Description

Base class for all drivers.

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

Public Member Functions

bool HasSubscriptions ()
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 Terminate ()
 Terminate the driver.
virtual int Setup ()
 Initialize the driver.
virtual int Shutdown ()
 Finalize the driver.
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 *property, ConfigFile *cf, int section)
 Property registration.
virtual bool RegisterProperty (Property *property, ConfigFile *cf, int section)
 Property registration.

Public Attributes

QueuePointer ret_queue
 Last requester's queue.
player_devaddr_t device_addr
 Default device address (single-interface drivers)
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

int AddInterface (player_devaddr_t addr)
 Add an interface.
int AddInterface (player_devaddr_t *addr, ConfigFile *cf, int section, int code, const char *key=NULL)
 Add an interface.
void SetError (int code)
 Set/reset error code.
virtual 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.
virtual void Lock (void)
 Lock access between the server and driver threads.
virtual void Unlock (void)
 Unlock access to driver internals.
virtual void SubscriptionLock (void)
 Lock to protect the subscription count for the driver.
virtual void SubscriptionUnlock (void)
 Unlock to protect the subscription count for the driver.
virtual void TestCancel ()
 enable thread cancellation and test for cancellation

Private Attributes

int error
PropertyBag propertyBag
int subscriptions
 Number of subscriptions to this driver.
pthread_mutex_t accessMutex
 Mutex used to lock access, via Lock() and Unlock(), to driver internals, like the list of subscribed queues.
pthread_mutex_t subscriptionMutex
 Mutex used to protect the subscription count for the driver.

Constructor & Destructor Documentation

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

Constructor for single-interface drivers.

Parameters:
cfCurrent configuration file
sectionCurrent section in configuration file
overwrite_cmdsDo new commands overwrite old ones?
queue_maxlenHow long can the incoming queue grow?
interfPlayer 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:
cfCurrent configuration file
sectionCurrent section in configuration file
overwrite_cmdsDo new commands overwrite old ones?
queue_maxlenHow long can the incoming queue grow?

Member Function Documentation

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

Add an interface.

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

Referenced by mbasedriver::mbasedriver(), SegwayRMP400::SegwayRMP400(), and SphereDriver::SphereDriver().

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

Add an interface.

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

Parameters:
addrPointer to Player device address, this is filled in with the address details.
cfCurrent configuration file
sectionCurrent section in configuration file
codeInterface code
keyConfiguration file key value
Returns:
0 on success, non-zero otherwise.
int Driver::GetError ( ) [inline]

Get last error value.

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

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

Lock access between the server and driver threads.

In particular used to procect the drivers thread pointer

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_queueThe queue to which any response should go.
hdrThe message header
dataThe message body
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_queueThe queue to which any response should go.
hdrThe message header
dataThe message body

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

void Driver::ProcessMessages ( int  maxmsgs)

Process pending messages.

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

Parameters:
maxmsgsThe 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.
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:
hdrThe message header
srcThe message body
copyif set to false the data will be claimed and the caller should no longer use or free it
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:
addrThe origin address
queueIf non-NULL, the target queue; if NULL, then the message is sent to all interested parties.
typeThe message type
subtypeThe message subtype
srcThe message body
deprecatedUsed to be the length of the message this is now calculated
timestampTimestamp for the message body (if NULL, then the current time will be filled in)
copyif set to false the data will be claimed and the caller should no longer use or free it

Referenced by mbasedriver::HandleConfig(), SegwayRMP::Main(), RFLEX::Main(), ER::Main(), EpuckDriver::Main(), CameraUvc::Main(), SegwayRMP400::ProcessData(), ToRanger::ProcessMessage(), SphereDriver::ProcessMessage(), snd::ProcessMessage(), SegwayRMP400::ProcessMessage(), RFLEX::ProcessMessage(), MapTransform::ProcessMessage(), LaserTransform::ProcessMessage(), Khepera::ProcessMessage(), FromRanger::ProcessMessage(), ER::ProcessMessage(), EpuckDriver::ProcessMessage(), AdaptiveMCL::ProcessMessage(), mbasedriver::PublishAIn(), mbasedriver::PublishIR(), mbasedriver::PublishPosition2D(), mbasedriver::PublishPower(), and mbasedriver::PublishSonar().

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:
addrThe origin address
typeThe message type
subtypeThe message subtype
srcThe message body
deprecatedUsed to be the length of the message this is now calculated
timestampTimestamp for the message body (if NULL, then the current time will be filled in)
copyif 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:
queuethe target queue.
hdrThe message header
srcThe message body
copyif set to false the data will be claimed and the caller should no longer use or free it
virtual bool Driver::RegisterProperty ( Property property,
ConfigFile cf,
int  section 
) [virtual]

Property registration.

Simplified form that uses the key already in the property

Parameters:
propertyPointer to a Property object - must exist for as long as the property bag does
cfConfiguration file
sectionConfiguration file section that may define the property value
Returns:
True if the property was registered, false otherwise
virtual bool Driver::RegisterProperty ( const char *  key,
Property property,
ConfigFile cf,
int  section 
) [virtual]

Property registration.

Parameters:
keyProperty key
propertyPointer to a Property object - must exist for as long as the property bag does
cfConfiguration file
sectionConfiguration file section that may define the property value
Returns:
True if the property was registered, false otherwise
virtual int Driver::Setup ( void  ) [inline, 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.

Reimplemented in ThreadedDriver, LaserTransform, MapTransform, Erratic, mbasedriver, snd, FromRanger, and ToRanger.

virtual int Driver::Shutdown ( void  ) [inline, virtual]

Finalize the driver.

This function is called with the last client unsubscribes.

Returns:
Returns 0 on success.

Reimplemented in ThreadedDriver, LaserTransform, MapTransform, Erratic, mbasedriver, snd, FromRanger, and ToRanger.

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:
addrAddress of the device to subscribe to (the driver may have more than one interface).
Returns:
Returns 0 on success.

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

Referenced by SegwayRMP400::MainSetup(), RFLEX::Subscribe(), P2OS::Subscribe(), mbasedriver::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:
queueThe queue of the subscribing client
addrAddress 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.
virtual void Driver::SubscriptionUnlock ( void  ) [protected, virtual]

Unlock to protect the subscription count for the driver.

virtual int Driver::Terminate ( ) [virtual]

Terminate the driver.

This method doesnt go through the niceities of unsubscribing etc, only use when the server is actually shutting down as it takes a few shortcuts

Returns:
Returns 0 on success.

Reimplemented in ThreadedDriver.

virtual void Driver::TestCancel ( ) [inline, protected, virtual]

enable thread cancellation and test for cancellation

This should only ever be called from the driver thread with *no* locks held

Reimplemented in ThreadedDriver.

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

Unlock access to driver internals.

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:
queueThe queue of the subscribing client
addrAddress of the device to unsubscribe from (the driver may have more than one interface).
Returns:
Returns 0 on success.
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:
addrAddress of the device to unsubscribe from (the driver may have more than one interface).
Returns:
Returns 0 on success.

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

Referenced by SegwayRMP400::MainQuit(), RFLEX::Unsubscribe(), P2OS::Unsubscribe(), mbasedriver::Unsubscribe(), Khepera::Unsubscribe(), and Erratic::Unsubscribe().

virtual void Driver::Update ( void  ) [inline, virtual]

Update non-threaded drivers.

Reimplemented in ThreadedDriver.

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

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.

Reimplemented in ThreadedDriver.


Member Data Documentation

pthread_mutex_t Driver::accessMutex [private]

Mutex used to lock access, via Lock() and Unlock(), to driver internals, like the list of subscribed queues.

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).

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

This is updated and read by the Device class.

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.

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

pthread_mutex_t Driver::subscriptionMutex [private]

Mutex used to protect the subscription count for the driver.

int Driver::subscriptions [private]

Number of subscriptions to this driver.


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