/*
* Copyright (c) 2000 - 2001 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: 
*
*/


/** ----------------------------------------------------------------------- **
    @package:     NW_TinyTree

    @synopsis:    default

    @description: default

 ** ----------------------------------------------------------------------- **/

#ifndef NW_TREE_ALLOC_H
#define NW_TREE_ALLOC_H


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */


#define MIN_SEGMENT_SIZE 64

/* ----------------------------------------------------------------------- **
   These methods are private to the tiny tree module.
** ----------------------------------------------------------------------- **/

 
/* ----------------------------------------------------------------------- **
   Storage mananagement:

   Header for a storage block. When the block is allocated by the
   tree_alloc methods, the storage block will be contiguous with the
   header. However, when the block was supplied externally (for
   example, by the parser) the storage will be somewhere else.  
** ----------------------------------------------------------------------- **/


/** ----------------------------------------------------------------------- **
    @typedef:     NW_TinyTree_RelativeOffset

    @synopsis:    Relative offset into structure.

    @scope:       public
    @type:        NW_Uint32

    @description: Relative offset into structure.
 ** ----------------------------------------------------------------------- **/
typedef NW_Uint32 NW_TinyTree_RelativeOffset_t;


/** ----------------------------------------------------------------------- **
    @struct:      NW_TinyTree_SegHeader

    @synopsis:    Segment header.

    @scope:       public
    @variables:
       NW_TinyTree_RelativeOffset_t next
                  Offset into segment.

       NW_TinyTree_Offset_t size
                  Offset.

       NW_TinyTree_Offset_t free_offset
                  Free offset.

       void* initializer NW_Byte__ptr__NW_TinyTree_Offset_t
                  Funcion pointer for initializer.

       NW_Byte* storage
                  Storage.

    @description: Segment header.
 ** ----------------------------------------------------------------------- **/
typedef struct NW_TinyTree_SegHeader_s{
  NW_TinyTree_RelativeOffset_t next;
  NW_TinyTree_Offset_t size;
  NW_TinyTree_Offset_t free_offset;
  void (*initializer) (NW_Byte*, NW_TinyTree_Offset_t);
  NW_Byte* storage;
} NW_TinyTree_SegHeader_t;


/** ----------------------------------------------------------------------- **
    @function:    NW_TinyTree_segmentGetFreeSpace

    @synopsis:    Get free space.

    @scope:       public

    @parameters:
       [in] NW_TinyTree_SegHeader_t* segment
                  The segment header.

    @description: Get free space.

    @returns:     NW_TinyTree_Offset_t
                  Free space pointer.

 ** ----------------------------------------------------------------------- **/
NW_TinyTree_Offset_t 
NW_TinyTree_segmentGetFreeSpace(NW_TinyTree_SegHeader_t* segment);


/** ----------------------------------------------------------------------- **
    @function:    NW_TinyTree_getFreeStorageSpace

    @synopsis:    Get free storage space.

    @scope:       public

    @parameters:
       [in] NW_TinyTree_SegHeader_t* base
                  The segment header.

    @description: Get free storage space.

    @returns:     NW_TinyTree_Offset_t
                  Free storage space pointer.

 ** ----------------------------------------------------------------------- **/
NW_TinyTree_Offset_t
NW_TinyTree_getFreeStorageSpace(NW_TinyTree_SegHeader_t* base);


/** ----------------------------------------------------------------------- **
    @function:    NW_TinyTree_addSegment

    @synopsis:    Add segment.

    @scope:       public

    @parameters:
       [in] NW_TinyTree_SegHeader_t* base
                  The segment header.

       [in] NW_TinyTree_Offset_t size
                  Size of new segment.

    @description: Add segment.

    @returns:     NW_TinyTree_SegHeader_t*
                  New header.

 ** ----------------------------------------------------------------------- **/
NW_TinyTree_SegHeader_t*
NW_TinyTree_addSegment(NW_TinyTree_SegHeader_t* base, NW_TinyTree_Offset_t size);


/** ----------------------------------------------------------------------- **
    @function:    NW_TinyTree_freeSegments

    @synopsis:    Free segments.

    @scope:       public

    @parameters:
       [in] NW_TinyTree_SegHeader_t* base
                  The segment header.

    @description: Free segments.
 ** ----------------------------------------------------------------------- **/
void 
NW_TinyTree_freeSegments(NW_TinyTree_SegHeader_t* base);


/** ----------------------------------------------------------------------- **
    @function:    NW_TinyTree_offsetGetSegment

    @synopsis:    Get segment header.

    @scope:       public

    @parameters:
       [in] NW_TinyTree_SegHeader_t* base
                  The segment header.

       [out] NW_TinyTree_Offset_t* offset
                  Data offset.

    @description: Get the segment header associated with an offset. This 
                  allocates a new segment if the offset is beyond any 
                  currently allocated segment. If a new segment is 
                  allocated, the offset is readjusted to the beginning of 
                  the new segment.

    @returns:     NW_TinyTree_SegHeader_t*
                  Segment header or NULL if error.

 ** ----------------------------------------------------------------------- **/
NW_TinyTree_SegHeader_t*
NW_TinyTree_offsetGetSegment(NW_TinyTree_SegHeader_t* base, NW_TinyTree_Offset_t* offset);


/** ----------------------------------------------------------------------- **
    @function:    NW_TinyTree_offsetIncrement

    @synopsis:    Increment.

    @scope:       public

    @parameters:
       [in] NW_TinyTree_SegHeader_t* base
                  The segment header.

       [in] NW_TinyTree_Offset_t offset
                  Offset.

       [in] NW_TinyTree_Offset_t delta
                  Delta.

    @description: Increment.

    @returns:     NW_TinyTree_Offset_t
                  New offset.

 ** ----------------------------------------------------------------------- **/
NW_TinyTree_Offset_t
NW_TinyTree_offsetIncrement(NW_TinyTree_SegHeader_t* base, 
            NW_TinyTree_Offset_t offset, 
            NW_TinyTree_Offset_t delta);


/** ----------------------------------------------------------------------- **
    @function:    NW_TinyTree_addressGetSegment

    @synopsis:   Get segment.

    @scope:       public

    @parameters:
       [in] NW_TinyTree_SegHeader_t* base
                  The segment header.

       [out] NW_Byte** address
                  Address of segment.

    @description: Get the segment header associated with an offset. 
                  This allocates a new segment if the offset is beyond 
                  any currently allocated segment. If a new segment is 
                  allocated, the offset is readjusted to the beginning 
                  of the new segment.  

    @returns:     NW_TinyTree_SegHeader_t*
                  The segment header.

 ** ----------------------------------------------------------------------- **/
NW_TinyTree_SegHeader_t*
NW_TinyTree_addressGetSegment(NW_TinyTree_SegHeader_t* base, 
                              NW_Byte** address);
  

/** ----------------------------------------------------------------------- **
    @function:    NW_TinyTree_addressIncrement

    @synopsis:    Increment.

    @scope:       public

    @parameters:
       [in] NW_TinyTree_SegHeader_t* base
                  The segment header.

       [in] NW_Byte* address
                  Address to increment.

       [in] NW_TinyTree_Offset_t delta
                  Delta.

    @description: Increment.

    @returns:     NW_Byte*
                  New address.

 ** ----------------------------------------------------------------------- **/
NW_Byte*
NW_TinyTree_addressIncrement(NW_TinyTree_SegHeader_t* base, 
             NW_Byte* address, 
             NW_TinyTree_Offset_t delta);


#ifdef __cplusplus
} // extern "C" {
#endif /* __cplusplus */

#endif  /* NW_TREE_ALLOC_H */