NCBI C++ ToolKit
ncbi_heapmgr.h
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CONNECT___NCBI_HEAPMGR__H
2 #define CONNECT___NCBI_HEAPMGR__H
3 
4 /* $Id: ncbi_heapmgr.h 94957 2021-09-24 00:47:12Z lavr $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Anton Lavrentiev, Denis Vakatov
30  *
31  * File Description:
32  * Simple heap manager with a primitive garbage collection
33  *
34  */
35 
36 #include <connect/ncbi_types.h>
37 
38 
39 /** @addtogroup ServiceSupport
40  *
41  * @{
42  */
43 
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 
49 
50 /* Heap handle
51  */
52 struct SHEAP_tag;
53 typedef struct SHEAP_tag* HEAP;
54 
55 
56 /* Header of a heap block
57  */
58 typedef struct {
59  unsigned int flag; /* (flag & 1) == 0 if the block is vacant; *
60  * other bits reserved, do not assume their values! */
61  TNCBI_Size size; /* size of the block (including this header), bytes */
62 } SHEAP_Block;
63 
64 
65 /* Callback to resize the heap (a la 'realloc').
66  * NOTE: the returned address must be aligned at the 'double' boundary!
67  *
68  * old_base | new_size | Expected result
69  * ------------+------------+--------------------------------------------------
70  * non-NULL | 0 | Deallocate old_base, return 0
71  * non-NULL | non-zero | Reallocate to the requested size, return new base
72  * 0 | non-zero | Allocate anew, return base (return 0 on error)
73  * 0 | 0 | Do nothing, return 0
74  * ------------+------------+--------------------------------------------------
75  * Note that reallocation can request either to expand or to shrink the heap
76  * extent. When (re-)allocation fails, the callback should return 0 (and must
77  * retain the original heap extent / content, if any). When expected to return
78  * 0, this callback must always do so.
79  */
80 typedef void* (*FHEAP_Resize)
81 (void* old_base, /* current base of the heap to be expanded */
82  TNCBI_Size new_size, /* requested new heap size (zero to deallocate heap) */
83  void* auxarg /* user-supplied argument, see HEAP_Create() below */
84  );
85 
86 
87 /* Create new heap.
88  * NOTE: the initial heap base must be aligned at a 'double' boundary!
89  */
91 (void* base, /* initial heap base (use "resize" if NULL) */
92  TNCBI_Size size, /* initial heap size */
93  TNCBI_Size chunk_size, /* minimal increment size */
94  FHEAP_Resize resize, /* NULL if not resizeable */
95  void* auxarg /* a user argument to pass to "resize" */
96  );
97 
98 
99 /* Attach to an already existing heap (in read-only mode), calculating the heap
100  * extent by a heap end marker (but only within the maximal specified size).
101  */
103 (const void* base, /* base of the heap to attach to */
104  TNCBI_Size maxsize, /* maximal heap extent, or 0 for unlimited search */
105  int serial /* serial number to assign */
106  );
107 
108 /* Expedited HEAP_Attach() that does not calculate heap extent on its own */
110 (const void* base, /* base of the heap to attach to */
111  TNCBI_Size size, /* heap extent -- must be non-0 for non-NULL base */
112  int serial /* serial number to assign */
113  );
114 
115 
116 /* Allocate a new block of memory in the heap toward either the base or the end
117  * of the heap, depending on the "hint" parameter:
118  * "hint" == 0 for base;
119  * "hint" != 0 for end.
120  * Return NULL if allocation has failed.
121  */
123 (HEAP heap, /* heap handle */
124  TNCBI_Size size, /* data size of the block to accommodate */
125  int/*bool*/ hint
126  );
127 
128 
129 /* Deallocate a block pointed to by "ptr".
130  */
132 (HEAP heap, /* heap handle */
133  SHEAP_Block* ptr /* block to deallocate */
134  );
135 
136 
137 /* Deallocate a block pointed to by "ptr" and having "prev" as its predecessor
138  * (NULL if "ptr" is the first on the heap) -- a faster variant of HEAP_Free().
139  * NOTE: Since the block pointed to by "ptr" may cause free blocks to
140  * coalesce, to use this call again while walking the heap, the following rule
141  * must be utilized: If "prev" was free, "prev" must not get advanced;
142  * otherwise, "prev" must be updated with "ptr"'s value.
143  * As an exception, if "prev" points to a used block and "prev"'s next block is
144  * not "ptr", but a free block, whose next is "ptr", then "prev" gets bumped up
145  * internally to that free block's pointer value.
146  * NOTE: This call will be removed.
147  */
149 (HEAP heap, /* heap handle */
150  SHEAP_Block* ptr, /* block to deallocate */
151  const SHEAP_Block* prev /* block's predecessor */
152  );
153 
154 
155 /* Iterate through the heap blocks.
156  * Return pointer to the block following the block "prev".
157  * Return NULL if "prev" is the last block of the heap.
158  */
160 (const HEAP heap, /* heap handle */
161  const SHEAP_Block* prev /* if 0, then get the first heap block */
162  );
163 
164 
165 /* Same as HEAP_Walk() but skip over free blocks so that only used blocks show
166  * (nevertheless it can also accept prev pointing to a free block).
167  */
169 (const HEAP heap, /* heap handle */
170  const SHEAP_Block* prev /* if 0, then get the first used heap block */
171  );
172 
173 
174 /* Trim the heap, making garbage collection first. Returned is the resultant
175  * heap, which has its last block (if any) trimmed to the size of the heap
176  * chunk size as specified at the time of the heap creation. No change in size
177  * is made if the last block is not free or not large enough to allow the
178  * trimming. NULL gets returned on NULL or read-only heaps, or on a resize
179  * error.
180  * Note that trimming may cause the entire heap extent (of an empty heap) to
181  * deallocate (so that HEAP_Base() and HEAP_Size() will both return 0).
182  */
184 
185 
186 /* Make a snapshot of a given heap. Return a read-only heap (like the one
187  * after HEAP_Attach[Fast]()), which must be freed by a call to either
188  * HEAP_Detach() or HEAP_Destroy() when no longer needed.
189  * A copy is created reference-counted (with the initial ref.count set to 1).
190  */
192 (const HEAP orig, /* original heap to copy from */
193  size_t extra, /* extra amount to add past the heap extent */
194  int serial /* serial number to assign */
195  );
196 
197 
198 /* Add reference counter to the given copy heap (no effect on a heap, which has
199  * been HEAP_Create()'d or HEAP_Attach[Fast]()'d). The heap handle then will
200  * be destroyed only when the internal reference counter reaches 0.
201  * @warning No internal locking is provided.
202  * Return the resultant value of the reference counter.
203  */
204 extern NCBI_XCONNECT_EXPORT unsigned int HEAP_AddRef(HEAP heap);
205 
206 
207 /* Detach a heap (previously attached by HEAP_Attach[Fast]). For a copy heap,
208  * it decrements an internal ref. counter by one, and actually destroys the
209  * heap handle if and only if the counter has reached 0.
210  * @warning No internal locking of the reference counter is provided.
211  * For heaps that are results of the HEAP_Copy() call, both HEAP_Detach() and
212  * HEAP_Destroy() can be used interchangeably.
213  * Return the remaining value of the reference counter (0 if the heap is gone).
214  */
215 extern NCBI_XCONNECT_EXPORT unsigned int HEAP_Detach(HEAP heap);
216 
217 
218 /* Destroy the heap (previously created by HEAP_Create()).
219  * For copy heaps -- see comments for HEAP_Detach() above.
220  * Return the remaining value of the reference counter (0 if the heap is gone).
221  */
222 extern NCBI_XCONNECT_EXPORT unsigned int HEAP_Destroy(HEAP heap);
223 
224 
225 /* Get the base address of the heap. Return NULL if heap is passed as NULL, or
226  * when the heap is completely empty.
227  */
228 extern NCBI_XCONNECT_EXPORT void* HEAP_Base(const HEAP heap);
229 
230 
231 /* Get the extent of the heap. This is a very fast routine. Return 0 if heap
232  * is passed as NULL, or when the heap is completely empty.
233  */
235 
236 
237 /* Return the total used space on the heap. This is a very fast routine.
238  */
240 
241 
242 /* Return total vacant usable space on the heap. Involves heap walking.
243  */
245 
246 
247 /* Get a serial number of the heap as assigned by Attach or Copy.
248  * Return 0 if the heap is not a copy but the original, or passed as NULL.
249  */
250 extern NCBI_XCONNECT_EXPORT int HEAP_Serial(const HEAP heap);
251 
252 
253 /* Set heap access speed (and ignore second parameter):
254  * fast == eOn turns on fast heap operations (default);
255  * fast == eOff turns off fast heap operations (more checks, slower);
256  * fast == eDefault does not change the current setting.
257  * This call is intended for internal uses; and default settings (fast ops
258  * w/o structure integrity checks) should suffice for most users.
259  */
261 
262 
263 #ifdef __cplusplus
264 } /* extern "C" */
265 #endif
266 
267 
268 /* @} */
269 
270 #endif /* CONNECT___NCBI_HEAPMGR__H */
static const int chunk_size
static int heap[2 *(256+1+29)+1]
static DLIST_TYPE *DLIST_NAME() prev(DLIST_LIST_TYPE *list, DLIST_TYPE *item)
Definition: dlist.tmpl.h:61
SHEAP_Block * HEAP_Next(const HEAP heap, const SHEAP_Block *prev)
void * HEAP_Base(const HEAP heap)
void HEAP_Options(ESwitch fast, ESwitch unused)
SHEAP_Block * HEAP_Alloc(HEAP heap, TNCBI_Size size, int hint)
Definition: ncbi_heapmgr.c:640
HEAP HEAP_Copy(const HEAP orig, size_t extra, int serial)
SHEAP_Block * HEAP_Walk(const HEAP heap, const SHEAP_Block *prev)
HEAP HEAP_Create(void *base, TNCBI_Size size, TNCBI_Size chunk_size, FHEAP_Resize resize, void *auxarg)
Definition: ncbi_heapmgr.c:261
unsigned int HEAP_Destroy(HEAP heap)
void HEAP_Free(HEAP heap, SHEAP_Block *ptr)
Definition: ncbi_heapmgr.c:819
int HEAP_Serial(const HEAP heap)
HEAP HEAP_AttachFast(const void *base, TNCBI_Size size, int serial)
Definition: ncbi_heapmgr.c:308
TNCBI_Size size
Definition: ncbi_heapmgr.h:61
HEAP HEAP_Attach(const void *base, TNCBI_Size maxsize, int serial)
Definition: ncbi_heapmgr.c:338
void *(* FHEAP_Resize)(void *old_base, TNCBI_Size new_size, void *auxarg)
Definition: ncbi_heapmgr.h:81
struct SHEAP_tag * HEAP
Definition: ncbi_heapmgr.h:53
unsigned int flag
Definition: ncbi_heapmgr.h:59
void HEAP_FreeFast(HEAP heap, SHEAP_Block *ptr, const SHEAP_Block *prev)
Definition: ncbi_heapmgr.c:871
unsigned int HEAP_AddRef(HEAP heap)
TNCBI_Size HEAP_Idle(const HEAP heap)
HEAP HEAP_Trim(HEAP heap)
Definition: ncbi_heapmgr.c:931
unsigned int HEAP_Detach(HEAP heap)
TNCBI_Size HEAP_Size(const HEAP heap)
TNCBI_Size HEAP_Used(const HEAP heap)
enum ENcbiSwitch ESwitch
Aux.
unsigned int TNCBI_Size
Fixed-size analogs of size_t and time_t (mainly for IPC)
Definition: ncbi_types.h:144
#define NCBI_XCONNECT_EXPORT
where boath are integers</td > n< td ></td > n</tr > n< tr > n< td > tse</td > n< td > optional</td > n< td > String</td > n< td class=\"description\"> TSE option controls what blob is orig
static const CS_INT unused
Definition: long_binary.c:20
const struct ncbi::grid::netcache::search::fields::SIZE size
void resize(vector< SMethodDef > &container)
Modified on Wed Apr 17 13:10:49 2024 by modify_doxy.py rev. 669887