typedef const struct M_ExceptionRec_*     M_Exception;

a handle to a given M_ExceptionRec record, used to model a given run-time exception.

M_Exception is always a pointer to a _constant_ exception record.

  typedef struct M_ExceptionRec_
  {
    M_ExceptionFamily    family;
    M_UInt               value;

  } M_ExceptionRec;

a structure used to model a given

#define  M_XTRY_CORE(mcore)                                                  \
            {                                                                \
              M_XHandlerRec  __xhandler;                                     \
                                                                             \
              m_core_set_xhandler( mcore, &__xhandler );                     \
              if ( !__xhandler.exception && setjmp( __xhandler.env ) == 0 )  \
              {

a macro used in association with ?m_xend to specify a set of instructions that will be tried for exceptions..

the "context" parameter must be a valid MLib Context handle..

#define  M_XTRY  M_XTRY_CORE(mcore)

this macro is a simpler variant of ?m_xtry_core that uses an implicit "mcore" variable to address the MLib core context..

#define  M_XCATCH( _e_ )                                                  \
              }                                                           \
              else                                                        \
              {                                                           \
                M_Exception   _e_ =                                       \
                      m_core_unset_xhandler( __xhandler.mcore, &__xhandler );

a macro used to begin an exception-handling section of code. the section _must_ ended with a ?m_xend

#define  M_XCATCH_ANY      M_XCATCH( __exc_e )

a macro similar to ?m_xcatch, except that the exception code is not returned in the catch statement.

#define  M_XEND                                                          \
              }                                                          \
              if ( __xhandler.exception )                                \
                m_core_unset_xhandler( __xhandler.mcore, &__xhandler );  \
            }

a macro used in association with ?m_xtry to specify a set of instructions that will be tried for exceptions..

#define  M_XTHROW_CORE( _e_, _mcore_ )       m_core_throw( _mcore_, _e_ )

a macro used to throw an exception within a given MLib core context

#define  M_XTHROW( _e_ )     m_core_throw( mcore, _e_ )

a macro used to throw an exception, using the _implicit_ "mcore" variable for the MLib core context

#define  M_XRETHROW_CORE( _e_, _mcore_ )   m_core_rethrow( _mcore_, _e_ )

a macro used to re-throw an exception, i.e. throw a new one when you're in a M_XCATCH .. M_XEND statement block..

#define  M_XRETHROW( _e_ )     M_XRETHROW_CORE( _e_, mcore )

a variant of M_XRETHROW that uses the implicit "mcore" variable for the MLib core handle

  typedef const struct M_ExceptionFamilyRec_*   M_ExceptionFamily;

a handle to an _constant_ exception family object. An exception family is used to describe ... a given family of exceptions !!. it also provides text that is dumped when an exception occurs..

  typedef struct M_XHandlerRec_*  M_XHandler;

a handle to an exception handler structure, see M_XHandlerRec . This type is not opaque, but application should ignore it..

  typedef struct M_XContextRec_*   M_XContext;

a handle to a thread-specific exception context object. Used to hold a cleanup stack, current and fatal execption handlers, as well as a few other things..

this type is opaque

  typedef const struct M_XMarkRec_*      M_XMark;

an opaque handle type. it is used to store the current size of the cleanup stack in exception handlers

  typedef struct M_XHandlerRec_
  {
    M_XHandler     previous;
    M_Core         mcore;
    M_Exception    exception;
    M_XContext     xcontext;
    M_XMark        xmark;
    jmp_buf        env;

  } M_XHandlerRec;

a structure used to hold information during a M_XTRY .. M_XEND block..

  MLIB_API_VAR( const M_ExceptionFamilyRec )   mlib_exception_family;

a constant used to address the family of all MLib-specific exceptions. These are:

m_err_parameter_check ,

m_err_memory_alloc ,

m_err_mutex_init , m_err_mutex_lock m_err_mutex_unlock

m_err_synlock_init m_err_synlock_lock m_err_synlock_unlock

m_err_rwlock_init m_err_rwlock_read_begin m_err_rwlock_read_end m_err_rwlock_write_begin m_err_rwlock_write_end

?m_err_stream_open, ?m_err_stream_seek ?m_err_stream_read ?m_err_stream_write

  MLIB_API_VAR( M_Exception )   m_err_mutex_init;

m_err_mutex_init

?description; this exception is thrown by m_mutex_new when allocating a new mutex isn't possible

  MLIB_API_VAR( M_Exception )   m_err_mutex_lock;

m_err_mutex_lock

?description; this exception is thrown by m_mutex_lock when locking a given mutex isn't possible (usually, this means a dangling mutex handle)

  MLIB_API_VAR( M_Exception )   m_err_mutex_unlock;

m_err_mutex_unlock

?description; this exception is thrown by m_mutex_lock when unlocking a given mutex isn't possible (usually, this means that the mutex wasn't locked by the current thread)

  MLIB_API_VAR( M_Exception )   m_err_synlock_init;

m_err_synlock_init

?description; this exception is thrown by m_synlock_new when allocating a new synlock isn't possible

  MLIB_API_VAR( M_Exception )   m_err_synlock_lock;

m_err_synlock_lock

?description; this exception is thrown by m_synlock_lock when locking a given synlock isn't possible (usually, this means a dangling synlock handle)

  MLIB_API_VAR( M_Exception )   m_err_synlock_unlock;

m_err_synlock_unlock

?description; this exception is thrown by m_synlock_lock when unlocking a given synlock isn't possible (usually, this means that the synlock wasn't locked by the current thread)

  MLIB_API_VAR( M_Exception )   m_err_rwlock_init;

m_err_rwlock_init

?description; this exception is thrown by m_rwlock_new when allocating a new rwlock isn't possible

  MLIB_API_VAR( M_Exception )   m_err_rwlock_read_begin;

m_err_rwlock_read_begin

?description; this exception is thrown by m_rwlock_read_begin when locking a given rwlock isn't possible (usually, this means a dangling rwlock handle)

  MLIB_API_VAR( M_Exception )   m_err_rwlock_read_end;

m_err_rwlock_read_end

?description; this exception is thrown by m_rwlock_read_end when unlocking a given rwlock isn't possible (usually, this means that the rwlock wasn't locked by the current thread)

  MLIB_API_VAR( M_Exception )   m_err_rwlock_read_begin;

m_err_rwlock_write_begin

?description; this exception is thrown by m_rwlock_write_begin when locking a given rwlock isn't possible (usually, this means a dangling rwlock handle)

  MLIB_API_VAR( M_Exception )   m_err_rwlock_read_end;

m_err_rwlock_write_end

?description; this exception is thrown by m_rwlock_write_end when unlocking a given rwlock isn't possible (usually, this means that the rwlock wasn't locked by the current thread)

  typedef void (*M_CleanupFunc)( M_Pointer  item,
                                 M_Pointer  cleanup_data );

a function pointer to a cleanup routine for a given item type

  MLIB_API_VAR( M_Exception )  m_err_parameter_check;

m_err_parameter_check

?description; this exception is thrown when certain functions receive an invalid parameter (for example, a NULL handle).

it is normally _only_ compiled in debug builds of the MLib