typedef struct M_CoreRec_*      M_Core;

a handle to a given top-level MLib core context object. There must be only one core context per process..

  typedef struct M_CoreRec_
  {
    M_Memory    memory;
    M_Pointer   impl;

  } M_CoreRec;

a core object is used to model a given context/instance of the MLib. there shouldn't be more than one core per program/process using the MLib (except maybe for debugging reasons).

  MLIB_API(M_Error)    m_core_new( M_Memory      memory,
                                   M_Core_Class  clazz,
                                   M_Pointer     impl_data,
                                   M_Core       *amcore );

this function creates a new MLib core object from a given memory manager. Don't call it directly, use ?mlib_init instead

error code. 0 means success

if a memory manager handle is provided, the function m_memory_ref is called to increment its reference count.

otherwise, a new standard/default memory manager is created through the function m_memory_new

note that a valid "clazz" handle is required if you want to use a thread-safe MLib core. Otherwise, the core assumes that only a single thread will access it..

  MLIB_API(void)       m_core_ref( M_Core  mcore );

increment the internal reference count within a MLib core object

  MLIB_API(void)       m_core_unref( M_Core  mcore );

decrement the internal reference count within a MLib core object. if it reaches 0 or below, the core is destroyed..

  MLIB_API(void)       m_core_push( M_Core         mcore,
                                    M_Pointer      item,
                                    M_CleanupFunc  cleanup_func,
                                    M_Pointer      cleanup_data );

push a new item on the current thread's cleanup stack. this function generates an exception is there isn't enough memory to allocate a stack slot.

m_err_memory_alloc

client applications should not call this function, unless they know exactly what they do. Rather, try to use the context specific functions like ?m_memory_push, m_object_push , ?m_object_array_push, etc.. as they're significnatly easier to use

  MLIB_API(void)       m_core_pop ( M_Core     context,
                                    M_Pointer  item,
                                    M_Bool     keep_it );

pop a given item from the current thread's clean-up stack.

this function will _panick_ (i.e. abort your program) if the top-most element of the stack doesn't correspond to the item passed as the 2nd parameter.

  MLIB_API(void)       m_core_throw( M_Core       mcore,
                                     M_Exception  exception );

throws an exception in current thread

  MLIB_API(void)       m_core_rethrow( M_Core       mcore,
                                       M_Exception  exception );

re-throws an exception. this function should only be used within a ?m_xcatch .. ?m_xend block.

it's possible to raise a different exception than the one that was caught in the "catch" statements. In this case, the "old" exception is released, and the new one is used..

  typedef void  (*M_FatalHandlerFunc)( M_Core       mcore,
                                       M_Exception  exception,
                                       M_Pointer    data );

a function called when a fatal exception is raised. An exception is considered fatal when it isn't handled by the program. The fatal exception handler can be set in any thread by first calling m_core_set_fatal_handler .

  MLIB_API(void)  m_core_set_fatal_handler(
                            M_Core              mcore,
                            M_FatalHandlerFunc  fatal_handler,
                            M_Pointer           fatal_data );

set the fatal exception handler for the current thread.

an out-of-memory exception can be raised by this function (mainly because there isn't enough memory to allocate a new thread data record within the MLib context)

in this case, the handler will be called directly.

do not try to do stupid things in the fatal handler like jumping to another thread. Its purpose is to allow you to write a semi-intelligent message before completely quiting the current thread or program..

you can call this function repeatedly to reset the fatal handler if you want to.

if no default fatal handler is set, the program will simply trap in the case of an un-handled exception.

  MLIB_API(void)       m_core_set_xhandler( M_Core      mcore,
                                            M_XHandler  handler );

pushes a new exception handler for the current thread. this function should not be called directly by applications, but by the M_XTRY macro.

  MLIB_API(M_Exception)  m_core_unset_xhandler( M_Core      mcore,
                                                M_XHandler  xinfo );

unsets a given exception handler for the current thread. this function should not be called directly by applications but by the M_XCATCH and M_XEND macros.

exception pointer in xinfo. can be NULL

  typedef M_CPointer    M_ThreadID;