Device Class Reference

Encapsulates a device (i.e., a driver bound to an interface) More...

#include <device.h>

Collaboration diagram for Device:

Detailed Description

Encapsulates a device (i.e., a driver bound to an interface)

A device describes an instantiated driver/interface combination. Drivers may support more than one interface, and hence appear more than once in the device table.

Public Member Functions
	Device (player_devaddr_t addr, Driver *driver)
	Constructor. More...
	~Device ()
	Destructor.
int	Subscribe (QueuePointer &sub_queue)
	Subscribe the given queue to this device. More...
int	Unsubscribe (QueuePointer &sub_queue)
	Unsubscribe the given queue from this device. More...
void	PutMsg (QueuePointer &resp_queue, uint8_t type, uint8_t subtype, void *src, size_t deprecated, double *timestamp)
	Send a message to this device. More...
void	PutMsg (QueuePointer &resp_queue, player_msghdr_t *hdr, void *src, bool copy=true)
	Send a message to this device (short form) More...
Message *	Request (QueuePointer &resp_queue, uint8_t type, uint8_t subtype, void *src, size_t deprecated, double *timestamp, bool threaded=true)
	Make a request of another device. More...
Message *	TimedRequest (QueuePointer &resp_queue, uint8_t type, uint8_t subtype, void *src, double timeout=0, double *timestamp=NULL, bool threaded=true)
	Make a request of another device with a timeout. More...

Static Public Member Functions
static bool	MatchDeviceAddress (player_devaddr_t addr1, player_devaddr_t addr2)
	Compare two addresses. More...

Public Attributes
Device *	next
	Next entry in the device table (this is a linked-list)
player_devaddr_t	addr
	Address for this device.
char	drivername [PLAYER_MAX_DRIVER_STRING_LEN]
	The string name for the underlying driver.
QueuePointer	InQueue
	Pointer to the underlying driver's queue.
QueuePointer *	queues
	Linked list of subscribed queues.
size_t	len_queues
	Length of queues.
Driver *	driver
	Pointer to the underlying driver.

Private Member Functions
void	Lock (void)
	Lock access to driver internals. More...
void	Unlock (void)
	Unlock access to driver internals. More...

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

Constructor & Destructor Documentation

Device()

Device::Device	(	player_devaddr_t	addr,
		Driver *	driver
	)

Constructor.

Parameters

addr	: Device address
driver	: Pointer to the underlying driver

Member Function Documentation

Lock()

void Device::Lock ( void  )

private

Lock access to driver internals.

MatchDeviceAddress()

static bool Device::MatchDeviceAddress ( player_devaddr_t  addr1, player_devaddr_t  addr2  )

inlinestatic

Compare two addresses.

This static method returns true if all 4 components of the two addresses match exactly. It's useful in Driver::ProcessMessage when you're deciding how to handle a message.

References player_devaddr::host, player_devaddr::index, player_devaddr::interf, and player_devaddr::robot.

Referenced by ImageBase::MainSetup(), Erratic::ProcessMessage(), LaserTransform::Setup(), wbr914::Subscribe(), Erratic::Subscribe(), mbasedriver::Subscribe(), P2OS::Subscribe(), wbr914::Unsubscribe(), Erratic::Unsubscribe(), mbasedriver::Unsubscribe(), and P2OS::Unsubscribe().

PutMsg() [1/2]

void Device::PutMsg	(	QueuePointer &	resp_queue,
		uint8_t	type,
		uint8_t	subtype,
		void *	src,
		size_t	deprecated,
		double *	timestamp
	)

Send a message to this device.

This method is the basic way of sending a message to a device. The header will be assembled and the message will get pushed on to the underlying driver's InQueue.

Parameters

resp_queue	: Where to push any reply (e.g., your InQueue)
type	: Message type
subtype	: Message subtype
src	: Message payload
deprecated	Used to be the length of the message this is now calculated
timestamp	: If non-NULL, the timestamp to attach to the message; otherwise, the current time is filled in.

Referenced by SegwayRMP400::HandlePosition2DCmd(), and SegwayRMP400::HandlePosition3DCmd().

PutMsg() [2/2]

void Device::PutMsg	(	QueuePointer &	resp_queue,
		player_msghdr_t *	hdr,
		void *	src,
		bool	copy = true
	)

Send a message to this device (short form)

This form of PutMsg is useful if you already have the message header assembled (e.g., when you're forwarding a message).

Parameters

resp_queue	Where to push any reply
hdr	The message header.
src	The message body (its size is stored in hdr->size).
copy	If copy is false then the message will be claimed by the device

Request()

Message* Device::Request	(	QueuePointer &	resp_queue,
		uint8_t	type,
		uint8_t	subtype,
		void *	src,
		size_t	deprecated,
		double *	timestamp,
		bool	threaded = true
	)

Make a request of another device.

This method send a request message to a device and waits for the reply.

Parameters

resp_queue	: Where to push the reply (e.g., your InQueue)
type	: Message type (usually PLAYER_MSGTYPE_REQ).
subtype	: Message subtype (interface-specific)
src	: Message body
deprecated	Used to be the length of the message this is now calculated
timestamp	: If non-NULL, the timestamp to attach to the request; otherwise, the current time is filled in.
threaded	: True if the caller is executing in its own thread, false otherwise

Note

It is is crucial that threaded be set correctly. If you call this method from within Setup() or Shutdown(), or if your driver does not run in its own thread, then threaded must be false. Deadlocks will otherwise result.

Returns

A pointer to the reply message. The caller is responsible for deleting this pointer.

Referenced by SegwayRMP400::ProcessMessage(), and MapTransform::Setup().

Subscribe()

int Device::Subscribe

(

QueuePointer &

sub_queue

)

Subscribe the given queue to this device.

Returns

0 on success, non-zero otherwise.

Referenced by MapTransform::Setup().

TimedRequest()

Message* Device::TimedRequest	(	QueuePointer &	resp_queue,
		uint8_t	type,
		uint8_t	subtype,
		void *	src,
		double	timeout = 0,
		double *	timestamp = NULL,
		bool	threaded = true
	)

Make a request of another device with a timeout.

This method send a request message to a device and waits for the reply. If a timeout occurs it returns NULL.

Note that any driver calling this here a timeout is not going to be a bad error also needs to add into its process messages somethig to handle the ACKs if they are recieved after the timeout. As such I would recomment that this is only called with a timeout not 0 if a timeout occurring is an indicaion of a system ailure (and a stall is unacceptable)

Parameters

resp_queue	: Where to push the reply (e.g., your InQueue)
type	: Message type (usually PLAYER_MSGTYPE_REQ).
subtype	: Message subtype (interface-specific)
src	: Message body
timeout	How long to wait for a response, if zero will never timeout
timestamp	: If non-NULL, the timestamp to attach to the request; otherwise, the current time is filled in.
threaded	: True if the caller is executing in its own thread, false otherwise

Note

It is is crucial that threaded be set correctly. If you call this method from within Setup() or Shutdown(), or if your driver does not run in its own thread, then threaded must be false. Deadlocks will otherwise result.

Returns

A pointer to the reply message. The caller is responsible for deleting this pointer. Will return NULL on a failure

Unlock()

void Device::Unlock ( void  )

private

Unlock access to driver internals.

Unsubscribe()

int Device::Unsubscribe

(

QueuePointer &

sub_queue

)

Unsubscribe the given queue from this device.

Returns

0 on success, non-zero otherwise.

Member Data Documentation

accessMutex

pthread_mutex_t Device::accessMutex

private

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

---

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

• device.h