CObject

Overview

Objects in the clingo context are memory allocated data with the extra cObjectInfo header. The cObjectInfo instance stores the information for the specific data instance, like reference counting. The referenced cMeta instance stores the information that all instances with the same type share.

CObject

Types and Definitions

c_ObjectConfig

enum c_ObjectConfig {
   c_Release = 1 << 0,
   c_Cleanup = 1 << 1,
   c_DefaultObject = c_Release | c_Cleanup,
};

typedef enum c_ObjectConfig c_ObjectConfig;

Enum type that defines the flags that can configurate the behaviour of an object.

c_Release

should the memory of the object be freed

c_Cleanup

should the cleanup function be called

c_DefaultObject

the default configuration for an object.

CObject

typedef void CObject;

A CObject pointer should only be used for data that is alloceted with the function alloc_object_c.

c_cleanup

typedef void ( *c_cleanup )( void* obj );

Type definition of a cleanup function to remove type specific data.

cMeta

struct cMeta
{
   char const* desc;
   c_cleanup cleanup;
};

typedef struct cMeta cMeta;

Stores information of that all instances of a type share. The attribute desc is a string that represents the content type, like CString for example. The cleanup function should also be the same for all instances of a type.

cObjectInfo

struct cObjectInfo
{
   uint32_t refs;
   uint8_t config;
   cMeta const* meta;
};

typedef struct cObjectInfo cObjectInfo;

Stores information for the specific instance. The refs stores the number of instances that share this object. The config value allows to stores flags for this instance. Finally is meta a pointer to the shared cMeta instance.

Functions

init

default_object_info_c_

#define default_object_info_c_( Meta )

Creates a cObjectInfo with the c_DefaultObject configuration. Meta is a pointer to the shared cMeta instance.

object_info_c_

#define object_info_c_( Meta, Config )

Creates a cObjectInfo with a individual configuration Config. Meta is a pointer to the shared cMeta instance.

lifecycle

new_object_c

#define new_object_c_( Type, Meta )                                            \
   new_object_c( sizeof_c_( Type ), Meta )
CObject* new_object_c( int64_t size, cMeta const meta[static 1] );

Allocates a CObject instance with a default cObjectInfo value.

alloc_object_c

#define alloc_object_c_( Type, Info )                                          \
   alloc_object_c( sizeof_c_( Type ), Info )
CObject* alloc_object_c( int64_t size, cObjectInfo const info[static 1] );

Allocates a CObject instance with the required overhead for the cObjectInfo instance.

init_object_c

CObject* init_object_c( void* mem, cObjectInfo const info[static 1] );

Initialises reserved memory as object with a specific info.

references_c

uint32_t references_c( const CObject* obj );

Returns the value of the refs counter.

release_all_c

#define release_all_c_( ... )                                                  \
   release_all_c( nargs_c_( __VA_ARGS__ ), __VA_ARGS__ )
void release_all_c( int n, ... );

Calls release_c on all(…​) objects. It is recommended to use the macro function.

release_c

CObject* release_c( CObject* obj );

Decrements the refs counter of obj. If the refs counter reaches 0 and the doCleanup flag is set calls the function the cleanup function of the cMeta instance.

retain_c

CObject* retain_c( CObject* obj );

Increments the refs counter of obj. The obj value can be NULL, this allows to chain method calls.

Example
CString* str = retain_c( new_string_c( "test" ) );

let_object_c

#define let_object_c_( Type, Meta )                                            \
   let_object_c( stack_mem_c_( sizeof_object_c_( Type ) ), (Meta) )
CObject* let_object_c( void* mem, cMeta const meta[static 1] );

Initialises reserved memory as object that will not be released.

Example
#include "clingo/lang/CObject.h"
#include "clingo/lang/expect.h"

struct Counter
{
   int64_t val;
};
typedef struct Counter Counter;

static void cleanup( void* instance )
{
   Counter* counter = instance;
   counter->val += 1;
}

cMeta const CounterMeta = {
   .desc = stringify_c_( Counter ),
   .cleanup = &cleanup
};

int main( void )
{
   init_tap_c_();

   Counter* counter = let_object_c_( Counter, &CounterMeta );
   expect_c_( counter->val == 0 );

   release_c( counter );
   expect_c_( counter->val == 1 );

   release_c( counter );
   expect_c_( counter->val == 2 );

   return finish_tap_c_();
}

touch_c

CObject* touch_c( CObject* obj );

Calls retain_c and release_c on obj.

object info

get_object_desc_c

char const* get_object_desc_c( CObject const* obj );

Util function to access the desc attribute of the linked cMeta instance.

get_object_info_c

cObjectInfo const* get_object_info_c( CObject const* obj );

Returns the cObjectInfo of the CObject instance obj.

sizeof_object_c_

#define sizeof_object_c_( Type )

Macro function that returns the memory size a object for a Type requires. The type of the returned value is int64_t.