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

#include <driver.h>

Inherits Driver.

Inherited by Accel_Calib, Acr120u, Acts, AdaptiveMCL, AioToSonar, Alsa, AmtecM5, AmtecPowerCube, Bumper2Laser, Camera1394, CameraCompress, Camerareq, CameraUncompress, CameraUvc, CameraV4L, CameraV4L2, CamFilter, canonvcc4, ClodBuster, Cmucam2, CMVisionBF, Create, CvCam, DeadStop, Differential, DioCmd, DioDelay, Dummy, EEDHController, Ekfvloc, EpuckDriver, ER, FakeLocalize, Festival, Flexiport, FlockOfBirds_Device, GarciaDriver, GarminNMEA, GbxGarminAcfr, GbxSickAcfr, GenericXBow, gridmap, GripCmd, GStreamerDriver, Hemisson, HokuyoDriver, ImageBase, ImageSeq, ImgCmp, ImgSave, InertiaCube2, InsideM300, Iwspy, KartoLogger, Khepera, KinectDriver, LaserFeature, Libv4l2, LinuxJoystick, mbicp, Mica2, MicroStrain3DMG, MotionMind, MrIcp, ND, NomadDriver, Nxt, Obot, OceanServer, OpaqueCmd, P2OS, PBSDriver, PhidgetAcc, PhidgetIFK, Phidgetrfid, PlayerNIMU, PortIO, Powershot, PTU46_Device, RazorIMU, RCore_XBridge, ReadLog, REB, RFLEX, roboteq, RobotinoDriver, Roomba, RS4LeuzeLaserDriver, rt3xxx, Searchpattern, SegwayRMP, SegwayRMP400, SerialStream, SerIO, sickLDMRS, SickLMS200, SickLMS400, SickNAV200, SickRFI341, SickS3000, SkyetekM1, snd, SonyEVID30, SpeechCmd, SphereDriver, SpherePTZ, Sphinx2, SR3000, SrvAdv_MDNS, StatGrabDriver, STOC, SWISSRANGER, TCPStream, UniCap_Image, Vec2Map, VelCmd, VFH_Class, VideoCanny, Wavefront, wbr914, WlanScan, WriteLog, XSensMT, and Yarp_Image.

Collaboration diagram for ThreadedDriver:

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.

Public Member Functions
	ThreadedDriver (ConfigFile *cf, int section, bool overwrite_cmds, size_t queue_maxlen, int interface_)
	Constructor with implicit interface. More...

	ThreadedDriver (ConfigFile *cf, int section, bool overwrite_cmds=true, size_t queue_maxlen=PLAYER_MSGQUEUE_DEFAULT_MAXLEN)
	Constructor for multiple-interface drivers. More...

virtual	~ThreadedDriver ()
	Destructor.

virtual int	Setup ()
	Initialize the driver. More...

virtual int	Shutdown ()
	Finalize the driver. More...

virtual int	Terminate ()
	Terminate the driver. More...

virtual void	Main (void)=0
	Main method for driver thread. More...

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

bool	Wait (double TimeOut=0.0)
	Wait for new data to arrive on the driver's queue. More...

virtual void	Update ()
	Update non-threaded drivers. More...

Public Member Functions inherited from Driver
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. More...

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

virtual void	Publish (QueuePointer &queue, player_msghdr_t hdr, void src, bool copy=true)
	Publish a message via one of this driver's interfaces. More...

virtual void	Publish (player_msghdr_t hdr, void src, bool copy=true)
	Publish a message via one of this driver's interfaces. More...

	Driver (ConfigFile *cf, int section, bool overwrite_cmds, size_t queue_maxlen, int interf)
	Constructor for single-interface drivers. More...

	Driver (ConfigFile *cf, int section, bool overwrite_cmds=true, size_t queue_maxlen=PLAYER_MSGQUEUE_DEFAULT_MAXLEN)
	Constructor for multiple-interface drivers. More...

virtual	~Driver ()
	Destructor.

int	GetError ()
	Get last error value. More...

virtual int	Subscribe (player_devaddr_t addr)
	Subscribe to this driver. More...

virtual int	Subscribe (QueuePointer &, player_devaddr_t)
	Subscribe to this driver. More...

virtual int	Unsubscribe (player_devaddr_t addr)
	Unsubscribe from this driver. More...

virtual int	Unsubscribe (QueuePointer &, player_devaddr_t)
	Unsubscribe from this driver. More...

void	ProcessMessages (int maxmsgs)
	Process pending messages. More...

void	ProcessMessages (void)
	Process pending messages. More...

virtual int	ProcessMessage (QueuePointer &resp_queue, player_msghdr hdr, void data)
	Message handler. More...

virtual int	ProcessInternalMessages (QueuePointer &resp_queue, player_msghdr hdr, void data)
	Internal message handler. More...

virtual bool	RegisterProperty (const char key, Property property, ConfigFile *cf, int section)
	Property registration. More...

virtual bool	RegisterProperty (Property property, ConfigFile cf, int section)
	Property registration. More...

Protected Member Functions
virtual void	StartThread (void)

virtual void	StopThread (void)
	Cancel (and wait for termination) of the driver thread. More...

void	TestCancel ()
	enable thread cancellation and test for cancellation More...

Protected Member Functions inherited from Driver
int	AddInterface (player_devaddr_t addr)
	Add an interface. More...

int	AddInterface (player_devaddr_t addr, ConfigFile cf, int section, int code, const char *key=NULL)
	Add an interface. More...

void	SetError (int code)
	Set/reset error code.

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

virtual void	Unlock (void)
	Unlock access to driver internals. More...

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

Static Protected Member Functions
static void *	DummyMain (void *driver)
	Dummy main (just calls real main). More...

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

Private Attributes
pthread_t	driverthread
	The driver's thread. More...

player_thread_state_t	ThreadState
	TODO: insert state machine here.

bool	SetupSuccessful

PlayerBarrier	SetupBarrier
	Barrier to synchronise threads on setup.

Additional Inherited Members
Public Attributes inherited from Driver
QueuePointer	ret_queue
	Last requester's queue. More...

player_devaddr_t	device_addr
	Default device address (single-interface drivers)

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

bool	alwayson
	Always on flag. More...

QueuePointer	InQueue
	Queue for all incoming messages for this driver.

Constructor & Destructor Documentation

◆ ThreadedDriver() [1/2]

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

Constructor with implicit interface.

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?
interface_	The interface that you want this driver to provide

Referenced by Khepera::ProcessMessage(), and RFLEX::ProcessMessage().

◆ ThreadedDriver() [2/2]

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

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

◆ DummyMain()

static void* ThreadedDriver::DummyMain ( void * driver )

staticprotected

Dummy main (just calls real main).

This is used to simplify thread creation.

◆ DummyMainQuit()

static void ThreadedDriver::DummyMainQuit ( void * driver )

staticprotected

Dummy main cleanup (just calls real main cleanup).

This is used to simplify thread termination.

◆ Main()

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 P2OS, ClodBuster, wbr914, Alsa, RFLEX, SegwayRMP, AdaptiveMCL, ER, REB, Khepera, SegwayRMP400, ImageBase, EpuckDriver, snd, SphereDriver, GarciaDriver, CameraUvc, and StatGrabDriver.

◆ MainQuit()

virtual void ThreadedDriver::MainQuit ( void )

inlinevirtual

Cleanup method for driver thread (called when main exits)

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

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

References Driver::Wait().

Here is the call graph for this function:

◆ Setup()

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

◆ Shutdown()

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

◆ StopThread()

virtual void ThreadedDriver::StopThread ( void )

protectedvirtual

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

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

◆ Terminate()

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.

◆ TestCancel()

void ThreadedDriver::TestCancel ( )

protectedvirtual

enable thread cancellation and test for cancellation

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

Reimplemented from Driver.

◆ Update()

virtual void ThreadedDriver::Update ( void )

inlinevirtual

Update non-threaded drivers.

Reimplemented from Driver.

◆ Wait()

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 RFLEX::Main().

Member Data Documentation

◆ driverthread

pthread_t ThreadedDriver::driverthread

private

The driver's thread.

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

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

driver.h

Detailed Description

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ ThreadedDriver() [1/2]

◆ ThreadedDriver() [2/2]

Member Function Documentation

◆ DummyMain()

◆ DummyMainQuit()

◆ Main()

◆ MainQuit()

◆ Setup()

◆ Shutdown()

◆ StopThread()

◆ Terminate()

◆ TestCancel()

◆ Update()

◆ Wait()

Member Data Documentation

◆ driverthread