#ifndef _aplmt_os_tsdapi_h_
#define _aplmt_os_tsdapi_h_
/*----------------------------------------------------------------------------
** SUMMARY: Thread Specific Data (TSD)
**
** DESCRIPTION:
**  This file provides the interface for managing and accessing global 
**  variables that have different values in different threads. Each thread 
**  possesses a private memory block, the TSD area. This area is indexed by 
**  TSD keys. The TSD area associates values of type AplmtTsdElement 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.
**
**  INITIAL TSD VALUE
**  -----------------
**  When a thread is created, its TSD elements are initially set to:
**  APLMT_TSD_INIITAL_ELEMENT_VALUE.  In addition, when a new key is created, 
**  the element value for all existing threads is set to:
**  APLMT_TSD_INIITAL_ELEMENT_VALUE
**
**  TSD ELEMENT TYPE
**  ----------------
**  The application can set/override the data type for the TSD Elements.
**  However, there are limits on what the TSD Element type can be.  Most
**  platforms do not support structures and/or non-intrinsic data types
**  for TSD elements.  To ensure portability, the application should not
**  define the TSD Element type to be larger, in bits, than a void pointer.
**
** 
** CONFIGURATION 
** -------------
**  COMPILE:        none.
**                                            
**  APPLICATION:    The application can override the following types/defintions
**                      AplmtTsdElement
**                      OPTION_APLMT_TSD_MAX_KEYS
**
**  PLATFORM:       PLATFORM_APLMT_TSD_KEY_T
**                  PLATFORM_APLMT_TSD_NULL_KEY 
**                  PLATFORM_APLMT_TSD_INIITAL_ELEMENT_VALUE                         
**                                            
**  NOTES:
**  1. Unless explicitly stated otherwise, NONE of the following methods may be 
**     called from interrupt service routines.
**  2. Unless explicitly stated otherwise, NONE of the following methods may be 
**     called before the platform's kernel is running.
**  3. Unless explicitly stated otherwise, all of the following methods ARE 
**     thread-safe.
**  4. 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 macros.
----------------------------------------------------------------------------*/


#include "apl/types/types.h"        /* For: basic types */

#ifdef __cplusplus
extern "C" {
#endif


/*-------------- ERRORS ----------------------------------------------------*/
/** A call to Aplmt_requestTsdKey() exceeded the TSD Key limit of the application.
 */
#define APLMT_ERRSTR_TSD_EXCEEDING_KEY_LIMIT    "TSD: No more Thread-Specific-Data keys available"
/***/
#define APLMT_ERR_TSD_EXCEEDING_KEY_LIMIT       _APLMT_ERR_TSD_EXCEEDING_KEY_LIMIT

/** A call was made using an invalid/un-initialized TSD key
 */
#define APLMT_ERRSTD_TSD_INVALID_KEY            "TSD: Invalid and/or un-initialized TSD key specified" 
/***/
#define APLMT_ERR_TSD_INVALID_KEY               _APLMT_ERR_TSD_INVALID_KEY



/*-------------- CONSTANTS -------------------------------------------------*/
/** NULL TSD Key identifier */
#define APLMT_NULL_TSD_KEY                  PLATFORM_APLMT_TSD_NULL_KEY

/** Initial TSD Element for a newly create TSD key */
#define APLMT_TSD_INIITAL_ELEMENT_VALUE     PLATFORM_APLMT_TSD_INIITAL_ELEMENT_VALUE

/** Maximum number of TSD keys (default is 4) */
#ifndef OPTION_APLMT_TSD_MAX_KEYS
#define OPTION_APLMT_TSD_MAX_KEYS           4
#endif

/*-------------- TYPES -----------------------------------------------------*/
/** Data type of the TSD storage (default is a void*) */
#ifndef AplmtTsdElement
#define AplmtTsdElement                     void*
#endif

/** Key data type */
#define AplmtTsdKey                         PLATFORM_APLMT_TSD_KEY_T


/*-------------- INLINE PLATFORM IMPLEMENTATION ----------------------------*/
#include "platform/tsdapi.h"       


/*-------------- 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 element area.  
    NOTES:
        o There is a finite number of TSD keys (i.e. OPTION_APLMT_TSD_MAX_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:
        AplmtTsdKey Aplmt_tsdRequestKey(void);
 */
#define Aplmt_tsdRequestKey                 _Aplmt_tsdRequestKey

/** 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
          Aplmt_requestTsdKey()), the kernel will generate a Fatal Error.

    Prototype:
        AplmtTsdElement Aplmt_tsdGetElement( AplmtTsdKey index );
 */
#define Aplmt_tsdGetElement                 _Aplmt_tsdGetElement

/** 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
          Aplmt_requestTsdKey()), the kernel will generate a Fatal Error.

    Prototype:
        void Aplmt_tsdSetElement( AplmtTsdKey index, AplmtTsdElement newValue );
 */
#define Aplmt_tsdSetElement                 _Aplmt_tsdSetElement



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