typedef struct M_ListPoolRec_*   M_ListPool;

handle to a list pool object. A List pool is a _static_ core object used to allocate and release list nodes efficiently.

  typedef struct M_ListNodeRec_*      M_ListNode;

handle to a simple doubly-linked list node. see M_ListNodeRec

  typedef struct M_ListNodeRec_
  {
    M_ListNode  next;
    M_ListNode  prev;
    M_Pointer   data;

  } M_ListNodeRec;

a simple doubly-linked list node structure.

  typedef M_ListNode   M_CList;

a simple circular list node/item.

note that the same type is used for both the list head and a pointer to a list node.

in a circular list, the 'prev' and 'next' fields of each node _cannot_ be NULL.

  typedef struct M_ListRec_*           M_List;

handle to a simple doubly-linked list. see M_ListRec

  typedef struct M_ListRec_
  {
    M_ListPool  pool;
    M_CList     head;

  } M_ListRec;

an easy-to-use _circular_ doubly-linked list structure.

  typedef void  (*M_ListNodeFunc)(  M_ListNode  node,
                                    M_Pointer   user_data );

a function used to process a given list node. For example, to delete its data member..

  MLIB_API(M_ListPool)   m_list_pool( M_Memory  memory );

retrieves a handle to the current static list pool a list and destroy it.

handle to list pool

m_err_memory_alloc (but very unlikely)

  MLIB_API(M_ListNode)
  m_list_node_alloc( M_ListPool  pool,
                     M_Pointer   data );

allocate a new list node

handle to new list node

m_err_memory_alloc

  MLIB_API(void)
  m_list_node_free( M_ListNode  node,
                    M_ListPool  pool );

release a given list node

  MLIB_API(void)
  m_clist_append_node( M_CList*   list,
                       M_CList    node );

append a given node to an existing circular list

  MLIB_API(void)
  m_clist_prepend_node( M_CList*  list,
                        M_CList   node );

prepend a given node to an existing circular list

  MLIB_API(void)
  m_clist_remove_node( M_CList*   list,
                       M_CList    node );

remove a given node from a circular list

#define  M_CLIST(x)    ((M_CList)(x))

a useful macro to convert any pointer to a M_CList

#define  M_CLIST_P(x)  ((M_CList*)(x))

a useful macro to convert any pointer to a pointer to a M_CList

#define  m_clist_next(node)   ( (node) ? M_CLIST(node)->next : NULL )

returns the next node in a circular list. Note that if "node" is the last node in the list, this macro will return the first one.

#define  m_clist_prev(node)   ( (node) ? M_CLIST(node)->prev : NULL )

returns the previous node in a circular list. Note that if "node" is the first node in the list, this macro will return the last one.

#define  m_clist_first(list)  (list)

returns the first node in a circular list, or NULL if it's empty

#define  m_clist_last(list)   m_clist_prev(list)

returns the last node in a circular list, or NULL if it's empty

  MLIB_API(void)
  m_clist_append( M_CList*    list,
                  M_Pointer   data,
                  M_ListPool  pool );

append a new node with given value to a circular list

?m_err_mem_alloc

  MLIB_API(void)
  m_clist_prepend( M_CList*    list,
                   M_Pointer   data,
                   M_ListPool  pool );

prepend a new node with given value to a circular list

?m_err_mem_alloc

  MLIB_API(M_CList)
  m_clist_find( const M_CList*  list,
                M_Pointer       data );

find an element with a given value in a circular list

list node, or NULL if not found

  MLIB_API(void)
  m_clist_remove( M_CList*     list,
                  M_Pointer    data,
                  M_ListPool   pool );

find a nod in a clist with specific data, and remove it

  MLIB_API(M_UInt)
  m_clist_size( const M_CList*  list );

returns the length in nodes of a given circular list

list length

  MLIB_API(void)
  m_clist_foreach( const M_CList*  list,
                   M_ListNodeFunc  node_func,
                   M_Pointer       node_data );

process each node in a list serially

see also the macros M_CLIST_LOOP and ?M_CLIST_LOOP_END to be able to process a circular list efficiently..

  MLIB_API(void)
  m_clist_clear( M_CList*    list,
                 M_ListPool  pool );

clear a list, i.e. delete all its nodes. the list node data isn't touched.

  MLIB_API(void)
  m_clist_clear_custom( M_CList*           list,
                        M_ListPool         pool,
                        M_DestroyDataFunc  destroy,
                        M_Pointer          destroy_data );

clear a list, i.e. delete all its nodes. the list node data is processed by a node function before each deletion.

#define  M_CLIST_LOOP_ROOT( list )                       \
          {                                              \
            M_CList  __clist_first = M_CLIST(list);      \
            M_CList  __clist_node;                       \
            if (__clist_first)                           \
            {                                            \
              __clist_node = __clist_first;              \
              do                                         \
              {

#define  M_CLIST_LOOP( _list, _data )               \
            M_LOOP_CLIST_ROOT( _list )              \
            M_Pointer  _data = __clist_node->data;

this macro is used in association with M_CLIST_END to parse the content of a given M_CList.

it's ok to exit the loop with "break" or "return"

here's a simple usage example, it is used to print the list of values as signed integers

      M_CList    list = 0;

      ...

      printf( "listed values = [" );

      // note that "data" doesn't need to be defined before the loop !!

      M_CLIST_LOOP( list, data )
        printf( " %d", M_POINTER_TO_INT(data) );
      M_CLIST_END

#define  M_CLIST_LOOP_END                                   \
                __clist_node = __clist_node->next;          \
              }                                             \
              while ( __clist_node != __clist_first );      \
            }                                               \
          }

this macro is used in association with M_CLIST_LOOP or ?M_CLIST_LOOP_NODE to parse the content of a given M_CList.

see the description of ?M_LOOP_CLIST for a usage example

  MLIB_API(void)  m_list_init( M_List    list,
                               M_Memory  memory );

initialize a given list from the current memory manager. this must be called before _any_ other operation on the list

this function extracts the list pool from the current memory manager, and set it in "list->pool".

  MLIB_API(void)  m_list_init_from_pool( M_List       list,
                                         M_ListPool  pool );

initialize a given list from the current list pool. this must be called before _any_ other operation on the list

#define  m_list_size(list)   ( (list) ? m_clist_size( (list)->head ) : 0 )

returns the number of nodes in a list

number of elements

#define  m_list_is_empty(list)  ( (list) ? (list)->head == 0 : 1 )

a macro that returns TRUE iff a list is empty

  MLIB_API(void)
  m_list_append( M_List     list,
                 M_Pointer  data );

append a given value to a list

m_err_memory_alloc

  MLIB_API(void)
  m_list_prepend( M_List     list,
                  M_Pointer  data );

prepend a given value to a list

m_err_memory_alloc

  MLIB_API(M_ListNode)
  m_list_find( M_List     list,
               M_Pointer  data );

parse a list to find the node corresponding to a given data

handle to list node. NULL if not found

  MLIB_API(void)
  m_list_remove( M_List     list,
                 M_Pointer  data );

find a list node corresponding to a given value, remove it from a list and destroy it.

#define  m_list_first(list)  ( (list) ? (list)->head : NULL )

returns the first node of a list

#define  m_list_last(list)   ( (list) && (list)->head       \
                                ? (list)->head->prev : NULL )

returns the last node of a list

#define  m_list_next(node)  m_clist_next(node)

returns the next node of a list. Note that if the node is the last in the list, the macro will return the first node.

#define  m_list_prev(node)  m_clist_prev(node)

returns the previous node of a list. Note that if the node is the first in the list, the macro will return the last node.

#define  M_LIST_LOOP( _list, _data )                 \
            M_BEGIN_STMNT                            \
              m_assert( _list  );                    \
              M_CLIST_LOOP( (_list)->head, _data )

this macro is used in assocation with M_LIST_END . They are used to parse the content of a list simply. See the descriptions of M_CLIST_LOOP and M_CLIST_END for an idea of how to use them

#define  M_LIST_END                   \
                M_CLIST_END           \
            M_END_STMNT

this macro is used in assocation with M_LIST_LOOP . They are used to parse the content of a list simply. See the descriptions of M_CLIST_LOOP and M_CLIST_END for an idea of how to use them

#define  m_list_append_node( list, node )                  \
            M_BEGIN_STMNT                                  \
              m_assert( list );                            \
              m_clist_append_node( &(list)->head, node );  \
            M_END_STMNT

this macro is used to append a node to a given list.

this is defined as a macro rather than a function because an application should rarely use it in practice, and because it's such a thin wrapper around m_clist_append_node

#define  m_list_prepend_node( list, node )                  \
            M_BEGIN_STMNT                                   \
              m_assert( list );                             \
              m_clist_prepend_node( &(list)->head, node );  \
            M_END_STMNT

this macro is used to prepend a node to a given list.

this is defined as a macro rather than a function because an application should rarely use it in practice, and because it's such a thin wrapper around m_clist_prepend_node

#define  m_list_remove_node( list, node )                  \
            M_BEGIN_STMNT                                  \
              m_assert( list );                            \
              m_clist_remove_node( &(list)->head, node );  \
            M_END_STMNT

this macro is used to prepend a node to a given list.

this is defined as a macro rather than a function because an application should rarely use it in practice, and because it's such a thin wrapper around m_clist_remove_node

  MLIB_API(void)
  m_list_clear( M_List   list );

clear a list, i.e. destroy all its nodes (without touching their values).

  MLIB_API(void)
  m_list_clear_custom( M_List             list,
                       M_DestroyDataFunc  destroy_func,
                       M_Pointer          destroy_data );

clear a given list, i.e. remove its list node, using a node function