Database Module (DB)

The database is a common repository for data. The most important application is the scene data, but it can keep auxiliary data such as function declarations and frame buffers. The DB module has calls to create a database item, to destroy an item, to get a pointer to an item (access), to give back (unpin) a pointer, and to write back changes into the distributed database after writing (flush). All items have a unique identifier, called a tag, that is assigned by the DB module when an item is created. All other functions reference items through tags. Tags, unlike pointers, are unique on the network and can be stored in the database as part of items, thus allowing users to grow trees of items.

An item is retrieved from the database by requesting a pointer to the data. The DB module makes sure that the requested item is in local memory, pins it, and returns a pointer to it. Pinning means that the DB module retains the item in memory until it is explicitly unpinned. One of the fundamental design goals is that data never exists twice in the same address space. All changes made to the item by using the returned pointer are immediately visible to all others in the local address space. It is the supervisor's responsibility to make sure that no conflicts occur, such as modules changing the scene while it is being rendered. (The supervisor is the module that started the whole operation, usually a translator.)

Creating an item and requesting a pointer as described above implies pinning the item in memory, so the returned pointer is guaranteed to remain valid. While an item is pinned, the DB module will not destroy or move the item to make space for other items coming in from the network. If the pointer is used to change the item (which is usually the case after creating it), the item must be flushed explicitly after the change is complete. Flushing means that all other hosts on the network who have a copy of the item are notified to delete the item from their local memory, or re-read it if it was pinned locally. The DB module does not offer locking functions. If a write to the database must be done atomically, messages must be used to implement a lock.

Note that the DB functions that create, resize (grow), or delete DB elements should not normally be used by an application. Instead, the scene should be built with API calls. For certain operations, such as editing geometric objects, SCENE calls can be used. SCENE adds data type management, including size calculations and appropriate defaults for struct fields, and dirty flag management for consistent virtual shared database access required when rendering on a network. API adds symbol table management which is necessary to construct cohesive scenes.