The database is owned by a central manager, typically residing on the robot. Database clients, such as graphical user interfaces, connect to the database manager and register to either subscribe to database entries (i.e., when the entry values change on the robot, the new values are propagated to the clients) or to publish to database entries (i.e., when the entry value changes on the client, the new values are propagated to the manager). Clients cannot register to both publish and subscribe to the same entry.
There are two methods by which information can be propagated between database clients and managers. In immediate mode, as soon as a change is made, that change is propagated. Changes made in immediate mode can be throttled to save network bandwidth, for example, a limit can be set to send changes in a database entries at most every n milliseconds. In periodic mode, the value of the database entry is propagated over the network at a regular interval.
Changes in database entries are propagated by both database managers and clients through a subthread which contains a list of database entry monitors. When a database entry is marked as having an external ``client'', a monitor is added to the list. The subthread iterates through the list at a regular interval to check all of the monitors. Periodic monitors fire at regular intervals and send the current value to the recipient. Immediate monitors simply check to see if there is a throttled change pending to send.
Users can also add callbacks to entries which invoke a C++ method when a database entry is changed. These callbacks are implemented in the simplest possible manner, which means they are very inefficient, and really should not be used. When you add a callback to an entry, a monitor gets added to the monitor list. Whenever the monitor list checks this monitor, it will perform a comparison of the old entry value and the new entry value. If they are different, then the callback is marked to be executed by a update function that the user of both data base managers and clients must call. Note that this means that callbacks will not be invoked immediately, add significant computational burden to the monitor thread, and require the user to periodically invoke a special method in the ``main'' thread of control. It is my opinion that callbacks should not be used at all, and that you should design your code accordingly. If there is a great hue and cry for them, these drawbacks can be alleviated somewhat, but it will take more restructuring of code than you think to make them efficient and effective.
Although the individual components have their classes defined in a variety of header files, you will only have to include the file Database.hh.
Database Entries
The core of the database are the named database entries, encapsulated within the class DBEntry. First, each entry has a name by which it is known in the database. What the entry contains is essentially a block of bytes: You can consider a database entry as ``wrapping'' an instance of a communiations manager message, with all of the caveats about byte order (must be identical across processes), structure alignment (must be compatible between compilers), and structure components (there can be no pointers unless you pack the data yourself).
In addition, each entry has a ``description.'' The purpose of a description is to give some measure of run-time type checking for the data that goes into and out of the entry as remote clients subscribe to it. Thus, the description is usually the name of the type which resides in the entry data. For example, if a database entry simply contains an integer, its description would be ``int.'' The entry converts the description into a single integer key for comparison.
Note that database entries can be even more expensive than communication mailboxes and streams, and thus it is imperative that the database not be simply a bunch of named integers and doubles. Data that is meant to be used together should be grouped together into structures as much as possible.
Common database operations
Both the database manager and the database client classes have a common superclass, DBBase, which contains methods common to both, such as the creation and management of the monitor thread or the management of callbacks.
Database Manager
There is one database manager (an instance of the class DBManager) which ``owns'' all of the database entries. Clients can access and even add entries remotely , but the entries are still truly maintained by the database manager.
As well as creating a monitor thread (through it's superclass, DBBase), a database manager also creates a protocol thread, which is watching a stream sink for messages from database clients about access to the manager's database.
Database Clients
Users access the central database managed by a database manager by using the database clients (through the DBClient class). These clients send messages to the database manager's stream sink, and performs all of the necessary handshaking to setup database communications. Unlike the database manager operations, which return DBEntry's, the database client operations return a subclass, RemoteDBEntry which allows the user to detect when the remote database manager has gone down and come back up, and allows the user to quickly reregister the entry with the new database manager.
Note there is one serious lack in the database interface: currently while remote clients can register to subscribe to database entries, there is no way for them to cancel a subscription. The database manager is smart enough to see that an client has stopped and restarted, and will ``cancel'' all of the client's previous subscriptions (thus the necessity of the RemoteDBEntry class), so this is not a fatal flaw, but it is still a flaw.
need to get focused example here
Compounds | |
| class | DBBase |
| Common superclass of DBManager and DBClient. More... | |
| class | DBClient |
| Interface class for a database client. More... | |
| class | DBEntry |
| Fundamental class for entries in the database. More... | |
| class | DBManager |
| Manager for a database (blackboard) operations. More... | |
| class | RemoteDBEntry |
| Class to encapsulate a remote database entry's details. More... | |