#ifndef _apl_memory_thinallocapi_h_
#define _apl_memory_thinallocapi_h_
/*----------------------------------------------------------------------------
** SUMMARY: Thin Memory Allocation (MEMTHIN)
**
** DESCRIPTION:
**  This file provides a thin/bare-bones memory allocator.  Memory can be 
**  allocated, but never freed and/or released. This approach has several 
**  advantages: 1) allocating memory is 'fast' and deterministic. 2) Maximum 
**  efficiency of the heap memory, since there are no 'overhead' bytes per 
**  block. This interface can be used in 'parallel' (i.e. co-exist) with other 
**  Memory interfaces.
**
**  HEAP-SIZE
**  ---------
**  The size of the heap is defined at compile time by the preprocessor
**  symbol, OPTION_APL_MEMTHIN_SIZE_HEAP.  This symbol defines the size of
**  heap in bytes. The MUST define this symbol when using this interface.
**  For maximum usage of the heap, APL_MEMTHIN_SIZE_ALLOC_HEAP needs to be
**  a multiple of OPTION_APL_MEMTHIN_ALIGNMENT_SIZE.  
** 
**  OUT-OF-MEMORY
**  -------------
**  The application can at compile time, determine the behavior for
**  the out-of-memory condition.  By default, the alloc routine returns
**  a NULL pointer when the heap has been exhausted.  However, by using the
**  the compile switch, USE_APL_MEMTHIN_FATAL_ERROR_WHEN_OUTOFMEMORY, 
**  allocate routine will generate a fatal error when it is unable to 
**  satifiy an application request for memory.
**
**  MEMORY ALIGNMENT
**  ----------------
**  By default the heap, and all 'chunks' allocated from it, are aligned on
**  even address boundaries.  If the application/platform requires different 
**  alignment then it needs to set 'OPTION_APL_MEMTHIN_ALIGNMENT_SIZE' to the 
**  size, in bytes, of the alignment.  For example, for alignment on 4 byte 
**  boundaries, set OPTION_APL_MEMTHIN_ALIGNMENT_SIZE equal to 4. Boundaries 
**  of 1, 2, and 4 are supported.
**
**
** CONFIGURATION 
** -------------
**  COMPILE:        USE_APL_MEMTHIN_FATAL_ERROR_WHEN_OUTOFMEMORY
**
**  APPLICATION:    OPTION_APL_MEMTHIN_SIZE_HEAP
**                  OPTION_APL_MEMTHIN_ALIGNMENT_SIZE
**
**  PLATFORM:       none.
**
**  NOTES:
**  1. Unless explicitly stated, NONE of the following methods may be called
**     from interrtup service routines.
**  2. 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 "aplcfg.h"                 /* For: Application configuration */
#include "apl/types/types.h"        /* For: basic types */


#ifdef __cplusplus
extern "C" {
#endif


/*-------------- ERRORS ----------------------------------------------------*/
/** The requested size is reported with the error */
#define APL_ERRSTR_MEMTHIN_OUT_OF_MEMORY    "MEMTHIN: Not enough free memory left to satisfy the request.  Number of bytes requested="
/***/
#define APL_ERR_MEMTHIN_OUT_OF_MEMORY       _APL_ERR_MEMTHIN_OUT_OF_MEMORY


/*-------------- CONSTANTS -------------------------------------------------*/
/** Aligment boundary (default value) */
#ifndef OPTION_APL_MEMTHIN_ALIGNMENT_SIZE
#define OPTION_APL_MEMTHIN_ALIGNMENT_SIZE         2
#endif


/*-------------- INLINE IMPLEMENTATION -------------------------------------*/
#include "apl/memory/thinalloc.h"            /* For: inline implementation */


/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This method attempts to allocate the specified number of bytes from the 
    'thin' heap. The method returns a pointer to the newly allocate memory if 
    successful, else 0 is returned if no memory is currently available.
    NOTES:
        o There is compile option to generate a fatal error when the
          out-of-memory condition occurs (see inteface description above
          for more details).
        o The memory allocated with this method can NEVER be freed and/or
          released.

    Prototype:
        void* Apl_allocate( AplSize_t numBytes );
 */
#define Apl_allocate                    _Apl_allocate


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