#ifndef _apl_memory_mallocapi_h_
#define _apl_memory_mallocapi_h_
/*----------------------------------------------------------------------------
** SUMMARY: Memory Allocation (MEM)
**
** DESCRIPTION:
**  This file provides basic heap-based memory management methods. 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_MEM_SIZE_HEAP.  This symbol defines the size of
**  heap in bytes. The symbol MUST define this symbol when using this 
**  interface (well almost always, see the section 'STANDARD C LIBRARY').
** 
**  OUT-OF-MEMORY
**  -------------
**  The application can at compile time, determine the behavior for
**  the out-of-memory condition.  By default, the malloc routine returns
**  a NULL pointer when the heap has been exhausted.  However, by using the
**  the compile switch, USE_APL_MEM_FATAL_ERROR_WHEN_OUTOFMEMORY, 
**  malloc routine will generate a fatal error when it is unable to 
**  satifiy an application request for memory.
**
**  MINIMUM ALLOCATION SIZE
**  -----------------------
**  In an attempt to reduce fragmentation, the heap will always 'round-up'
**  allocation request sizes to a predefined value.  The default minimum
**  size is 16 bytes.  The application can sets its own minimum value
**  by defining OPTION_APL_MEM_MIN_ALLOC_SIZE.
** 
**  MEMORY ALIGNMENT
**  ----------------
**  By default the heap, and all memory 'chunks' allocated from it, are aligned 
**  on even address boundaries.  If the application/platform requires different
**  alignment then it needs to set 'OPTION_APL_MEM_ALIGNMENT_SIZE' to the size, 
**  in bytes, of the alignment.  For example, for alignment on 4 byte 
**  boundaries, set OPTION_APL_MEM_ALIGNMENT_SIZE equal to 4. Boundaries of  
**  1, 2, and 4 are supported.
**
**  STANDARD C LIBRARY
**  ------------------
**  If you want APL to make use of the standard C library's (libc) 
**  malloc/free implemeantion then the application must define the
**  preprocess symbol: USE_APL_MEM_STANDARD_C_LIBRARY.  Note: When using the
**  the standard library, the application does not define 
**  OPTION_APL_MEM_SIZE_HEAP, OPTION_APL_MEM_ALIGNMENT_SIZE, or 
**  OPTION_APL_MEM_MIN_ALLOC_SIZE, since APL has no control over how the C 
**  library allocates and manages its heap.
**
**
** CONFIGURATION 
** -------------
**  COMPILE:        USE_APL_MEM_FATAL_ERROR_WHEN_OUTOFMEMORY
**                  USE_APL_INIT_MEM_IN_SYSTEM_INIT
**                  USE_APL_MEM_STANDARD_C_LIBRARY
**
**                                            
**  APPLICATION:    OPTION_APL_MEM_SIZE_HEAP
**                  OPTION_APL_MEM_ALIGNMENT_SIZE
**                  OPTION_APL_MEM_MIN_ALLOC_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_MEM_OUT_OF_MEMORY        "MEM: No free block of memory large enough to satisfy the request.  Number of bytes requested="
/***/
#define APL_ERR_MEM_OUT_OF_MEMORY           _APL_ERR_MEM_OUT_OF_MEMORY


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

/** Minimum heap block size (default value) */
#ifndef OPTION_APL_MEM_MIN_ALLOC_SIZE
#define OPTION_APL_MEM_MIN_ALLOC_SIZE              16
#endif


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


/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This method is used to initialize the heap used by the following 
    routines.  This method must be called BEFORE any/all calls to 
    the other methods in this interface.
    NOTES:
        o If USE_APL_INIT_MEM_IN_SYSTEM_INIT is defined, then APL will
          internally call this method as part of the Apl_systemInit()
        o This method does nothing when USE_APL_MEM_STANDARD_C_LIBRARY
          is defined.

    Prototype:
        void Apl_initMalloc(void);
 */
#define Apl_initMalloc                      _Apl_initMalloc  
 

/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This method attempts to allocate the specified number of bytes from the 
    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).

    Prototype:
        void* Apl_malloc( AplSize_t numBytes );
 */
#define Apl_malloc                    _Apl_malloc   

/** This returns the block of memory pointed by the specified pointer
    to the heap.
    NOTES:
        o If 'memoryToFree' equals 0, then no operation is performed.
        o You must free the same pointer that was originally allocated
          from Apl_malloc  .  Freeing 'different' pointers will cause
          memory leaks at best, or more typically, crash the system!
        o It is OK to free memory allocated by Aplmt_malloc() with
          this method.


    Prototype:
        void Apl_free( void* memoryToFree );
 */
#define Apl_free                      _Apl_free   




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