exstreamspeed Reference/es_mbc

References/es_mbc_new

Syntax

int es_mbc_new( struct es_mbd *def,
                const char *clsnm,
                int batchsize, 
                int itype,
                struct es_mbc *parent,
                struct es_mbc **res );

Arguments

`struct es_mbd *def`	A database definition.
`const char *clsnm`	Class name.
`unsigned batchsize`	Approximate number of rows to use in each node-batch.
`int itype`	Index type. Must be one of enumerated list of values below.
`struct es_mbc *parent`	Pointer to parent class, if applicable. NULL otherwise.
`struct es_mbc **res`	Assigned result, passed by reference.

Return Codes

`ES_ERROR_NONE`	Success. No errors.
`ES_ERROR_INVALIDBATCHSIZE`	`batchsize` is <= 0.
`ES_ERROR_CLASSEXISTS`	Class name already exists in database.
`ES_ERROR_INDEXCLASSEXISTS`	Name of hidden class created for shared index already exists in database - see `ES_INDEX_SHARED`.
`ES_ERROR_UNKNOWNINDEXTYPE`	Invalid index type.

Description

Constructs a new class with respect to a database definition (struct es_mbs *def) and class name (const char *clsnm). There is no rule regarding class name identifiers.

New classes can also be constructed by extending the definition of an existing class via es_mbc_newsub().

Batch Sizes

A node instance of a class contain rows of data. These rows are broken up into batches, where each batch represents the smallest unit of memory allocated per node. The batchsize parameter controls the approximate number of rows used in each batch.

Appropriate choice of batchsize can greatly effect the performance and memory efficiency of the database. Smaller batch sizes will improve memory efficiency, through reduced fragmentation, but may slow down mass insert and filtering/scanning operations. In general, a batch size should be chosen that is appropriate for the perceived average node size. Query and update performance does not improve materially beyond certain maximum batchsizes, however, so a certain amount of experimentation is recommended in optimizing performance.

[Top]

Index Types

Each class requires an index type (int itype). Associated with an index is a sequence of one or more integer-based index fields, which may be added to the class via es_mbc_addfldidx. Index types may be one of the following:

ES_INDEX_NONE This method has constant-time lookup, akin to simple array indexing. It is the fastest method. It is designed to be used with string dictionary identifiers and date-ids which are guaranteed to fall in a tight range. Classes with this index type may have at most one index field . If a class has no index fields, then data may be inserted via es_mbi_insert.

ES_INDEX_PRIVATE This method incorporates a fast hashing scheme that works for a variable number of index fields. Classes with this index must have at least one index field. Ordering of index fields is important. Placing the field with the smallest domain of values first in the list may improve performance. If the pattern of access ensures a locality of value for some particular field (due to sorting of an input stream, for example) then placing that field first in the list may also improve performance.

ES_INDEX_SHARED This method is identical to the ES_INDEX_PRIVATE method except that the values for the index fields are stored in a seperate singleton node. The index is shared amongst all node instances of this class. A seperate, hidden class is created automatically for the index fields. The hidden class has the same class-name with a postfix of "__Index".

[Top]

Parent Class

A class may be designated as a child of some other parent class (struct es_mbc *parent). In this case a field is automatically added to the parent class with a field name the same as the child class name (const char *clsnm) with a bound type of struct es_mbn* ( i.e. a node ).

A class may be designated as a root class - i.e. a class with no parent (struct es_mbc *parent = NULL). Root nodes are automatically constructed when a database instance is constructed via es_mb_new(). Root nodes may be retrieved via es_mb_getnode(). Child nodes must be constructed explicitly via es_mbn_new().

  /* construct "Parent" class as a root class */
  struct es_mbc *c_parent;
  es_mbc_new( schema, "Parent", 100, ES_INDEX_NONE, NULL, &c_parent );

  /* construct "Child" class as a child of "Parent" class -
     "Parent" now has a field called "Child" */
  struct es_mbc *c_child;
  es_mbc_new( schema, "Child", 100, ES_INDEX_NONE, c_parent, &c_child );

[Top]

[Back To Reference] [Back To Reference/es_mbc]