A client application is built by using an IRB interface (IRBi) which, on invocation, will spawn the client's ``personal'' IRB. This IRB is used to cache data retrieved from other IRBs during the operation of the client. An application specific server is similarly built using the IRBi. Hence there is actually little differentiation between a client and a server. Using the IRBi a client can arbitrarily form a connection with any other client or server to access its resources. The IRBi will communicate the request to the client's personal IRB which will then communicate with the remote client's or server's IRB. It is the IRBs' responsibility to negotiate the networking and database services requested by the client/server applications. This form of flexibility will allow arbitrary CVR topologies to be constructed.
A client's handle to their personal IRB is used to activate dynamic connections with remote IRBs. A client wishing to share information between its personal IRB and a remote IRB begins by first creating a communication channel and declaring its communication properties. Then any number of local and remote keys may be linked over the channel. A key is a handle to a storage location in an IRB's database. The database is used to cache data received from remote keys. Keys are uniquely identified across all IRBs and can be hierarchically organized much like a UNIX directory structure. Each local key may be linked to only one remote key. This is the link explicitly invoked by the user to share information with a remote IRB. However each local key can accept multiple linkages from other remote subscribing keys. The user is generally made unaware of these additional linkages as the personal IRB transparently manages data sharing with the remote subscribers. Any modifications that are made to one key will automatically be propagated to all the other linked keys.
In addition to connection reliability clients may specify Quality of Service (QoS) requirements. Hence they are able to declare the desired bandwidth, latency, and jitter of the data stream. The personal IRB will attempt to obtain the desired level of QoS from the remote IRB, but if it fails, the client may at any time negotiate for a lower QoS.
In most CVR applications, world state information consisting of a few tens of bytes are actively distributed. That is, the moment a new value is generated it is automatically propagated to all the subscribers of the data. Passive updates occur only on subscriber request and usually involves a comparison of local and remote timestamps before transmission. For example, passive updates are typically used to download large volumes of 3D model data. Caching data and comparing their timestamps helps to reduce the need to redundantly download the same data set.
The initial synchronization behavior determines how the local and remote keys should be synchronized when the links are first formed. That is, clients are able to choose to synchronize automatically based on the keys' timestamps. That is the older key will be updated with information from the newer key. However the client may also choose to force synchronization from the local key to the remote key, and vice versa, regardless of timestamp. Of course clients may choose to perform no initial synchronization at all.
Subsequent synchronization behavior specifies the manner in which data is synchronized when local or remote updates to keys occur. The same options as for initial synchronization hold.
The default link property is to use active updates with automatic initial and subsequent synchronization.
Some examples of events include: new incoming data event; IRB connection broken event; QoS deviation event.
For now this is enough to get you started on working with CAVERNsoft. The section below gives you a pictorial guide of how to code with CAVERNsoft.
Once you have a handle you can define a key with it. A key is just a reference to a place in the IRB where you can store your own information. So once you have a key defined you can start putting data in it.
To share the information in the local key with another remote client you need to first create and open a channel to the remote client (of course the remote client must also be built from the CAVERNsoft library).
By specifying a channel you may choose between reliable and unreliable data delivery; and, soon various other networking characteristics such as quality of service (latency, jitter, bandwidth).
Once the channel is established you can link the local key to a remote key. Now anytime you place new data in your local key the data gets automagically forwarded to the remote key and vice versa. If you wish to store the data in the local or remote key permanently you need to perform a local or remote commit, respectively.
So basically what we've created is a notion of a distributed shared memory with some added database capability. Put in another way it is a database system with active updates. Whatever you want to call it the keys are now intimately linked. The difference between this scheme and other distributed database-like ideas is that the channels over which data is delivered may be tuned to support reliable as well as unreliable networking protocols (like TCP, UDP, Multicast) as well as set up networking Quality of Service features. So although this all feels like a regular distributed shared memory or database it has some slightly unconventional networking nuances. This way we can merge all three concepts simultaneously into one (the idea being to "trick" VR deverlopers into being networking as well as database programmers all at the same time.)
With this you can create multiple channels between clients, and you can choose which pairs of keys are linked over which channels. A channel can support multiple links. Multiple clients may link their keys to a single key on a single central client (server). Proper propagation of data is maintained by CAVERNsoft and the constraints that you gave it when you initially created the link.
This "brief" introduction should give you enough of the general idea to start writing CAVERNsoft applications. The specifics of the API calls can be found in the API documentation. Also there are a few examples included in the installation that will help get your feet wet.