driver.h
1/*
2 * Player - One Hell of a Robot Server
3 * Copyright (C) 2000
4 * Brian Gerkey, Kasper Stoy, Richard Vaughan, & Andrew Howard
5 *
6 *
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 *
21 */
22/********************************************************************
23 *
24 * This library is free software; you can redistribute it and/or
25 * modify it under the terms of the GNU Lesser General Public
26 * License as published by the Free Software Foundation; either
27 * version 2.1 of the License, or (at your option) any later version.
28 *
29 * This library is distributed in the hope that it will be useful,
30 * but WITHOUT ANY WARRANTY; without even the implied warranty of
31 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
32 * Lesser General Public License for more details.
33 *
34 * You should have received a copy of the GNU Lesser General Public
35 * License along with this library; if not, write to the Free Software
36 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
37 *
38 ********************************************************************/
39
40/*
41 * $Id$
42 *
43 * The virtual class from which all driver classes inherit. this
44 * defines the API that all drivers must implement.
45 */
46
47#ifndef _DRIVER_H
48#define _DRIVER_H
49
50#if defined (WIN32)
51 #if defined (PLAYER_STATIC)
52 #define PLAYERCORE_EXPORT
53 #elif defined (playercore_EXPORTS)
54 #define PLAYERCORE_EXPORT __declspec (dllexport)
55 #else
56 #define PLAYERCORE_EXPORT __declspec (dllimport)
57 #endif
58#else
59 #define PLAYERCORE_EXPORT
60#endif
61
62#include <pthread.h>
63
64#include <libplayercommon/playercommon.h>
65#include <libplayercore/message.h>
66#include <libplayerinterface/player.h>
67#include <libplayercore/property.h>
68
69//using namespace std;
70
86#define HANDLE_CAPABILITY_REQUEST(device_addr, queue, hdr, data, cap_type, cap_subtype) \
87 if(Message::MatchMessage(hdr, PLAYER_MSGTYPE_REQ, PLAYER_CAPABILITIES_REQ, device_addr)) \
88 { \
89 player_capabilities_req_t & cap_req = * reinterpret_cast<player_capabilities_req_t *> (data);\
90 if (cap_req.type == cap_type && cap_req.subtype == cap_subtype) \
91 { \
92 Publish(device_addr, queue, PLAYER_MSGTYPE_RESP_ACK, PLAYER_CAPABILITIES_REQ); \
93 return 0; \
94 } \
95 }
96
97
98// Forward declarations
99class ConfigFile;
100
108class PLAYERCORE_EXPORT Driver
109{
110 private:
111 /* @brief Last error value; useful for returning error codes from
112 constructors. */
113 int error;
114
115 PropertyBag propertyBag;
116
119 public:
120 bool HasSubscriptions();
121
122 protected:
123
130
141 int AddInterface(player_devaddr_t *addr, ConfigFile * cf, int section, int code, const char * key = NULL);
142
143
145 void SetError(int code) {this->error = code;}
146
156 virtual bool Wait(double TimeOut=0.0);
157
159 int AddFileWatch(int fd, bool ReadWatch = true, bool WriteWatch = false, bool ExceptWatch = true);
160
162 int RemoveFileWatch(int fd, bool ReadWatch = true, bool WriteWatch = false, bool ExceptWatch = true);
163
164
165 private:
168 pthread_mutex_t accessMutex;
170 pthread_mutex_t subscriptionMutex;
171 protected:
174 virtual void Lock(void);
176 virtual void Unlock(void);
177
179 virtual void SubscriptionLock(void);
181 virtual void SubscriptionUnlock(void);
182
186 virtual void TestCancel() {};
187
188
189 public:
196
211 virtual void Publish(player_devaddr_t addr,
212 QueuePointer &queue,
213 uint8_t type,
214 uint8_t subtype,
215 void* src=NULL,
216 size_t deprecated=0,
217 double* timestamp=NULL,
218 bool copy=true);
219
233 virtual void Publish(player_devaddr_t addr,
234 uint8_t type,
235 uint8_t subtype,
236 void* src=NULL,
237 size_t deprecated=0,
238 double* timestamp=NULL,
239 bool copy=true);
240
241
242
251 virtual void Publish(QueuePointer &queue,
252 player_msghdr_t* hdr,
253 void* src,
254 bool copy = true);
255
263 virtual void Publish(player_msghdr_t* hdr,
264 void* src,
265 bool copy = true);
266
267
270
274
283
286
295 int section,
296 bool overwrite_cmds,
297 size_t queue_maxlen,
298 int interf);
299
308 int section,
309 bool overwrite_cmds = true,
310 size_t queue_maxlen = PLAYER_MSGQUEUE_DEFAULT_MAXLEN);
311
313 virtual ~Driver();
314
317 int GetError() { return(this->error); }
318
328 virtual int Subscribe(player_devaddr_t addr);
329
343 virtual int Subscribe(QueuePointer &/*queue*/, player_devaddr_t /*addr*/) {return 1;};
344
354 virtual int Unsubscribe(player_devaddr_t addr);
355
369 virtual int Unsubscribe(QueuePointer &/*queue*/, player_devaddr_t /*addr*/) {return 1;};
370
377 virtual int Terminate();
378
379
386 virtual int Setup() {return 0;};
387
393 virtual int Shutdown() {return 0;};
394
402 void ProcessMessages(int maxmsgs);
403
408 void ProcessMessages(void);
409
419 virtual int ProcessMessage(QueuePointer &resp_queue, player_msghdr * hdr,
420 void * data);
421
423 virtual void Update()
424 {
425 this->ProcessMessages();
426 }
427
435 virtual int ProcessInternalMessages(QueuePointer& resp_queue,
436 player_msghdr * hdr,
437 void * data);
438
446 virtual bool RegisterProperty(const char *key,
447 Property *property,
448 ConfigFile* cf,
449 int section);
450
458 virtual bool RegisterProperty(Property *property,
459 ConfigFile* cf,
460 int section);
461};
462
463typedef enum player_thread_state
464{
465 PLAYER_THREAD_STATE_STOPPED,
466 PLAYER_THREAD_STATE_RUNNING,
467 PLAYER_THREAD_STATE_STOPPING,
468 PLAYER_THREAD_STATE_RESTARTING
469} player_thread_state_t;
470
471class PLAYERCORE_EXPORT PlayerBarrier
472{
473public:
475 {
476 pthread_mutex_init(&barrierMutex,NULL);
477 pthread_cond_init(&barrierCond,NULL);
478 barrierValue = 0;
479 }
481 {
482 pthread_mutex_destroy(&barrierMutex);
483 pthread_cond_destroy(&barrierCond);
484 };
485
486 int SetValue(int Value)
487 {
488 return barrierValue = Value;
489 };
490
491 int Wait()
492 {
493 pthread_mutex_lock(&barrierMutex);
494 assert(barrierValue);
495 if (--barrierValue)
496 pthread_cond_wait(&barrierCond,&barrierMutex);
497 else
498 pthread_cond_broadcast(&barrierCond);
499 pthread_mutex_unlock(&barrierMutex);
500 return 0;
501 };
502private:
505 pthread_mutex_t barrierMutex;
506
507 int barrierValue;
508
509 pthread_cond_t barrierCond;
510
511};
512
513
514
552class PLAYERCORE_EXPORT ThreadedDriver : public Driver
553{
554 protected:
555
556 /* @brief Start the driver thread
557
558 This method is usually called from the overloaded Setup() method to
559 create the driver thread. This will call Main(). */
560 virtual void StartThread(void);
561
566 virtual void StopThread(void);
567
570 static void* DummyMain(void *driver);
571
574 static void DummyMainQuit(void *driver);
575
576 private:
580 pthread_t driverthread;
581
584 player_thread_state_t ThreadState;
585 bool SetupSuccessful;
586
589
590 protected:
595
596
597 public:
598
606 int section,
607 bool overwrite_cmds,
608 size_t queue_maxlen,
609 int interface_);
610
619 int section,
620 bool overwrite_cmds = true,
621 size_t queue_maxlen = PLAYER_MSGQUEUE_DEFAULT_MAXLEN);
622
625
632 virtual int Setup();
633
640 virtual int Shutdown();
641
648 virtual int Terminate();
649
655 virtual void Main(void) = 0;
656
658 virtual int MainSetup(void) {return 0;};
659
664 virtual void MainQuit(void) {};
665
675 bool Wait(double TimeOut=0.0);
676
677 virtual void Update()
678 {};
679
680};
681
682
683#endif
Class for loading configuration file information.
Definition: configfile.h:197
Base class for all drivers.
Definition: driver.h:109
int AddInterface(player_devaddr_t *addr, ConfigFile *cf, int section, int code, const char *key=NULL)
Add an interface.
virtual int Terminate()
Terminate the driver.
virtual int ProcessInternalMessages(QueuePointer &resp_queue, player_msghdr *hdr, void *data)
Internal message handler.
virtual int Unsubscribe(player_devaddr_t addr)
Unsubscribe from this driver.
QueuePointer InQueue
Queue for all incoming messages for this driver.
Definition: driver.h:285
bool alwayson
Always on flag.
Definition: driver.h:282
void ProcessMessages(int maxmsgs)
Process pending messages.
virtual ~Driver()
Destructor.
void SetError(int code)
Set/reset error code.
Definition: driver.h:145
virtual int Subscribe(QueuePointer &, player_devaddr_t)
Subscribe to this driver.
Definition: driver.h:343
int GetError()
Get last error value.
Definition: driver.h:317
virtual void Lock(void)
Lock access between the server and driver threads.
virtual void SubscriptionUnlock(void)
Unlock to protect the subscription count for the driver.
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 int Setup()
Initialize the driver.
Definition: driver.h:386
virtual bool RegisterProperty(Property *property, ConfigFile *cf, int section)
Property registration.
virtual int Unsubscribe(QueuePointer &, player_devaddr_t)
Unsubscribe from this driver.
Definition: driver.h:369
virtual void Update()
Update non-threaded drivers.
Definition: driver.h:423
QueuePointer ret_queue
Last requester's queue.
Definition: driver.h:195
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 bool RegisterProperty(const char *key, Property *property, ConfigFile *cf, int section)
Property registration.
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 Unlock(void)
Unlock access to driver internals.
void ProcessMessages(void)
Process pending messages.
player_devaddr_t device_addr
Default device address (single-interface drivers)
Definition: driver.h:269
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 entries
Total number of entries in the device table using this driver.
Definition: driver.h:273
virtual int ProcessMessage(QueuePointer &resp_queue, player_msghdr *hdr, void *data)
Message handler.
pthread_mutex_t subscriptionMutex
Mutex used to protect the subscription count for the driver.
Definition: driver.h:170
virtual int Shutdown()
Finalize the driver.
Definition: driver.h:393
int AddInterface(player_devaddr_t addr)
Add an interface.
Driver(ConfigFile *cf, int section, bool overwrite_cmds, size_t queue_maxlen, int interf)
Constructor for single-interface drivers.
virtual void Publish(player_msghdr_t *hdr, void *src, bool copy=true)
Publish a message via one of this driver's interfaces.
virtual bool Wait(double TimeOut=0.0)
Wait for new data to arrive on the driver's queue.
virtual int Subscribe(player_devaddr_t addr)
Subscribe to this driver.
pthread_mutex_t accessMutex
Mutex used to lock access, via Lock() and Unlock(), to driver internals, like the list of subscribed ...
Definition: driver.h:168
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 SubscriptionLock(void)
Lock to protect the subscription count for the driver.
virtual void TestCancel()
enable thread cancellation and test for cancellation
Definition: driver.h:186
int subscriptions
Number of subscriptions to this driver.
Definition: driver.h:118
Driver(ConfigFile *cf, int section, bool overwrite_cmds=true, size_t queue_maxlen=PLAYER_MSGQUEUE_DEFAULT_MAXLEN)
Constructor for multiple-interface drivers.
Definition: driver.h:472
pthread_mutex_t barrierMutex
barrier to make sure StartThread doesnt return until cleanup handlers etc have been installed.
Definition: driver.h:505
Property bag class: stores registered properties.
Definition: property.h:208
Property base class.
Definition: property.h:60
An autopointer for the message queue.
Definition: message.h:74
Base class for drivers which oeprate with a thread.
Definition: driver.h:553
player_thread_state_t ThreadState
TODO: insert state machine here.
Definition: driver.h:584
virtual ~ThreadedDriver()
Destructor.
void TestCancel()
enable thread cancellation and test for cancellation
PlayerBarrier SetupBarrier
Barrier to synchronise threads on setup.
Definition: driver.h:588
ThreadedDriver(ConfigFile *cf, int section, bool overwrite_cmds, size_t queue_maxlen, int interface_)
Constructor with implicit interface.
static void DummyMainQuit(void *driver)
Dummy main cleanup (just calls real main cleanup).
pthread_t driverthread
The driver's thread.
Definition: driver.h:580
bool Wait(double TimeOut=0.0)
Wait for new data to arrive on the driver's queue.
virtual int MainSetup(void)
Sets up the resources needed by the driver thread.
Definition: driver.h:658
virtual int Shutdown()
Finalize the driver.
virtual int Setup()
Initialize the driver.
virtual void Main(void)=0
Main method for driver thread.
static void * DummyMain(void *driver)
Dummy main (just calls real main).
virtual void StopThread(void)
Cancel (and wait for termination) of the driver thread.
virtual int Terminate()
Terminate the driver.
virtual void Update()
Update non-threaded drivers.
Definition: driver.h:677
virtual void MainQuit(void)
Cleanup method for driver thread (called when main exits)
Definition: driver.h:664
ThreadedDriver(ConfigFile *cf, int section, bool overwrite_cmds=true, size_t queue_maxlen=PLAYER_MSGQUEUE_DEFAULT_MAXLEN)
Constructor for multiple-interface drivers.
#define PLAYER_MSGQUEUE_DEFAULT_MAXLEN
Default maximum length for a message queue.
Definition: player.h:76
A device address.
Definition: player.h:146
Generic message header.
Definition: player.h:162