#ifndef _xmk_tsd_h_
#define _xmk_tsd_h_
/*----------------------------------------------------------------------------
** SUMMARY: XMK Thread-Specific-Data (TSD)
**
** DESCRIPTION:
**  Programs often need global or static variables that have different values
**  in different threads. XMK provides a Thread-Specific-Data interface for
**  just this purpose.  
**
**  Each thread possesses a private memory block, the TSD area. This area 
**  is indexed by TSD keys. The TSD area associates values of type 
**  XMK_TSD_TYPE to TSD keys. TSD keys are common to all threads, but the 
**  value associated with a given TSD key can be different in each thread.
**
**  For concreteness, the TSD areas can be viewed as arrays of type 
**  XMK_TSD_TYPE and TSD keys as integer indices into these arrays, and the 
**  value of a TSD key as the value of the corresponding array element in the 
**  calling thread.
**
**  When a thread is created, its entire TSD area is initialize to ZERO.
**
**  The default type of XMK_TSD_TYPE is defined in types.h and is of type:
**  'void*'.  The application can provide different type definition via
**  its xmkcfg.h header file.
**
** CONFIGURATION OPTION: USE_XMK_TSD
**
** DEPENDENCIES:
**  To use this interface the following XMK service(s) MUST always be
**  enabled/configured:
**      USE_XMK_CORE_KERNEL
**
** APPLICATION REQUIREMENTS:
**  The application must provide definitions for the following symbols
**  in its xmkcfg.h header file:
**    PRJ_XMK_NUM_TSD_KEYS  - Maximum number of TSD keys supported, i.e. 
**                            the element count of the TSD areas.
**
**  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 and/or invalid TSD Key identifier */
#define XMK_INVALID_TSD_KEY                     _XMK_INVALID_TSD_KEY

/*
** ERROR CODES 
*/
/** A call to Xmk_requestTsdKey() exceeded the TSD Key limit of the application.
 */
#define XMK_ERRFATAL_TSD_EXCEEDING_KEY_LIMIT    _XMK_ERRFATAL_TSD_EXCEEDING_KEY_LIMIT

/** A call to Xmk_getTsdElement() was made with an invalid/un-initialized TSD key
 */
#define XMK_ERRFATAL_TSD_INVALID_GET            _XMK_ERRFATAL_TSD_INVALID_GET

/** A call to Xmk_setTsdElement() was made with an invalid/un-initialized TSD key
 */
#define XMK_ERRFATAL_TSD_INVALID_SET            _XMK_ERRFATAL_TSD_INVALID_SET



/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This method is used to 'generate' a TSD key for use by the application.
    The returned key can then be used by ALL threads to access their respective
    TSD area.  
    NOTES:
        o There is a finite number of TSD keys (i.e. PRJ_XMK_NUM_TSD_KEYS) 
          and once a key is 'created' it can not be deleted.
        o If this method is called and there are no more available TSD keys, 
          the kernel will generate a Fatal Error.

    Prototype:
        XMK_TSD_KEY Xmk_requestTsdKey(void);
 */
#define Xmk_requestTsdKey()             _Xmk_requestTsdKey()        

/** This method retrieves the value of the TSD element associated with the 
    current thread for the specified TSD key.
    NOTES:
        o If the specified TSD key is invalid (i.e. not generated by
          Xmk_requestTsdKey()), the kernel will generate a Fatal Error.

    Prototype:
        XMK_TSD_ELEMENT Xmk_getTsdElement( XMK_TSD_KEY index );
 */
#define Xmk_getTsdElement(k)            _Xmk_getTsdElement(k)

/** This method sets the value of the TSD element associated with the 
    current thread for the specified TSD key.
    NOTES:
        o If the specified TSD key is invalid (i.e. not generated by
          Xmk_requestTsdKey()), the kernel will generate a Fatal Error.

    Prototype:
        void Xmk_setTsdElement( XMK_TSD_KEY index, XMK_TSD_ELEMENT newValue );
 */
#define Xmk_setTsdElement(k,v)          _Xmk_setTsdElement(k,v)



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