Skip to content

dtobject

This is a facade layer for basic object operations such as creation, copying, disposal and string rendering.

Many diverse objects in the system implement this facade to provide a common interface for basic object management. It is espeicially useful for generic containers and utilities that need to manipulate objects without knowing their concrete types.

This facade is vtable-dispatched. Please refer to dtvtable for more information on vtable dispatching.

Mini-guide

  • For a class to implement this facade, it must register a dtobject_vt_t vtable for its model number and implement all the functions below.
  • To call the facade functions, pass the handle to the function cast as dtobject_handle.

Example Creation From Model Number

#include <dtcore/dtobject.h>

my_object_handle h = NULL;
dtobject_create(MODEL_NUMBER, (dtobject_handle_t*)&h);
dtobject_to_string((dtobject_handle_t)h, buffer, buffer_size);
dtobject_dispose((dtobject_handle_t)h);

Example Handle Sharing

#include <dtcore/dtobject.h>
#include <dtcore/dtrandomizer_uniform.h>

dtrandomizer_handle r = NULL;
// create a dtrandomizer_uniform object, which we know implements dtobject facade
dtrandomizer_uniform_create(&r);
// use dtobject facade to render it to string
dtobject_to_string((dtobject_handle_t)r, buffer, buffer_size);

Example Implementation

#include <dtcore/dtobject.h>

#define MODEL_NUMBER 1

static dterr_t* my_create(void* handle) { (void)handle; return NULL; }
static void my_copy(void* self, void* that) { (void)self; (void)that; }
static void my_dispose(void* self) { (void)self; }
static bool my_equals(void* self, void* that) { (void)self; (void)that; return true; }
static const char* my_get_class(void* self) { (void)self; return "my_t"; }
static bool my_is_iface(void* self, const char* iface_name) { (void)self; (void)iface_name; return false; }
static void my_to_string(void* self, char* buffer, size_t buffer_size) { (void)self; (void)buffer; (void)buffer_size; }

int main(void)
{
    dtobject_vt_t vt = {
        .create = my_create,
        .copy = my_copy,
        .dispose = my_dispose,
        .equals = my_equals,
        .get_class = my_get_class,
        .is_iface = my_is_iface,
        .to_string = my_to_string,
    };

    (void)dtobject_set_vtable(MODEL_NUMBER, &vt);

    dtobject_handle h = NULL;
    (void)dtobject_create(MODEL_NUMBER, &h);
    dtobject_dispose(h);

    return 0;
}

Data structures

dtobject_handle

Defines an opaque handle used for dispatch calls.

dtobject_vt_t

Defines the vtable used to dispatch object operations.

Members:

dtobject_create_fn create Create delegate for the model.
dtobject_copy_fn copy Copy delegate for the model.
dtobject_dispose_fn dispose Dispose delegate for the model.
dtobject_equals_fn equals Equality delegate for the model.
dtobject_get_class_fn get_class Class-name delegate for the model.
dtobject_is_iface_fn is_iface Interface test delegate for the model.
dtobject_to_string_fn to_string String rendering delegate for the model.

Macros

DTOBJECT_COMMON_MEMBERS

Defines common members required at the start of implementation structures.

DTOBJECT_DECLARE_API

DTOBJECT_DECLARE_API(NAME)

Declares a typed object API that maps to the common dispatch surface.

DTOBJECT_INIT_VTABLE

DTOBJECT_INIT_VTABLE(NAME)

Defines a vtable initializer that binds a typed API to the common vtable shape.

Functions

dtobject_copy

Dispatches a copy operation through the vtable for the handle model number.

Params:

dtobject_handle handle Object handle to copy into.
dtobject_handle that Object handle to copy from.

Return: void No return value.

dtobject_create

Dispatches a create operation through the vtable for a model number.

Params:

int32_t model_number Model number used to select a registered vtable.
dtobject_handle* handle Output location for the created handle.

Return: dterr_t* Error on failure, or NULL on success.

dtobject_dispose

Dispatches a dispose operation through the vtable for the handle model number.

Params:

dtobject_handle handle Object handle to dispose.

Return: void No return value.

dtobject_equals

Dispatches an equality operation through the vtable for the handle model number.

Params:

dtobject_handle handle First object handle to compare.
dtobject_handle that Second object handle to compare.

Return: bool True if equal, otherwise false.

dtobject_get_class

Dispatches a class-name query through the vtable for the handle model number.

Params:

dtobject_handle handle Object handle to query.

Return: const char* Class name string, or NULL on failure.

dtobject_get_vtable

Retrieves a registered vtable for a model number.

Params:

int32_t model_number Model number used to select a registered vtable.
dtobject_vt_t** vtable Output location for the vtable pointer.

Return: dterr_t* Error on failure, or NULL on success.

dtobject_is_iface

Dispatches an interface-membership query through the vtable for the handle model number.

Params:

dtobject_handle handle Object handle to query.
const char* iface_name Interface name to test.

Return: bool True if the interface is supported, otherwise false.

dtobject_set_vtable

Registers a vtable for a model number in the dispatch registry.

Params:

int32_t model_number Model number used to identify the vtable.
dtobject_vt_t* vtable Vtable to register for dispatch.

Return: dterr_t* Error on failure, or NULL on success.

dtobject_to_string

Dispatches a string rendering operation through the vtable for the handle model number.

Params:

dtobject_handle handle Object handle to render.
char *buffer Output buffer for the rendered string.
size_t buffer_size Size of the output buffer in bytes.

Return: void No return value.