DIVE Properties

Reference Document
Web site: <http://www.sics.se/dive/manual/properties.html>

Emmanuel Frécon - <emmanuel@sics.se>
Olof Hagsand - <olof@sics.se>
Olov Ståhl - <olovs@sics.se>
The Swedish Institute of Computer Science, Stockholm June, 1995

1. What is a Dive property?

Properties represent a way to associate application-level data to objects, data which the system (Dive) need have no knowledge of. The data is only interpretable by application-level semantics, the Dive distribution layer simply relays the data as a byte stream.

Properties can be associated to all entities: dive_obj, worlds, views and persons.

The most essential fields of a property are: 

     char * name    - the name used to refer to the property,
     char * type    - the type of the property,
     void * data    - the value of the property, depends on the type,
     int    length  - the length of the data.

There are three user interface to creating and manipulating properties: a functional interface using C library calls, a Dive/Tcl interface and a file format interface, each described below.

2. Sharing properties

If the data (property value) should be distributed among several application peers on different architectures, the distributed system needs a way to encode and decode the data so that the application peers see identical data.

A property must therefore be accompanied by a type description acting as a specification to the decoding and encoding. In Dive, XDR is used for this purpose. Therefore, in order to create a distributed property, an XDR function must be supplied for each type that is registered. Now, if a shared property is created and a process has not registered an xdr type for it, its value is saved undecoded, making it possible for other processes to interpret it any way.

Properties can be either local or global. Local properties are private to one process, while global properties values are shared between all processes. A local property of an object is not distributed to other processes. When changing the property value, only a local change occurs. Global properties and their values are distributed to all processes.

3. Property naming: cached ids

Globally for the DIVE system, properties are identified by (string) names. Locally to each process, properties may be identified by unique integer identifiers. The identifier is returned when a new property is created and may then be used as an identifier in all successive operations. The reason for this double identification is speed in processes highly dependent on values stored in properties.

4. Functional C interface

The following C functions are used for local properties:

http://www.sics.se/dive/manual/cref.p.html#property_create http://www.sics.se/dive/manual/cref.p.html#property_put http://www.sics.se/dive/manual/cref.p.html#property_get http://www.sics.se/dive/manual/cref.p.html#property_remove

The following C functions are used for global properties. However, reading a global property is done by the local property_get operation.

http://www.sics.se/dive/manual/cref.d.html#distr_property_create http://www.sics.se/dive/manual/cref.d.html#distr_property_put http://www.sics.se/dive/manual/cref.d.html#distr_property_remove http://www.sics.se/dive/manual/cref.d.html#dive_xdr_register

5. Dive/Tcl interface

The following commands are useful for manipulating properties using the Dive/Tcl interface [1] [3].

http://www.sics.se/dive/manual/tclref.html#dive_property_create http://www.sics.se/dive/manual/tclref.html#dive_property_put http://www.sics.se/dive/manual/tclref.html#dive_property_get http://www.sics.se/dive/manual/tclref.html#dive_property_remove http://www.sics.se/dive/manual/tclref.html#dive_property_link

6. File interface

In the Dive .vr interface [2] properties can be created and set with initial values for some predefined types, namely TYPE_INT, TYPE_FLOAT and TYPE_STRING. If no initial values are given, any type can be used.

The file syntax is as follows (as a dive object sub declaration): 

     PROP prop_name prop_type prop_val prop_locality
     prop_name          : STRING
     prop_type          : STRING
     prop_val           : NUMBER
                        | FLOAT
                        | STRING
     prop_locality      : NUMBER

Locality can be LOCAL_PROP or GLOBAL_PROP if the "dive.vh" is included.

Example:

#include "dive.vh" 

     object {
         name "A"
         prop "name" TYPE_STRING "embraquel" GLOBAL_PROP
         prop "view" TYPE_INT    42          GLOBAL_PROP
     }

References

[1] The Dive/Tcl Behaviour Interface, Reference Document. Available at <http://www.sics.se/dive/manual/tcl-behaviour.html>

[2] Dive 3.2 file format interface

[3] The Dive/Tcl Reference manual, Reference Document. Available at <http://www.sics.se/dive/manual/tclref.html>