ncbi_heapmgr.h
上传用户:yhdzpy8989
上传日期:2007-06-13
资源大小:13604k
文件大小:8k
源码类别:

生物技术

开发平台:

C/C++

  1. /*
  2.  * ===========================================================================
  3.  * PRODUCTION $Log: ncbi_heapmgr.h,v $
  4.  * PRODUCTION Revision 1000.0  2003/10/29 16:30:57  gouriano
  5.  * PRODUCTION PRODUCTION: IMPORTED [ORIGINAL] Dev-tree R6.19
  6.  * PRODUCTION
  7.  * ===========================================================================
  8.  */
  9. #ifndef CONNECT___NCBI_HEAPMGR__H
  10. #define CONNECT___NCBI_HEAPMGR__H
  11. /*  $Id: ncbi_heapmgr.h,v 1000.0 2003/10/29 16:30:57 gouriano Exp $
  12.  * ===========================================================================
  13.  *
  14.  *                            PUBLIC DOMAIN NOTICE
  15.  *               National Center for Biotechnology Information
  16.  *
  17.  *  This software/database is a "United States Government Work" under the
  18.  *  terms of the United States Copyright Act.  It was written as part of
  19.  *  the author's official duties as a United States Government employee and
  20.  *  thus cannot be copyrighted.  This software/database is freely available
  21.  *  to the public for use. The National Library of Medicine and the U.S.
  22.  *  Government have not placed any restriction on its use or reproduction.
  23.  *
  24.  *  Although all reasonable efforts have been taken to ensure the accuracy
  25.  *  and reliability of the software and data, the NLM and the U.S.
  26.  *  Government do not and cannot warrant the performance or results that
  27.  *  may be obtained by using this software or data. The NLM and the U.S.
  28.  *  Government disclaim all warranties, express or implied, including
  29.  *  warranties of performance, merchantability or fitness for any particular
  30.  *  purpose.
  31.  *
  32.  *  Please cite the author in any work or product based on this material.
  33.  *
  34.  * ===========================================================================
  35.  *
  36.  * Author:  Anton Lavrentiev, Denis Vakatov
  37.  *
  38.  * File Description:
  39.  *   Simple heap manager with a primitive garbage collection
  40.  *
  41.  */
  42. #include <connect/ncbi_types.h>
  43. /** @addtogroup ServiceSupport
  44.  *
  45.  * @{
  46.  */
  47. #ifdef __cplusplus
  48. extern "C" {
  49. #endif
  50. /* Heap handle
  51.  */
  52. struct SHEAP_tag;
  53. typedef struct SHEAP_tag* HEAP;
  54. /* Header of a heap block
  55.  */
  56. typedef struct {
  57.     unsigned int flag;  /* (short)flag == 0 if block is vacant              */
  58.     TNCBI_Size   size;  /* size of the block (including the block header)   */
  59. } SHEAP_Block;
  60. /* Callback to expand the heap (a la 'realloc').
  61.  * NOTE: the returned address must be aligned on a 'double' boundary!
  62.  *
  63.  *   old_base  |  new_size  |  Expected result
  64.  * ------------+------------+--------------------------------------------------
  65.  *   non-NULL  |     0      | Deallocate old_base and return 0
  66.  *   non-NULL  |  non-zero  | Reallocate to the requested size, return new base
  67.  *      0      |  non-zero  | Allocate (newly) and return base
  68.  *      0      |     0      | Do nothing, return 0
  69.  * ------------+------------+--------------------------------------------------
  70.  * Note that reallocation can request either to expand or to shrink the
  71.  * heap extent. When (re-)allocation fails, the callback should return 0.
  72.  * When expected to return 0, this callback has to always do so.
  73.  */
  74. typedef void* (*FHEAP_Expand)
  75. (void*      old_base,  /* current base of the heap to be expanded           */
  76.  TNCBI_Size new_size,  /* requested new heap size (zero to deallocate heap) */
  77.  void*      arg        /* user-supplied argument, see HEAP_Create() below   */
  78.  );
  79. /* Create new heap.
  80.  * NOTE: the initial heap base must be aligned on a 'double' boundary!
  81.  */
  82. extern NCBI_XCONNECT_EXPORT HEAP HEAP_Create
  83. (void*        base,        /* initial heap base (use "expand" if NULL) */
  84.  TNCBI_Size   size,        /* initial heap size                        */
  85.  TNCBI_Size   chunk_size,  /* minimal increment size                   */
  86.  FHEAP_Expand expand,      /* NULL if not expandable                   */
  87.  void*        arg          /* arg to pass to expand (if any)           */
  88.  );
  89. /* Attach to an already existing heap (in read-only mode).
  90.  */
  91. extern NCBI_XCONNECT_EXPORT HEAP HEAP_Attach
  92. (const void* base          /* base of the heap to attach to */
  93.  );
  94. extern NCBI_XCONNECT_EXPORT HEAP HEAP_AttachEx
  95. (const void* base,
  96.  TNCBI_Size  size
  97.  );
  98. /* Allocate a new block of memory in the heap.
  99.  */
  100. extern NCBI_XCONNECT_EXPORT SHEAP_Block* HEAP_Alloc
  101. (HEAP       heap,          /* heap handle                       */
  102.  TNCBI_Size size           /* data size of the block to contain */
  103.  );
  104. /* Deallocate block pointed by "block_ptr".
  105.  */
  106. extern NCBI_XCONNECT_EXPORT void HEAP_Free
  107. (HEAP         heap,        /* heap handle         */
  108.  SHEAP_Block* block_ptr    /* block to deallocate */
  109.  );
  110. /* Iterate through the heap blocks.
  111.  * Return pointer to the block following block "prev_block".
  112.  * Return NULL if "prev_block" is the last block of the heap.
  113.  */
  114. extern NCBI_XCONNECT_EXPORT SHEAP_Block* HEAP_Walk
  115. (const HEAP         heap,  /* heap handle                                  */
  116.  const SHEAP_Block* prev   /* (if 0, then get the first block of the heap) */
  117.  );
  118. /* Trim the heap, making garbage collection first. Returned is
  119.  * the size of the resultant heap, which has its last block trimmed
  120.  * to the size of heap chunk size as specified at the time of the
  121.  * heap creation. No change in size is made if the last block is
  122.  * not free or large enough to allow the trimming. 0 returned on
  123.  * NULL or read-only heaps, or if an error has occurred.
  124.  */
  125. extern NCBI_XCONNECT_EXPORT TNCBI_Size HEAP_Trim(HEAP heap);
  126. /* Make a snapshot of a given heap. Return a read-only heap
  127.  * (like one after HEAP_Attach), which must be freed by a call to
  128.  * either HEAP_Detach or HEAP_Destroy when no longer needed.
  129.  * If a non-zero number provided (serial number) it is stored
  130.  * in the heap descriptor (zero serial is always turned into 1).
  131.  */
  132. extern NCBI_XCONNECT_EXPORT HEAP HEAP_CopySerial
  133. (const HEAP orig,         /* original heap to copy from               */
  134.  size_t     extra,        /* extra amount to add past the heap extent */
  135.  int        serial        /* serial number to assign (default is 1)   */
  136.  );
  137. #define HEAP_Copy(orig) HEAP_CopySerial(orig, 0, 0)
  138. /* Detach heap (previously attached by HEAP_Attach).
  139.  */
  140. extern NCBI_XCONNECT_EXPORT void HEAP_Detach(HEAP heap);
  141. /* Destroy heap (previously created by HEAP_Create).
  142.  */
  143. extern NCBI_XCONNECT_EXPORT void HEAP_Destroy(HEAP heap);
  144. /* Get base address of the heap
  145.  */
  146. extern NCBI_XCONNECT_EXPORT void* HEAP_Base(const HEAP heap);
  147. /* Get the extent of the heap
  148.  */
  149. extern NCBI_XCONNECT_EXPORT TNCBI_Size HEAP_Size(const HEAP heap);
  150. /* Get non-zero serial number of the heap.
  151.  * Return 0 if HEAP is passed as 0, or the heap is not a copy but original.
  152.  */
  153. extern NCBI_XCONNECT_EXPORT int HEAP_Serial(const HEAP heap);
  154. #ifdef __cplusplus
  155. } /* extern "C" */
  156. #endif
  157. /* @} */
  158. /*
  159.  * --------------------------------------------------------------------------
  160.  * $Log: ncbi_heapmgr.h,v $
  161.  * Revision 1000.0  2003/10/29 16:30:57  gouriano
  162.  * PRODUCTION: IMPORTED [ORIGINAL] Dev-tree R6.19
  163.  *
  164.  * Revision 6.19  2003/09/23 21:00:53  lavr
  165.  * +HEAP_AttachEx()
  166.  *
  167.  * Revision 6.18  2003/09/02 20:45:45  lavr
  168.  * -<connect/connect_export.h> -- now included from <connect/ncbi_types.h>
  169.  *
  170.  * Revision 6.17  2003/08/28 21:09:37  lavr
  171.  * Accept (and allocate) additional heap extent in HEAP_CopySerial()
  172.  *
  173.  * Revision 6.16  2003/08/25 14:50:10  lavr
  174.  * Heap arena ptrs changed to be "void*";  expand routine to take user arg
  175.  *
  176.  * Revision 6.15  2003/07/31 17:53:43  lavr
  177.  * +HEAP_Trim()
  178.  *
  179.  * Revision 6.14  2003/04/09 17:58:51  siyan
  180.  * Added doxygen support
  181.  *
  182.  * Revision 6.13  2003/01/08 01:59:32  lavr
  183.  * DLL-ize CONNECT library for MSVC (add NCBI_XCONNECT_EXPORT)
  184.  *
  185.  * Revision 6.12  2002/09/25 20:08:43  lavr
  186.  * Added table to explain expand callback inputs and outputs
  187.  *
  188.  * Revision 6.11  2002/09/19 18:00:58  lavr
  189.  * Header file guard macro changed; log moved to the end
  190.  *
  191.  * Revision 6.10  2002/04/13 06:33:22  lavr
  192.  * +HEAP_Base(), +HEAP_Size(), +HEAP_Serial(), new HEAP_CopySerial()
  193.  *
  194.  * Revision 6.9  2001/07/03 20:23:46  lavr
  195.  * Added function: HEAP_Copy()
  196.  *
  197.  * Revision 6.8  2001/06/19 20:16:19  lavr
  198.  * Added #include <connect/ncbi_types.h>
  199.  *
  200.  * Revision 6.7  2001/06/19 19:09:35  lavr
  201.  * Type change: size_t -> TNCBI_Size; time_t -> TNCBI_Time
  202.  *
  203.  * Revision 6.6  2000/10/05 21:25:45  lavr
  204.  * ncbiconf.h removed
  205.  *
  206.  * Revision 6.5  2000/10/05 21:09:52  lavr
  207.  * ncbiconf.h included
  208.  *
  209.  * Revision 6.4  2000/05/23 21:41:05  lavr
  210.  * Alignment changed to 'double'
  211.  *
  212.  * Revision 6.3  2000/05/12 18:28:40  lavr
  213.  * First working revision
  214.  *
  215.  * ==========================================================================
  216.  */
  217. #endif /* CONNECT___NCBI_HEAPMGR__H */