typedef struct M_ObjectRec_*            M_Object;

handle to a M_ObjectRec structure, models an object (i.e. a class instance).

  typedef struct M_ObjectRec_
  {
    M_Class   clazz;
    M_Int     ref_count;

  } M_ObjectRec;

a structure used to describe a given class instance.

  typedef const struct M_ClassRec_*       M_Class;

handle to a constant M_ClassRec structure, used to model a class to the object system. Note that classes are _objects_ too and are allocated by the object sub-system.

classes are described by M_ClassType handles.

  typedef const struct M_ClassTypeRec_*   M_ClassType;

handle to a constant M_ClassTypeRec structure, used to describe a given class to the object system.

  typedef struct M_ClassTypeRec_
  {
    M_ClassType         super;
    M_CString           name;

    M_Size              class_size;
    M_UInt              class_flags;
    M_Class_InitFunc    class_init;
    M_Class_DoneFunc    class_done;

    M_Size              object_size;
    M_Object_InitFunc   object_init;
    M_Object_CopyFunc   object_copy;
    M_Object_IncrFunc   object_incr;
    M_Object_DoneFunc   object_done;

  } M_ClassTypeRec;

a structure used to describe a given class to the object system. class types must be unique, and they're used to allocate and manage M_Class objects.

  typedef void     (*M_Class_InitFunc)( M_Class    clazz );

initialize a new class object

before this function is called, the content of the parent's class is copied into the current one.

any exception

  typedef M_Bool   (*M_Class_DoneFunc)( M_Class   clazz );

finalizer a given class

a boolean, true if the parent class finalizer must _not_ be called..

any exception

  enum
  {
    M_CLASS_FLAG_NO_COPY      = 1,
    M_CLASS_FLAG_SINGLETON    = 2,
  };

bit flags used in class type descriptors

  typedef void  (*M_Object_InitFunc)( M_Object   object );

a function used to initialise a given object (i.e. class instance)

any exception

  typedef void     (*M_Object_CopyFunc)( M_Object   source,
                                         M_Object   copy );

a function used when an object is copied. m_object_copy will start by copying the root object instance, then call this method in order to manage child pointers / references

note that this will never be called for instances of classes that have the ?M_CLASS_FLAG_SINGLETON flag set.

this function should _only_ modify the copy, never the source

any exception

  typedef M_Bool   (*M_Object_IncrFunc)( M_Object  object,
                                         M_Int     increment );

a function used to increment or decrement the reference count of a given object. This is only used for instances of classes that have the ?M_CLASS_FLAG_CUSTOM_REF bit flag set.

this can be used to implement locking/unlocking during the reference count update for certain classes.

boolean. if true, indicates that the object must be destroyed.

the return value is only tested during a m_object_unref call, which means when "increment" == -1. If the object's reference count is not 0 at this time, the program will panic !!

any exception

  typedef M_Bool  (*M_Object_DoneFunc)( M_Object   object );

a function used to finalize a given object (i.e. class instance)

boolean. true when the parent object finalizer must _not_ be called

  typedef struct M_ClassRec_
  {
    M_Memory            memory;
    M_Core              mcore;
    M_ClassPool         class_pool;
    M_ULong             num_objs;
    M_UInt32            magic;
    M_ClassType         type;
    M_Class             super;
    M_ClassInfo         info;
    M_Pointer           data;

    M_Object_InitFunc   object_init;
    M_Object_DoneFunc   object_done;
    M_Object_CopyFunc   object_copy;
    M_Object_RefFunc    object_ref;

  } M_ClassRec;

a structure used to describe a given class. Note that classes are themselves objects..

normally, the "object_done" and "object_copy" fields are initialised by the "class_type" content. However, the class initialiser is capable of changing these functions if it wants to..

#define  M_OBJECT(x)    ((M_Object)(x))

a convenient macro used to convert a pointer to a M_Object .

#define  M_OBJECT_CHK(o)    M_OBJECT(M_OBJECT_CHECK_TYPE(o,NULL))

a convenient macro used to convert a pointer to a M_Object . on debug builds, it will panic if the parameter is not an object handle..

  MLIB_API(M_Pointer)
  m_object_new( M_Class   clazz );

create a new object (i.e. class instance), from a given class

handle to new object. cannot be NULL

any exception (e.g. m_err_memory_alloc )

the new object's reference count is set to 1

you can use m_class_from_type to retrieve a class handle from a given class type..

  MLIB_API(M_Pointer)
  m_object_new_from_type( M_Core       mcore,
                          M_ClassType  class_type,
                          M_Pointer    class_data );

create a new object (i.e. class instance), given its class type

any exception (e.g. m_err_memory_alloc )

the new object's reference count is set to 1

this function is slightly slower that m_object_new , but doesn't require a pre-determined class handle.

  MLIB_API(void)
  m_object_ref( M_Pointer object );

increment a given object's reference count

  MLIB_API(void)
  m_object_unref( M_Pointer object );

decrement a given object's reference count. it it reaches 0, the object is destroyed automatically..

  MLIB_API(M_Pointer)
  m_object_copy( M_Pointer object );

copy a given object.

object copy

any exception (e.g. m_err_memory_alloc )

the copy's reference count is set to 1

  MLIB_API(void)
  m_object_push( M_Pointer  object );

push an object on top of the cleanup stack

m_err_memory_alloc

  MLIB_API(void)
  m_object_pop( M_Pointer  object );

pops an object from the cleanup stack. do not unref/destroy it

  MLIB_API(void)
  m_object_pop_unref( M_Pointer  object );

pops an object from the cleanup stack, then unref it

  MLIB_API(M_Memory)
  m_object_get_memory( M_Pointer object );

retrieve the current memory manager handle from an object

memory manager handle

  MLIB_API(M_Core)
  m_object_get_core( M_Pointer object );

retrieve the current MLib core handle from an object

MLib core handle

  MLIB_API(M_Bool)
  m_object_is_a( M_Pointer    object,
                 M_ClassType  class_type );

checks wether an object is an instance of a given class type

boolean. true if the object's class is the one described by "class_info", or one of its children..

  MLIB_API(M_Bool)
  m_object_is_instance_of( M_Pointer  object,
                           M_Class    clazz );

checks wether an object is an instance of a given class

boolean. true if the object's class is the one described by "class_info", or one of its children..

  MLIB_API(M_Bool)
  m_object_check( M_Pointer  object )

checks at runtime that a pointer is really an object handle on debug builds, this will abort the program in case of error

#define  m_object_get_class(o)    M_OBJECT(o)->clazz

retrieve's an object's class

the object's class record

  typedef struct M_ClassPoolRec_*  M_ClassPool;

an opaque handle to the pool of classes in a given MLib core.

  typedef struct M_ClassInfoRec_*         M_ClassInfo;

opque handle to a M_ClassInfo structure. used internally by the object sub-system to store internal typermation about the class

#define  M_CLASS(x)  ((M_Class)(x))

a convenient macro to convert a pointer to a M_Class.

#define  M_CLASS_CHK(x)  M_CLASS( M_CLASS_CHECK_TYPE(x,NULL) )

a convenient macro to convert a pointer to a M_Class. On debug builds this also perform runtime info checks (which will abort the program if the pointer is not a valid class handle)

#define  m_assert_is_class(x)  M_CLASS_CHECK_TYPE(x,NULL)

checks at runtime that a given pointer is a class handle

  MLIB_API(M_Class)
  m_class_from_type( M_Core       mcore,
                     M_ClassType  class_type,
                     M_Pointer    class_data );

retrieves the class handle corresponding to a given class type

class handle, cannot be NULL

any (e.g. m_err_memory_alloc ..)

it's usually a good idea to store the result to use it with m_object_new

  MLIB_API(void)
  m_class_flush( M_Class  clazz );

this function is used to remove a given class from the class pool, and should seldom be used.

If one or more instances of the class exist, this function will _panic_ and abort the program..

this function should only be used when the class's implementation isn't available anymore, for example when unloading a dynamic module that implements a given class, m_class_flush must be called before removing its code from memory

  MLIB_API(M_Bool)
  m_class_is_a( M_Class      clazz,
                M_ClassType  class_type );

checks that a given class corresponds to a given class type

boolean, true if the class's info, or one of its super infos, correspond to the class type.

  MLIB_API(M_Bool)
  m_class_is_sub_of( M_Class  clazz,
                     M_Class  parent );

checks that a given class corresponds to a given class type. if not, aborts the program..

boolean. true if "class" is "parent" or any of its childs in the class hierarchy tree