ThreadedDriver Class Reference

Base class for drivers which oeprate with a thread. More...

#include <driver.h>

Inheritance diagram for ThreadedDriver:
Driver AdaptiveMCL Alsa CameraUvc ClodBuster ER GarciaDriver ImageBase Khepera P2OS REB RFLEX SegwayRMP SegwayRMP400 snd SphereDriver StatGrabDriver wbr914

List of all members.

Public Member Functions

 ThreadedDriver (ConfigFile *cf, int section, bool overwrite_cmds, size_t queue_maxlen, int interf)
 Constructor with implicit interface.
 ThreadedDriver (ConfigFile *cf, int section, bool overwrite_cmds=true, size_t queue_maxlen=PLAYER_MSGQUEUE_DEFAULT_MAXLEN)
 Constructor for multiple-interface drivers.
virtual ~ThreadedDriver ()
 Destructor.
virtual int Setup ()
 Initialize the driver.
virtual int Shutdown ()
 Finalize the driver.
virtual int Terminate ()
 Terminate the driver.
virtual void Main (void)=0
 Main method for driver thread.
virtual int MainSetup (void)
 Sets up the resources needed by the driver thread.
virtual void MainQuit (void)
 Cleanup method for driver thread (called when main exits)
bool Wait (double TimeOut=0.0)
 Wait for new data to arrive on the driver's queue.
virtual void Update ()
 Update non-threaded drivers.

Protected Member Functions

virtual void StartThread (void)
virtual void StopThread (void)
 Cancel (and wait for termination) of the driver thread.
void TestCancel ()
 enable thread cancellation and test for cancellation

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_t driverthread
 The driver's thread.
player_thread_state_t ThreadState
 TODO: insert state machine here
bool SetupSuccessful
PlayerBarrier SetupBarrier
 Barrier to synchronise threads on setup.

Detailed Description

Base class for drivers which oeprate with a thread.

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

The ThreadedDriver uses a fairly simple thread model with the only complications coming from the deferred cancellation.

The default setup method simply calls StartThread and likewise the default Shutdown method calls StopThread. Resources for the driver should be allocated in MainSetup and cleaned up in MainQuit, these two methods will be called in the driver thread before and after the main method respectively.

When StopThread is called it will request the driver thread to be cancelled, this cancellation will be deffered until one of three cancellation points, ProcessMessages, Wait or TestCancel. In this way the driver has control over when the thread is cancelled.

If a new subscription arrives before the thread has terminated then upon completion of the MainQuit method the thread will be relaunched and MainSetup run. In this way it is gaurunteed that there is only ever one thread running for the driver and that Main is always proceeded by MainSetup and followed by MainQuit before any new threads are launched.

To manage the thread lifetime a small state machine is implemented, containing four states: STOPPED, RUNNING, STOPPING and RESTARTING. Initially the thread is in STOPPED state.

From the STOPPED state the only valid transition is to RUNNING, this is triggered by a call to StartThread.

From the RUNNING state the driver can transition to STOPPING, triggered by a call to StopThread.

In the STOPPING state the driver can transition to STOPPED, triggered by MainQuit running, or to RESTARTING on a call to StartThread.

From RESTARTING the driver can transition to RUNNING once MainQuit has run and the new thread is started, or to STOPPING if StopThread is called before the original thread terminates.


Constructor & Destructor Documentation

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

Constructor with implicit interface.

Parameters:
cfCurrent configuration file
sectionCurrent section in configuration file
overwrite_cmdsDo new commands overwrite old ones?
queue_maxlenHow long can the incoming queue grow?
interfaceThe interface that you want this driver to provide
ThreadedDriver::ThreadedDriver ( 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

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

Dummy main (just calls real main).

This is used to simplify thread creation.

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

Dummy main cleanup (just calls real main cleanup).

This is used to simplify thread termination.

virtual void ThreadedDriver::Main ( void  ) [pure 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.

Implemented in Alsa, ImageBase, SphereDriver, CameraUvc, StatGrabDriver, AdaptiveMCL, ClodBuster, ER, GarciaDriver, Khepera, P2OS, REB, RFLEX, SegwayRMP, wbr914, SegwayRMP400, and snd.

virtual void ThreadedDriver::MainQuit ( void  ) [inline, 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 Alsa, ImageBase, SphereDriver, CameraUvc, AdaptiveMCL, ClodBuster, ER, GarciaDriver, Khepera, P2OS, REB, RFLEX, SegwayRMP, wbr914, and SegwayRMP400.

virtual int ThreadedDriver::Setup ( ) [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 from Driver.

Reimplemented in snd.

Referenced by AdaptiveMCL::MainSetup().

virtual int ThreadedDriver::Shutdown ( ) [virtual]

Finalize the driver.

This function is called with the last client unsubscribes; the default version simple stops the driver thread if one is present. In this case resources should be cleaned up in MainQuit.

Returns:
Returns 0 on success.

Reimplemented from Driver.

Reimplemented in snd.

Referenced by AdaptiveMCL::MainQuit().

virtual void ThreadedDriver::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.

Referenced by snd::Shutdown().

virtual int ThreadedDriver::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 from Driver.

void ThreadedDriver::TestCancel ( ) [protected, virtual]

enable thread cancellation and test for cancellation

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

Reimplemented from Driver.

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

Update non-threaded drivers.

Reimplemented from Driver.

bool ThreadedDriver::Wait ( double  TimeOut = 0.0) [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 from Driver.

Referenced by snd::Main(), and RFLEX::Main().


Member Data Documentation

pthread_t ThreadedDriver::driverthread [private]

The driver's thread.

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

player_thread_state_t ThreadedDriver::ThreadState [private]

TODO: insert state machine here


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

Last updated 25 May 2011 21:17:00