#ifndef _xmk_mutex_h_
#define _xmk_mutex_h_
/*----------------------------------------------------------------------------
** SUMMARY: XMK Mutex API (MX)
**
** DESCRIPTION:
**  This file provides interfaces for Mutexes.  A mutex is a MUTual EXclusion 
**  device, and is useful for protecting shared data structures from concurrent 
**  modifications, and implementing critical sections and monitors.
**
** IMPLEMENATION NOTE:
**  The current implementation is simply a collection of specialized aliases to
**  the Semaphore API.  This has the following effects:
**      o The mutexes are NOT recursive mutexes.
**      o No error checking for Mutex specific behaviour versus a generic 
**        semaphore.  Also any fatal errors generated will be Semaphore errors, 
**        not Mutex errors.
**
** CONFIGURATION OPTION: USE_XMK_MUTEXES
**
** DEPENDENCIES:
**  To use this interface the following XMK service(s) MUST always be
**  enabled/configured:
**      USE_XMK_CORE_KERNEL
**
**  NOTES:
**  1. For efficency/optimization some methods are 'inlined'.  The inlining
**     is done by using the preprocessor/macros.  The application should
**     treat all methods as function calls and not rely on the fact they may
**     be currently defined as a macro.
**
**
----------------------------------------------------------------------------*/

#include "xmkcfg.h"     /* For: Project/Application kernel configuraiton */

#ifdef __cplusplus
extern "C" {
#endif

/*-------------- MAGIC CONSTANTS -------------------------------------------*/
/** NULL Semaphore handle */
#define XMK_NULL_MUTEX		            _XMK_NULL_MUTEX


/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This method is used to iniitalize a mutex for use by the 
    application. 
    NOTES:
        o The application is responsible for allocating the memory for
          the mutex data structure.

    Prototype:
        void Xmk_mutexInit(XMK_MUTEX* mutex);
 */
#define Xmk_mutexInit(m)                _Xmk_mutexInit(m)

/** This method is used to free the kernel resources of a previously created 
    mutex.  
    NOTES:
        o The application is responsible for freeing the memory of the
          mutex data structure.
        o Passing an uninitialized mutex will result in un-defined 
          behavior (and most likely crash your application).

    Prototype:
        void Xmk_mutexDestroy( XMK_MUTEX* mutex );
 */
#define Xmk_mutexDestroy(m)             _Xmk_mutexDestroy(m)

/** This method locks the given mutex.  If the mutex is currently unlocked,  
    it becomes locked and owned by the calling thread, and the method
    returns immediately. If the mutex is already locked by another thread,  
    the method suspends the calling thread until the mutex is unlocked.
    NOTES:
        o This method can ONLY be called from a thread context.
        o Passing an uninitialized mutex will result in un-defined 
          behavior (and most likely crash your application).

    Prototype:
        void Xmk_mutexLock( XMK_MUTEX* mutex );
 */
#define Xmk_mutexLock(m)                _Xmk_mutexLock(m)

/** This method unlocks the given mutex. The mutex is assumed to be locked and
    owned by the calling thread.
    NOTES:
        o This method can ONLY be called from a thread context.
        o Passing an uninitialized mutex will result in un-defined 
          behavior (and most likely crash your application).

    Prototype:
        void Xmk_mutexUnlock( XMK_MUTEX* mutex );
 */
#define Xmk_mutexUnlock(m)              _Xmk_mutexUnlock(m)



#ifdef __cplusplus
}
#endif
/*--------------------------------------------------------------------------*/
#endif  /* end _xmk_mutex_h_ */