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