Object Memory Managment

Defines
#define	OBJECT_OK   0
	OK (No Error).
#define	OBJECT_ERR_OUT_OF_MEMORY   1
	Out of memory.
#define	OBJECT_ERR_CLASS_REGISTERED   2
	Class already registered.
#define	OBJECT_ERR_CLASS_NOT_FOUND   3
	Class could not be found.
#define	ObjectRegisterType(_type)   ObjectRegisterClass(TOSTRING(_type), sizeof(_type), NULL)
	Helper macro to register a type as an object class.
#define	ObjectRegisterTypeDestructor(_type, _destructor)   ObjectRegisterClass(TOSTRING(_type), sizeof(_type), _destructor)
	Helper macro to register a type as an object class.
#define	ObjectCreate(_classname)   ObjectCreateImpl(_classname, __FILE__, __LINE__)
	Create a new object of class <classname>.
#define	ObjectCreateType(_type)   ObjectCreate(TOSTRING(_type))
	Helper macro to create a new object of the specfied type.
#define	ObjectRefInc(_ptr)   ObjectRefIncImpl(_ptr, __FILE__, __LINE__)
	Increment the reference count for the specified object.
#define	ObjectRefDec(_ptr)   ObjectRefDecImpl(_ptr, __FILE__, __LINE__)
	Decrement the reference count for the specified object.
#define	ObjectAlloc(_size)   ObjectAllocImpl(_size, __FILE__, __LINE__)
	Replacement for malloc, with the addition that it also clears the memory to zero.
#define	ObjectFree(_ptr)   ObjectFreeImpl(_ptr, __FILE__, __LINE__)
	Replacement for free.
Typedefs
typedef void(*	ObjectDestructor_t )(void *ptr)
	Type for a function to call when free'ing an object.
Functions
int	ObjectInit (void)
	Initialise object memory system.
int	ObjectDeinit (void)
	Deinitialise object memory system.
int	ObjectRegisterClass (char *classname, unsigned int size, ObjectDestructor_t destructor)
	Register a class of object to use with the ObjectCreate function.
void *	ObjectCreateImpl (char *classname, char *file, int line)
	Create a new object of class <classname>.
void	ObjectRefIncImpl (void *ptr, char *file, int line)
	Increment the reference count for the specified object.
bool	ObjectRefDecImpl (void *ptr, char *file, int line)
	Decrement the reference count for the specified object.
int	ObjectRefCount (void *ptr)
	Retrieve the current reference count of the specific object.
bool	ObjectIsObject (void *ptr)
	Queries the supplied pointer to determine if it is an object instance.
char *	ObjectGetObjectClass (void *ptr)
	Queries the supplied object pointer to determine the class of the object.
void *	ObjectAllocImpl (int size, char *file, int line)
	Replacement for malloc with the addition that it also clears the memory to zero.
void	ObjectFreeImpl (void *ptr, char *file, int line)
	Replacement for free.
void	ObjectDump (void *ptr)
	Print out debugging information about the object.

---

Define Documentation

#define OBJECT_ERR_CLASS_NOT_FOUND   3

Class could not be found.

#define OBJECT_ERR_CLASS_REGISTERED   2

Class already registered.

#define OBJECT_ERR_OUT_OF_MEMORY   1

Out of memory.

#define OBJECT_OK   0

OK (No Error).

#define ObjectAlloc

(

_size

)

ObjectAllocImpl(_size, __FILE__, __LINE__)

Replacement for malloc, with the addition that it also clears the memory to zero.

Parameters:

_size

Size of the block to allocated.

Returns:

Pointer to the new memory block or NULL.

#define ObjectCreate

(

_classname

)

ObjectCreateImpl(_classname, __FILE__, __LINE__)

Create a new object of class <classname>.

The initial reference count for the returned object will be 1.

Parameters:

_classname

Class of object to create.

Returns:

A pointer to the new object or NULL.

#define ObjectCreateType

(

_type

)

ObjectCreate(TOSTRING(_type))

Helper macro to create a new object of the specfied type.

Parameters:

_type

The new type of the object to create.

#define ObjectFree

(

_ptr

)

ObjectFreeImpl(_ptr, __FILE__, __LINE__)

Replacement for free.

Releases memory previously allocated by ObjectAlloc.

Parameters:

_ptr

The memory block to free.

#define ObjectRefDec

(

_ptr

)

ObjectRefDecImpl(_ptr, __FILE__, __LINE__)

Decrement the reference count for the specified object.

If the reference count reaches zero the object's class's destructor will be called and the memory freed.

Parameters:

_ptr

Pointer to the object to decrement the ref. count of.

Returns:

True if there are more references to the object, false if not.

#define ObjectRefInc

(

_ptr

)

ObjectRefIncImpl(_ptr, __FILE__, __LINE__)

Increment the reference count for the specified object.

Parameters:

_ptr

Pointer to the object to increment the ref. count of.

#define ObjectRegisterType

(

_type

)

ObjectRegisterClass(TOSTRING(_type), sizeof(_type), NULL)

Helper macro to register a type as an object class.

Parameters:

_type

The type to register with the object system.

#define ObjectRegisterTypeDestructor	(	_type,
		_destructor		)	ObjectRegisterClass(TOSTRING(_type), sizeof(_type), _destructor)

Helper macro to register a type as an object class.

Parameters:

	_type	The type to register with the object system.
	_destructor	Function to call when free'ing an object of the type being registered.

---

Typedef Documentation

typedef void(* ObjectDestructor_t)(void *ptr)

Type for a function to call when free'ing an object.

ptr is the pointer to the object being freed.

---

Function Documentation

void* ObjectAllocImpl	(	int	size,
		char *	file,
		int	line
	)

Replacement for malloc with the addition that it also clears the memory to zero.

Note:

This function should not be used instead the macro ObjectAlloc should be used.

Parameters:

	size	Size of the block to allocated.
	file	The file this function is being called from.
	line	The line this function is being called from.

Returns:

Pointer to the new memory block or NULL.

void* ObjectCreateImpl	(	char *	classname,
		char *	file,
		int	line
	)

Create a new object of class <classname>.

The initial reference count for the returned object will be 1.

Note:

This is the function should not be used instead the macro ObjectCreate should be used.

Parameters:

	classname	Class of object to create.
	file	The file this function is being called from.
	line	The line this function is being called from.

Returns:

A pointer to the new object or NULL.

int ObjectDeinit

(

void

)

Deinitialise object memory system.

Returns:

0 on success.

void ObjectDump

(

void *

ptr

)

Print out debugging information about the object.

Parameters:

ptr

Pointer to the object to dump information on.

void ObjectFreeImpl	(	void *	ptr,
		char *	file,
		int	line
	)

Replacement for free.

Releases memory previously allocated by ObjectAlloc.

Note:

This function should not be used instead the macro ObjectFree should be used.

Parameters:

	_ptr	The memory block to free.
	file	The file this function is being called from.
	line	The line this function is being called from.

char* ObjectGetObjectClass

(

void *

ptr

)

Queries the supplied object pointer to determine the class of the object.

Parameters:

ptr

Pointer to check.

Returns:

The name of the class of the object or NULL if a alloc'ed block.

int ObjectInit

(

void

)

Initialise object memory system.

Returns:

0 on success.

bool ObjectIsObject

(

void *

ptr

)

Queries the supplied pointer to determine if it is an object instance.

Parameters:

ptr

Pointer to check to see if it is an object pointer.

Returns:

True if the pointer is an object pointer, false otherwise.

int ObjectRefCount

(

void *

ptr

)

Retrieve the current reference count of the specific object.

Parameters:

ptr

Pointer to the object to get the reference count of.

Returns:

The reference count of the object.

bool ObjectRefDecImpl	(	void *	ptr,
		char *	file,
		int	line
	)

Decrement the reference count for the specified object.

If the reference count

Note:

This function should not be used instead the macro ObjectRefDec should be used.

Parameters:

	ptr	Pointer to the object to decrement the ref. count of.
	file	The file this function is being called from.
	line	The line this function is being called from.

void ObjectRefIncImpl	(	void *	ptr,
		char *	file,
		int	line
	)

Increment the reference count for the specified object.

Note:

This function should not be used instead the macro ObjectRefInc should be used.

Parameters:

	ptr	Pointer to the object to increment the ref. count of.
	file	The file this function is being called from.
	line	The line this function is being called from.

int ObjectRegisterClass	(	char *	classname,
		unsigned int	size,
		ObjectDestructor_t	destructor
	)

Register a class of object to use with the ObjectCreate function.

Parameters:

	classname	Name of the class being registered.
	size	Size of the memory need for the object.
	destructor	Function to call when the reference count reach zero for an object. This is only required if the object includes references to other object/malloc memory that needs to be freed.

Returns:

0 on success.