typedef struct M_MemoryRec_*      M_Memory;

a handle to a given memory manager.

  MLIB_API(M_Memory)  m_memory_new( void );

allocate a new _standard_ memory manager that uses the ANSI malloc/realloc/free

handle to new memory manager object. NULL in case of error

?m_memory_new_custom can also be used to create a custom memory manager. it is defined in the internal header file MLIB_INTERNAL_MEMORY_H

  MLIB_API(void)       m_memory_ref( M_Memory   memory );

increment the reference count of a given memory manager.

  MLIB_API(void)       m_memory_unref( M_Memory   memory );

decrement the reference count of a given memory manager if the count reaches 0 or below, the manager is destroyed

#define    m_mem_set( dest, byte, count )    \
              memset( (char*)(dest), (char)(byte), count )

a convenient macro to call the ANSI "memset"

#define    m_mem_copy( dest, source, count )   \
              memcpy( (char*)(dest), (char*)(source), count )

a convenient macro to call the ANSI "memcpy"

#define    m_mem_move( dest, source, count )   \
              memmove( (char*)(dest), (char*)(source), count )

a convenient macro to call the ANSI "memmove"

  MLIB_API(M_Pointer)    m_mem_alloc( M_Memory   memory,
                                      M_Size     size );

allocates a single memory block

a pointer to the new memory block. NULL iff size == 0

?m_exception_out_of_memory, when there is not enough available memory to satisfy the request, and when the memory's "context" field is set appropriately.

otherwise, this function will panic and abort the current program in case of memory shortage

the returned memory block is always zero-filled !!

  MLIB_API(void)    m_mem_realloc( M_Memory   memory,
                                   M_Size     cur_size,
                                   M_Size     new_size,
                                   M_Pointer *apointer );

reallocates a given memory block

m_exception_out_of_memory

if you're expanding a memory block, its new content will always be zero-filled..

  MLIB_API(void)  m_mem_free   ( M_Memory   memory,
                                 M_Pointer *apointer );

releases a given memory block

  MLIB_API(void)  m_mem_push ( M_Memory    memory,
                               M_Pointer   block );

push a given block of memory on top of the current thread's cleanup stack. It will be released by a call to ?m_mem_pop_destroy or in case of exception.

this function does nothing if "block" is NULL

this function will panic if the memory manager isn't linked to a MLib context

  MLIB_API(void)   m_mem_pop  ( M_Memory   memory,
                                M_Pointer  block,
                                M_Bool     keep_it );

pops a previously pushed memory block from the clean-up stack. the block isn't destroyed

this function does nothing if "block" is NULL

#define    M_ALLOC(size)   m_mem_alloc( memory, size )

allocates a new memory block, using the _implicit_ memory manager handle named "memory" (it must be defined prior to the macro call).

address of new memory block, just like m_mem_alloc

#define    M_FREE(p)   \
             m_mem_free( memory, (M_Pointer*)&(p) )

reallocates a given memory block whose address is in the "ptr" variable.

error code. 0 means success

this macro is more convenient than m_mem_free because it uses an _implicit_ memory manager handle named "memory" and automatically performs a typecast of "&.ptr" to (M_Pointer*)

this also means that "ptr" will always be NULL after the M_FREE

#define    M_REALLOC(p,cur_size,new_size)  \
             m_mem_realloc( memory, cur_size, new_size, (M_Pointer*)&(p) )

reallocates a given memory block whose address is in the "ptr" variable. Returns an error code or throws an exception

this macro is more convenient to use than m_mem_realloc because it uses an _implicit_ memory manager handle named "memory" (that must be defined prior to the macro call) and automatically performas a typecast of "&.ptr" to (M_Pointer*)

note that this macro doesn't return a value, unlike M_ALLOC

#define    M_NEW(p)                             \
             M_BEGIN_STMNT                      \
               (p) = M_ALLOC( sizeof(*(p)) );   \
             M_END_STMNT

this macro is used to allocate a new object. the type of "ptr" is used automatically to determine the size in bytes of the new object

#define    M_NEW_ARRAY(p,count)                             \
              M_BEGIN_STMNT                                 \
                 (p) = M_ALLOC( (count)*sizeof(*(p)) );     \
              M_END_STMNT

this macro is used to allocate a new table of "count" objects. the type of "ptr" is used automatically to determine the size in bytes of each element

error code. 0 means success

#define    M_RENEW_ARRAY(p,old,new) \
               M_REALLOC(p,(old)*sizeof(*(p)),(new)*sizeof(*(p)))

this macro is used to reallocate a table of "old_count" elements into a table of "new_count" elements.

the type of "ptr" is used automatically to determine the size in bytes of each element

#define  M_ALLOC_PUSH(size)  m_mem_alloc_push( memory, size )

a convention macro that calls m_mem_alloc_push with an _implicit_ 'memory' manager variable.

address of new memory block, just like m_mem_alloc_push

#define  M_POP(p)        m_mem_pop( memory, p, TRUE )

pop a memory block from the cleanup stack. Do _not_ release it.

this macro should only be used as a shortcut to m_mem_pop . it cannot pop other types of objects from the cleanup stack..

#define  M_POP_FREE(p)                       \
           M_BEGIN_STMNT                     \
             m_mem_pop( memory, p, FALSE );  \
             (p) = 0;                        \
           M_END_STMNT

pops a memory block from the cleanup stack, then release it.

"ptr" will always be set to NUMM after the call..

  typedef struct M_MemoryRec_
  {
    M_Core         mcore;
    M_Pointer      impl;

  } M_MemoryRec;

a memory manager object structure

each new manager created with m_memory_new will have its "mcore" field set to 0. An application should _never_ set or change it.

instead, the function m_core_new (and ?mlib_init) will set it to the appropriate value..

  MLIB_API(M_Pointer)  m_mem_dup( M_Memory   memory,
                                  M_Pointer  block,
                                  M_Size     size,
                                  M_Bool     push );

duplicate a given block of memory (allocate a new one, copy old content to it)

new memory block

  MLIB_API(void)  m_mem_alloc_batch( M_Memory    memory,
                                     M_UInt      count,
                                     M_Size*     sizes,
                                     M_Pointer*  pointers );

allocate several memory blocks at once

?m_err_mem_alloc

this function only returns when all memory blocks could be allocated.

otherwise, an exception is raised (and blocks that were allocated before the memory shortage are freed).

  MLIB_API(M_Pointer)  m_mem_alloc_push ( M_Memory    memory,
                                          M_Size      size );

creates a new memory block and push it on the cleanup stack.

pointer to new memory block. cannot be NULL

m_err_out_of_memory

this function will panic if the memory manager isn't linked to a MLib context

#define    M_ALLOC_BATCH(_count,_sizes,_pointers)   \
             m_mem_alloc_batch( memory,  (_count), (_sizes), (_pointers) )

this macro is used as a short-cut to m_mem_alloc_batch

#define  M_NEW_PUSH(p)    M_NEW_ARRAY_PUSH(p,1)

this macro is used to allocate a new "object" then push it on the cleanup stack. the type of "ptr" is used automatically to determine the size in bytes of the new object.

#define  M_NEW_ARRAY_PUSH(p,count)                          \
           M_BEGIN_STMNT                                    \
             (p) = M_ALLOC_PUSH( (count)*sizeof(*(p)));     \
           M_END_STMNT

this macro is used to allocate a new array of objects, then push it on the cleanup stack. the type of "ptr" is used automatically to determine the size in bytes of each array element.

  MLIB_API(M_Pointer)  m_mem_alloc_internal( M_Memory  memory,
                                             M_Size    size );

a function used to quickly allocate a block of memory from a given memory manager. The content of the new block is _not_ zero-ed. Also, the function returns NULL in case of memory shortage as it never throws an exception

address of new block, of NULL

  MLIB_API(void)       m_mem_free_internal( M_Memory   memory,
                                            M_Pointer  block );

a function used to quickly free a block of memory from a given memory manager.

  MLIB_API_VAR( M_Exception )  m_err_memory_alloc;

m_err_memory_alloc

this exception is raised by _many_ functions whenever a call to m_mem_alloc or m_mem_realloc failed due to lack of available memory.

note that it can also appear in a call to m_core_push and its variants (i.e. ?m_memory_push, m_string_push , etc..)