Base class for all drivers. More...

#include <driver.h>

Inheritance diagram for Driver:

Collaboration diagram for Driver:

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

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

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

virtual int	Shutdown ()
	Finalize the 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 void	Update ()
	Update non-threaded drivers. 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...

Public Attributes
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.

Protected Member Functions
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.

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

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

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

Private Attributes
int	error

PropertyBag	propertyBag

int	subscriptions
	Number of subscriptions to this driver. More...

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

pthread_mutex_t	subscriptionMutex
	Mutex used to protect the subscription count for the driver. More...

Constructor & Destructor Documentation

◆ Driver() [1/2]

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() [2/2]

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

◆ AddInterface() [1/2]

int Driver::AddInterface ( player_devaddr_t addr )

protected

Add an interface.

Parameters

addr	Player device address.

Returns: 0 on success, non-zero otherwise.

◆ AddInterface() [2/2]

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

addr	Pointer to Player device address, this is filled in with the address details.
cf	Current configuration file
section	Current section in configuration file
code	Interface code
key	Configuration file key value

Returns: 0 on success, non-zero otherwise.

◆ GetError()

int Driver::GetError ( )

inline

Get last error value.

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

◆ Lock()

virtual void Driver::Lock ( void )

protectedvirtual

Lock access between the server and driver threads.

In particular used to procect the drivers thread pointer

◆ ProcessInternalMessages()

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

◆ ProcessMessage()

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 P2OS, mbasedriver, Erratic, ClodBuster, wbr914, RFLEX, Khepera, ER, AdaptiveMCL, SegwayRMP400, Alsa, ImageBase, MapTransform, LaserTransform, EpuckDriver, SegwayRMP, SphereDriver, snd, GarciaDriver, CameraUvc, FromRanger, and ToRanger.

◆ ProcessMessages() [1/2]

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.

◆ ProcessMessages() [2/2]

void Driver::ProcessMessages ( void )

Process pending messages.

Equivalent to ProcessMessages(0).

Referenced by StatGrabDriver::Main(), SphereDriver::Main(), SegwayRMP400::Main(), Khepera::Main(), AdaptiveMCL::Main(), RFLEX::Main(), Alsa::Main(), Erratic::Main(), mbasedriver::Main(), and AdaptiveMCL::MainQuit().

◆ Publish() [1/4]

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 mbasedriver::HandleConfig(), StatGrabDriver::Main(), Khepera::Main(), RFLEX::Main(), Alsa::Main(), Erratic::Main(), AdaptiveMCL::MainQuit(), SegwayRMP400::ProcessData(), SphereDriver::ProcessMessage(), SegwayRMP400::ProcessMessage(), AdaptiveMCL::ProcessMessage(), Khepera::ProcessMessage(), RFLEX::ProcessMessage(), Erratic::ProcessMessage(), mbasedriver::PublishAIn(), mbasedriver::PublishIR(), mbasedriver::PublishPosition2D(), mbasedriver::PublishPower(), and mbasedriver::PublishSonar().

◆ Publish() [2/4]

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

◆ Publish() [3/4]

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

◆ Publish() [4/4]

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

◆ RegisterProperty() [1/2]

virtual bool Driver::RegisterProperty	(	const char *	key,
		Property *	property,
		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

◆ RegisterProperty() [2/2]

virtual bool Driver::RegisterProperty	(	Property *	property,
		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

◆ Setup()

virtual int Driver::Setup ( void )

inlinevirtual

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, mbasedriver, Erratic, MapTransform, LaserTransform, snd, FromRanger, and ToRanger.

◆ Shutdown()

virtual int Driver::Shutdown ( void )

inlinevirtual

Finalize the driver.

This function is called with the last client unsubscribes.

Returns: Returns 0 on success.

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

◆ Subscribe() [1/2]

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 P2OS, mbasedriver, Erratic, wbr914, RFLEX, Khepera, and EpuckDriver.

Referenced by REB::MainQuit(), SegwayRMP400::MainSetup(), Khepera::Subscribe(), RFLEX::Subscribe(), wbr914::Subscribe(), Erratic::Subscribe(), mbasedriver::Subscribe(), and P2OS::Subscribe().

◆ Subscribe() [2/2]

virtual int Driver::Subscribe	(	QueuePointer &	,
		player_devaddr_t
	)

inlinevirtual

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.

◆ SubscriptionUnlock()

virtual void Driver::SubscriptionUnlock ( void )

protectedvirtual

Unlock to protect the subscription count for the driver.

◆ Terminate()

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.

◆ TestCancel()

virtual void Driver::TestCancel ( )

inlineprotectedvirtual

enable thread cancellation and test for cancellation

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

Reimplemented in ThreadedDriver.

◆ Unlock()

virtual void Driver::Unlock ( void )

protectedvirtual

Unlock access to driver internals.

◆ Unsubscribe() [1/2]

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 P2OS, mbasedriver, Erratic, wbr914, RFLEX, Khepera, and EpuckDriver.

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

◆ Unsubscribe() [2/2]

virtual int Driver::Unsubscribe	(	QueuePointer &	,
		player_devaddr_t
	)

inlinevirtual

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.

◆ Update()

virtual void Driver::Update ( void )

inlinevirtual

Update non-threaded drivers.

Reimplemented in ThreadedDriver.

◆ Wait()

virtual bool Driver::Wait ( double TimeOut = 0.0 )

protectedvirtual

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.

Referenced by ThreadedDriver::MainQuit().

Member Data Documentation

◆ accessMutex

pthread_mutex_t Driver::accessMutex

private

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

◆ alwayson

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

◆ entries

int Driver::entries

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

This is updated and read by the Device class.

◆ ret_queue

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.

◆ subscriptionMutex

pthread_mutex_t Driver::subscriptionMutex

private

Mutex used to protect the subscription count for the driver.

◆ subscriptions

int Driver::subscriptions

private

Number of subscriptions to this driver.

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

driver.h

Detailed Description

Public Member Functions

Public Attributes

Protected Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ Driver() [1/2]

◆ Driver() [2/2]

Member Function Documentation

◆ AddInterface() [1/2]

◆ AddInterface() [2/2]

◆ GetError()

◆ Lock()

◆ ProcessInternalMessages()

◆ ProcessMessage()

◆ ProcessMessages() [1/2]

◆ ProcessMessages() [2/2]

◆ Publish() [1/4]

◆ Publish() [2/4]

◆ Publish() [3/4]

◆ Publish() [4/4]

◆ RegisterProperty() [1/2]

◆ RegisterProperty() [2/2]

◆ Setup()

◆ Shutdown()

◆ Subscribe() [1/2]

◆ Subscribe() [2/2]

◆ SubscriptionUnlock()

◆ Terminate()

◆ TestCancel()

◆ Unlock()

◆ Unsubscribe() [1/2]

◆ Unsubscribe() [2/2]

◆ Update()

◆ Wait()

Member Data Documentation

◆ accessMutex

◆ alwayson

◆ entries

◆ ret_queue

◆ subscriptionMutex

◆ subscriptions