72
72
* 0 | 0 | Do nothing, return 0
73
73
* ------------+------------+--------------------------------------------------
74
74
* Note that reallocation can request either to expand or to shrink the
75
* heap extent. When (re-)allocation fails, the callback should return 0.
76
* When expected to return 0, this callback has to always do so.
75
* heap extent. When (re-)allocation fails, the callback should return 0
76
* (and must not change the original heap extent / content, if any).
77
* When expected to return 0, this callback must always do so.
78
typedef void* (*FHEAP_Expand)
79
typedef void* (*FHEAP_Resize)
79
80
(void* old_base, /* current base of the heap to be expanded */
80
81
TNCBI_Size new_size, /* requested new heap size (zero to deallocate heap) */
81
82
void* arg /* user-supplied argument, see HEAP_Create() below */
85
86
/* Create new heap.
86
* NOTE: the initial heap base must be aligned on a 'double' boundary!
87
* NOTE: the initial heap base must be aligned with a 'double' boundary!
88
89
extern NCBI_XCONNECT_EXPORT HEAP HEAP_Create
89
(void* base, /* initial heap base (use "expand" if NULL) */
90
(void* base, /* initial heap base (use "resize" if NULL) */
90
91
TNCBI_Size size, /* initial heap size */
91
92
TNCBI_Size chunk_size, /* minimal increment size */
92
FHEAP_Expand expand, /* NULL if not expandable */
93
void* arg /* arg to pass to expand (if any) */
93
FHEAP_Resize resize, /* NULL if not resizeable */
94
void* arg /* user argument to pass to "resize" */
97
98
/* Attach to an already existing heap (in read-only mode).
99
100
extern NCBI_XCONNECT_EXPORT HEAP HEAP_Attach
100
(const void* base /* base of the heap to attach to */
101
(const void* base, /* base of the heap to attach to */
102
int serial /* serial number to assign */
105
/* faster HEAP_Attach() that does not calculate heap size on its own */
103
106
extern NCBI_XCONNECT_EXPORT HEAP HEAP_AttachEx
107
(const void* base, /* base of the heap to attach to */
108
TNCBI_Size size, /* heap extent -- must be non-0 for non-NULL base */
109
int serial /* serial number to assign */
109
113
/* Allocate a new block of memory in the heap.
111
115
extern NCBI_XCONNECT_EXPORT SHEAP_Block* HEAP_Alloc
112
(HEAP heap, /* heap handle */
113
TNCBI_Size size /* data size of the block to contain */
116
(HEAP heap, /* heap handle */
117
TNCBI_Size size /* data size of the block to accomodate */
117
/* Deallocate block pointed by "block_ptr".
121
/* Deallocate a block pointed to by "block_ptr".
119
123
extern NCBI_XCONNECT_EXPORT void HEAP_Free
120
124
(HEAP heap, /* heap handle */
135
/* Trim the heap, making garbage collection first. Returned is
136
* the size of the resultant heap, which has its last block trimmed
137
* to the size of heap chunk size as specified at the time of the
138
* heap creation. No change in size is made if the last block is
139
* not free or large enough to allow the trimming. 0 returned on
140
* NULL or read-only heaps, or if an error has occurred.
139
/* Trim the heap, making garbage collection first. Returned is
140
* the resultant heap, which has its last block (if any) trimmed to the
141
* size of heap chunk size as specified at the time of the heap creation.
142
* No change in size is made if the last block is not free or large
143
* enough to allow the trimming. NULL gets returned on NULL or read-only
144
* heaps, or if a resize error has occurred.
145
* Note that trimming can cause the entire heap extent (of an empty heap)
146
* to deallocate (so that HEAP_Base() and HEAP_Size() will return 0).
142
extern NCBI_XCONNECT_EXPORT TNCBI_Size HEAP_Trim(HEAP heap);
148
extern NCBI_XCONNECT_EXPORT HEAP HEAP_Trim(HEAP heap);
145
151
/* Make a snapshot of a given heap. Return a read-only heap
146
* (like one after HEAP_Attach), which must be freed by a call to
147
* either HEAP_Detach or HEAP_Destroy when no longer needed.
148
* If a non-zero number provided (serial number) it is stored
149
* in the heap descriptor (zero serial is always turned into 1).
152
* (like the one after HEAP_Attach[Ex]), which must be freed by a call
153
* to either HEAP_Detach() or HEAP_Destroy() when no longer needed.
154
* A copy is created reference-counted (with the initial ref.count set to 1).
151
extern NCBI_XCONNECT_EXPORT HEAP HEAP_CopySerial
152
(const HEAP orig, /* original heap to copy from */
153
size_t extra, /* extra amount to add past the heap extent */
154
int serial /* serial number to assign (default is 1) */
156
extern NCBI_XCONNECT_EXPORT HEAP HEAP_Copy
157
(const HEAP orig, /* original heap to copy from */
158
size_t extra, /* extra amount to add past the heap extent */
159
int serial /* serial number to assign */
157
#define HEAP_Copy(orig) HEAP_CopySerial(orig, 0, 0)
160
/* Detach heap (previously attached by HEAP_Attach).
163
/* Add reference counter to the given copy heap (no effect on
164
* a heap, which have been HEAP_Create()'d or HEAP_Attach[Ex]()'d).
165
* The heap handle then will be destroyed only when the internal
166
* reference counter reaches 0. No internal locking is provided.
168
extern NCBI_XCONNECT_EXPORT void HEAP_AddRef(HEAP heap);
171
/* Detach heap (previously attached by HEAP_Attach[Ex]).
172
* For copy heap, it decrements an internal ref. counter by one, and
173
* destroys the heap handle if and only if the counter has reached 0.
174
* No internal locking of the reference counter is provided.
175
* For heaps that are results of HEAP_Copy() call,
176
* both HEAP_Detach() and HEAP_Destroy() can be used interchangeably.
162
178
extern NCBI_XCONNECT_EXPORT void HEAP_Detach(HEAP heap);
165
/* Destroy heap (previously created by HEAP_Create).
181
/* Destroy heap (previously created by HEAP_Create()).
182
* For copy heaps -- see comments for HEAP_Detach() above.
167
184
extern NCBI_XCONNECT_EXPORT void HEAP_Destroy(HEAP heap);
170
187
/* Get base address of the heap.
188
* Return NULL if heap is passed as NULL, or when the heap is completely empty.
172
190
extern NCBI_XCONNECT_EXPORT void* HEAP_Base(const HEAP heap);
175
193
/* Get the extent of the heap.
194
* Return 0 if heap is passed as NULL, or when the heap is completely empty.
177
196
extern NCBI_XCONNECT_EXPORT TNCBI_Size HEAP_Size(const HEAP heap);
180
199
/* Get non-zero serial number of the heap.
181
* Return 0 if HEAP is passed as 0, or the heap is not a copy but the original.
200
* Return 0 if heap is passed as NULL,
201
* or the heap is not a copy but the original.
183
203
extern NCBI_XCONNECT_EXPORT int HEAP_Serial(const HEAP heap);
added
removed
connect/ncbi_heapmgr.h
