typedef struct M_MutexRec_*  M_Mutex;

a handle to a MLib mutex lock object, see M_MutexRec

mutexes are simple synchronisation objects used to protect shared data from concurrent access (read or write). They are _recursive_, which means that a single thread can lock a mutex multiple times if it needs to.

in most platforms, locking and unlocking a mutex both require a kernel call. These can frequently be avoided by using one of the following synchronisation objects..

synlocks (@M_Synlock) are _fast_ and _non-recursive_ mutex objects that can be used to protect short code sequences efficiently.

read/write locks (@M_RWLock) are special mutex objects whose implementation is specially optimised to protect shared objects that are much more frequently read than written to.

  typedef struct M_SynlockRec_*  M_Synlock;

a handle to a fast MLib synchronisation lock object, see M_SynlockRec

A synlock is a _fast_ and _non-recursive_ mutex. Synlocks are generally used to protect short code sequences from concurrent execution. They're also called "spinlocks", "critical sections" or "non-recursive mutexes" on certain systems.

on many platforms, they can be implemented without kernel calls, which makes them very fast.

  typedef struct M_RWLockRec_*    M_RWLock;

a handle to a MLib read/write lock object. see M_RWLockRec

A read/write lock is similar to a mutex, but is used to protect shared data that is frequently read, and seldom updated or written to.

A thread that only needs to read some protected data will call m_rwlock_read_begin , perform the read, then call m_rwlock_read_end .

A thread that wants to write to the same data will call m_rwlock_write_begin , perform the write, then call m_rwlock_write_end

Finally, a thread that wants to read the data and _eventually_ write to it will call m_rwlock_update_begin , perform the read and determine if the data will need an update.

If so, it will call m_rwlock_update_write , perform the write, then call m_rwlock_update_end . If not, it will call m_rwlock_update_end .

the implementation of a read/write lock on most platforms provide very fast implementation for "read_begin" and "read_end" (usually by avoiding any kernel call).

read/write locks also allow several concurrent reads on the protected data, as long as no thread called m_rwlock_write_begin or m_rwlock_update_write

  MLIB_API(M_Mutex)
  m_mutex_new( M_Core  mcore );

handle to new mutex object.

m_err_mutex_init or m_err_memory_alloc

  MLIB_API(void)
  m_mutex_destroy( M_Mutex  mutex );

  MLIB_API(void)
  m_mutex_lock( M_Mutex  mutex );

m_err_mutex_lock

  MLIB_API(void)
  m_mutex_unlock( M_Mutex  mutex );

m_err_mutex_unlock

  MLIB_API(void)
  m_mutex_lock_push( M_Mutex  mutex );

m_err_mutex_lock , m_err_memory_alloc

  MLIB_API(void)
  m_mutex_pop_unlock( M_Mutex  mutex );

?m_err_core_pop

  MLIB_API(M_Synlock)
  m_synlock_new( M_Core  mcore );

handle to new synlock object.

m_err_synlock_init or m_err_memory_alloc

  MLIB_API(void)
  m_synlock_destroy( M_Synlock  lock );

  MLIB_API(void)
  m_synlock_lock( M_Synlock  lock );

m_err_synlock_lock

  MLIB_API(void)
  m_synlock_unlock( M_Synlock  lock );

m_err_synlock_unlock

  MLIB_API(void)
  m_synlock_lock_push( M_Synlock  lock );

m_err_synlock_lock or m_err_memory_alloc

  MLIB_API(void)
  m_synlock_pop_unlock( M_Synlock  lock );

m_err_synlock_unlock

  MLIB_API(M_RWLock)
  m_rwlock_new( M_Core  mcore );

handle to new r/w lock

m_err_rwlock_init , m_err_memory_alloc

  MLIB_API(void)
  m_rwlock_destroy( M_RWLock  lock );

  MLIB_API(void)
  m_rwlock_read_begin( M_RWLock  lock );

m_err_rwlock_read_begin

  MLIB_API(void)
  m_rwlock_read_end( M_RWLock  lock );

m_err_rwlock_read_end

  MLIB_API(void)
  m_rwlock_write_begin( M_RWLock  lock );

m_err_rwlock_write_begin

  MLIB_API(void)
  m_rwlock_write_end( M_RWLock  lock );

m_err_rwlock_read_end

  MLIB_API(void)
  m_rwlock_update_begin( M_RWLock  lock );

m_err_rwlock_read_begin

  MLIB_API(void)
  m_rwlock_update_write( M_RWLock  lock );

m_err_rwlock_write_begin

  MLIB_API(void)
  m_rwlock_update_end( M_RWLock  lock );

m_err_rwlock_write_end or m_err_rwlock_read_end

  typedef struct M_ThreadRec_*  M_Thread;

a handle to a MLib thread object, see ?M_ThreadRec

the real implementation of threads is system-specific and hidden to the developer..