Managed Objects
[Data Structures and Representations]

---

Detailed Description

Buffers with reference counting and automated cloning and collection.

Managed objects at low-level are void* buffers with a prefix. To create a managed buffer, one must provide the buffer size and the following two routines : _clone() and _deinit().

_clone() should duplicate the buffer given as a parameter and _deinit() should free the resources associated with the buffer, but not the buffer itself.

Once a buffer is created, the Virtual Machine manages its reference counter and automatically collects unreferenced buffers.

Buffers are to be _clone 'd when enclosing their reference in Function objects (dynamic functions).

Collector

Currently, the GC collects at most one buffer per instruction cycle and has not been tested under heavy load.

This might change anytime in function of the needs.

Data Structures
struct	_vm_obj_t
Defines
#define	VM_OBJ_OFS   sizeof(struct _vm_obj_t)
	size of the object header
#define	PTR_TO_OBJ(_x)   ((vm_obj_t)(((char*)(_x))-VM_OBJ_OFS))
	translate from a managed buffer to its object header
#define	OBJ_TO_PTR(_x)   ((void*)(((char*)(_x))+VM_OBJ_OFS))
	translate from an object header to its managed buffer
#define	VM_OBJ_MAGIC   0x61060000
	magic value for managed objects : bit pattern
#define	VM_OBJ_MASK   0xFFFF0000
	magic value for managed objects : bit mask
#define	_obj_type(_x)   (((vm_obj_t)(_x))->magic^VM_OBJ_MAGIC)
	retrieve the type of managed object (DataObj* constant)
#define	_is_obj_obj(_x)   (((_x)&&(((_x)->magic&VM_OBJ_MASK) == VM_OBJ_MAGIC)) || (vm_printerrf("Data at %p is not a managed object (magic = %8.8lX)\n",(_x),(_x)?(_x)->magic:0) && 0))
	assertions
#define	_is_a_obj(_x, _t)   (_is_obj(_x) && (_obj_type(_x)==(_t)))
#define	_is_obj_ptr(_x)   ((_x)&&((PTR_TO_OBJ(_x)->magic&VM_OBJ_MASK) == VM_OBJ_MAGIC))
#define	_is_a_ptr(_x, _t)   (_is_obj_ptr(_x) && (_obj_type(PTR_TO_OBJ(_x))==(_t)))
Typedefs
typedef struct _vm_obj_t *	vm_obj_t
	A managed object.
typedef struct _vm_dyn_env_t *	vm_dyn_env_t
	A map.
typedef struct _vm_dyn_func_t *	vm_dyn_func_t
	A function object.
Functions
static void *	vm_obj_new (word_t struc_size, void(*_free)(vm_t, void *), void *(*_clone)(vm_t, void *), vm_data_type_t obj_type)
	allocate a new managed buffer.
static void	vm_obj_free_obj (vm_t vm, vm_obj_t o)
	free a managed object.
static vm_obj_t	vm_obj_clone_obj (vm_t vm, vm_obj_t o)
	clone an object
static word_t	vm_obj_refcount_ptr (void *ptr)
	get the reference count for object ptr
static void	vm_obj_ref_ptr (vm_t vm, void *ptr)
	increase reference count for ptr
static void	vm_obj_deref_ptr (vm_t vm, void *ptr)
	decrease reference count for ptr and collect object if necessary
char *	vm_string_new (const char *src)
	create a new managed string containing a copy of src
char *	vm_string_new_buf (word_t sz)
	create a new managed string of length sz
text_seg_t	vm_symtab_new ()
	create a new symbol table ( [symbol] => index not null )
mutex_t	vm_mutex_new ()
	create a new mutex
thread_t	vm_thread_new (vm_t vm, word_t prio, program_t p, word_t ip)
	create a new thread
dynarray_t	vm_array_new ()
	create a new dynamic array
vm_dyn_env_t	vm_env_new ()
	create a new map ( symbol table + array)
generic_stack_t	vm_stack_new ()
	create a new stack
vm_dyn_func_t	vm_dyn_fun_new ()
	create a new function object

---

Define Documentation

#define VM_OBJ_OFS   sizeof(struct _vm_obj_t)

size of the object header

#define PTR_TO_OBJ

(

_x

)

((vm_obj_t)(((char*)(_x))-VM_OBJ_OFS))

translate from a managed buffer to its object header

#define OBJ_TO_PTR

(

_x

)

((void*)(((char*)(_x))+VM_OBJ_OFS))

translate from an object header to its managed buffer

#define VM_OBJ_MAGIC   0x61060000

magic value for managed objects : bit pattern

#define VM_OBJ_MASK   0xFFFF0000

magic value for managed objects : bit mask

#define _obj_type

(

_x

)

(((vm_obj_t)(_x))->magic^VM_OBJ_MAGIC)

retrieve the type of managed object (DataObj* constant)

#define _is_obj_obj

(

_x

)

(((_x)&&(((_x)->magic&VM_OBJ_MASK) == VM_OBJ_MAGIC)) || (vm_printerrf("Data at %p is not a managed object (magic = %8.8lX)\n",(_x),(_x)?(_x)->magic:0) && 0))

assertions

#define _is_a_obj	(	_x,
		_t		)	(_is_obj(_x) && (_obj_type(_x)==(_t)))

#define _is_obj_ptr

(

_x

)

((_x)&&((PTR_TO_OBJ(_x)->magic&VM_OBJ_MASK) == VM_OBJ_MAGIC))

#define _is_a_ptr	(	_x,
		_t		)	(_is_obj_ptr(_x) && (_obj_type(PTR_TO_OBJ(_x))==(_t)))

---

Typedef Documentation

typedef struct _vm_obj_t* vm_obj_t

A managed object.

typedef struct _vm_dyn_env_t* vm_dyn_env_t

A map.

typedef struct _vm_dyn_func_t* vm_dyn_func_t

A function object.

---

Function Documentation

static void* vm_obj_new	(	word_t	struc_size,
		void(*)(vm_t, void *)	_free,
		void *(*)(vm_t, void *)	_clone,
		vm_data_type_t	obj_type
	)			[inline, static]

allocate a new managed buffer.

Parameters:

	struc_size	the size of the buffer to allocate
	_free	a routine that will be called just before freeing the buffer
	_clone	a routine that will be called to clone an object (used when initializing a closure for instance)
	obj_type	any DataObj* constant (see DataObjUser).

static void vm_obj_free_obj	(	vm_t	vm,
		vm_obj_t	o
	)			[inline, static]

free a managed object.

Note:

you should let the VM do its job and never call this routine

static vm_obj_t vm_obj_clone_obj	(	vm_t	vm,
		vm_obj_t	o
	)			[inline, static]

clone an object

static word_t vm_obj_refcount_ptr

(

void *

ptr

)

[inline, static]

get the reference count for object ptr

static void vm_obj_ref_ptr	(	vm_t	vm,
		void *	ptr
	)			[inline, static]

increase reference count for ptr

static void vm_obj_deref_ptr	(	vm_t	vm,
		void *	ptr
	)			[inline, static]

decrease reference count for ptr and collect object if necessary

char* vm_string_new

(

const char *

src

)

create a new managed string containing a copy of src

char* vm_string_new_buf

(

word_t

sz

)

create a new managed string of length sz

text_seg_t vm_symtab_new

(

)

create a new symbol table ( [symbol] => index not null )

mutex_t vm_mutex_new

(

)

create a new mutex

thread_t vm_thread_new	(	vm_t	vm,
		word_t	prio,
		program_t	p,
		word_t	ip
	)

create a new thread

dynarray_t vm_array_new

(

)

create a new dynamic array

vm_dyn_env_t vm_env_new

(

)

create a new map ( symbol table + array)

generic_stack_t vm_stack_new

(

)

create a new stack

vm_dyn_func_t vm_dyn_fun_new

(

)

create a new function object

---