Direct Structures

Direct structures (generated by specifying the optional direct keyword) are an efficient optimization for C and C++ applications that can be applied to fixed sized class layouts; i.e. data layouts within a class without any dynamic objects (i.e. objects with fields of type string, rect, vector, varbinary and sequence), optional or nullable fields, or other struct fields; also direct structures cannot be stored in a vector. Direct structures organize data fields as structure elements and internally store data as a C-language struct.

A structure in eXtremeDB is a way of combining several data fields together. When a normal structure is defined for a class, the elements of that structure are accessed through the generated field-level _get() and _put() APIs. The benefit of using structures is to organize multiple logically related data fields together and map the database structure into the application’s internals (one example is creating a time series of multiple sequences). The overhead incurred by calling separate _get() functions to read or _put() functions to write all structure elements can be quite noticeable, especially when the number of structure elements or data fields is relatively high. In addition the application needs to call the field accessors many times, which is again quite inconvenient for a large number of fields or structure elements. One alternative approach is to use the _fixed_get() and _fixed_put() APIs, which allow reading and writing a number of fields (or even all of them) at once, mapping the DDL fields into the generated C structure. However this is a mere convenience, a shortcut for the application developer.

Actually, the DDL compiler generates two structures: one is packed (in the literal C sense using #pragma pack), the other is aligned to word-boundaries. The first structure is used to store the elements in the database. While interfacing with the application, the database runtime reads / writes each structure element from/to the storage and copies it into the other structure visible from the application.

In contrast, when a direct structure declaration is used, the DDL compiler creates a single C-language structure that is already padded so that its elements are aligned to the target word boundaries. The database dictionary references structure elements offsets that correspond to the offsets of the application’s C structure elements. This is achieved by calculating the target word size at the schema compile time.

As a result it is possible to keep the original C-language structure in the storage and access the structure as a whole in one read / write (as opposed to via the accessors API). Moreover, the elements of the structure can be indexed as usual, because the runtime refers to the field data through the dictionary specified offsets as if they were normal fields. Really the trick is to figure out the target architecture word size at the DDL compile time and to use it to calculate the structure field offsets.