Base Classes

Depending on what functionality your instanced data type needs, it will typically be derived from 1 of 3 builtin types, which form a hierarchy. Each layer of the hierarchy adds functionality but also increases the size of the type instance and type class structures.

GblInstance

An Instance simply represents an object that can be created from a given GblType which shares some data with other instances of the same type, located within their class.

GblInstance is the base structure which is to be inherited by instances of all instantiable types. This means placing it or a type inheriting from it as the first member of an instance struct.

Note: As the root instantiable type, an instance contains nothing but a pointer to its corresponding class. Its as lightweight as possible.

See also: GblClass, GblType, GblBox, GblObject

GblBox

A GblBox is a GblInstance-derived type which simply adds the bare minimal set of functionality that is typically required for language bindings and interop. This includes:

destructors
reference counting semantics
a dictionary for storing arbitrary associated userdata
interop with GblVariant types
arbitrary flag bits

Note: A GblBox is 12 or 20 bytes total (32 or 64 bit respectively).

See also: GblBoxClass

GblObject

A GblObject is the default, full-blown object-oriented instantiable type. It is analogous to Qt's "QObject" or GNOME's "GObject" root type. It extends GblBox to add the following additonal functionality:

properties
GblVariant table operations
constructor / post-constructor
event handling and filtering
object parenting and hierarchy
object name

Note: A GblObject by default has the same size of a GblBox. Additional data for fields such as name, parent, children, event filters, etc are created lazily and are stored within GblBox::pFields.

See also: GblBox, GblObjectClass, GblProperty

Private Data

All libGimbal type instance and type class structures are capable of encapsulating and hiding private data within them. During type registration, the sizes for additional private structures may be provided to GblTypeInfo::classPrivateSize and GblTypeInfo::instancePrivateSize. Using this approach, private structures may be hidden from the types' public headers, similar to C++'s PIMPL idiom.

Object Layout

Unlike C++'s PIMPL idiom, which requires a separate heap allocation for private data and additional indirection, libGimbal uses a single, contigous allocation for both an object's public and private data.

Inherited public data grows downwards, as with traditional OO inheritance schemes; however, inherited private data grows upwards in the opposite direction. "Casting" between the public and private structures is then a simple matter of the type system adjusting a pointer by a fixed offset.

+-----------+
| C Private |
+-----------+
| B Private |
+-----------+
| A Private |
+-----------+  <----- object pointer is here!!!
| A Public  |
+-----------+
| B Public  |
+-----------+
| C Public  |
+-----------+