Mercurial > projects > ldc
comparison druntime/src/common/core/memory.d @ 759:d3eb054172f9
Added copy of druntime from DMD 2.020 modified for LDC.
author | Tomas Lindquist Olsen <tomas.l.olsen@gmail.com> |
---|---|
date | Tue, 11 Nov 2008 01:52:37 +0100 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
758:f04dde6e882c | 759:d3eb054172f9 |
---|---|
1 /** | |
2 * The memory module provides an interface to the garbage collector and to | |
3 * any other OS or API-level memory management facilities. | |
4 * | |
5 * Copyright: Copyright (c) 2005-2008, The D Runtime Project | |
6 * License: BSD Style, see LICENSE | |
7 * Authors: Sean Kelly | |
8 */ | |
9 module core.memory; | |
10 | |
11 | |
12 private | |
13 { | |
14 extern (C) void gc_init(); | |
15 extern (C) void gc_term(); | |
16 | |
17 extern (C) void gc_enable(); | |
18 extern (C) void gc_disable(); | |
19 extern (C) void gc_collect(); | |
20 extern (C) void gc_minimize(); | |
21 | |
22 extern (C) uint gc_getAttr( void* p ); | |
23 extern (C) uint gc_setAttr( void* p, uint a ); | |
24 extern (C) uint gc_clrAttr( void* p, uint a ); | |
25 | |
26 extern (C) void* gc_malloc( size_t sz, uint ba = 0 ); | |
27 extern (C) void* gc_calloc( size_t sz, uint ba = 0 ); | |
28 extern (C) void* gc_realloc( void* p, size_t sz, uint ba = 0 ); | |
29 extern (C) size_t gc_extend( void* p, size_t mx, size_t sz ); | |
30 extern (C) size_t gc_reserve( size_t sz ); | |
31 extern (C) void gc_free( void* p ); | |
32 | |
33 extern (C) void* gc_addrOf( void* p ); | |
34 extern (C) size_t gc_sizeOf( void* p ); | |
35 | |
36 struct BlkInfo_ | |
37 { | |
38 void* base; | |
39 size_t size; | |
40 uint attr; | |
41 } | |
42 | |
43 extern (C) BlkInfo_ gc_query( void* p ); | |
44 | |
45 extern (C) void gc_addRoot( void* p ); | |
46 extern (C) void gc_addRange( void* p, size_t sz ); | |
47 | |
48 extern (C) void gc_removeRoot( void* p ); | |
49 extern (C) void gc_removeRange( void* p ); | |
50 | |
51 extern (C) void* gc_getHandle(); | |
52 extern (C) void gc_setHandle( void* p ); | |
53 extern (C) void gc_endHandle(); | |
54 } | |
55 | |
56 | |
57 /** | |
58 * This struct encapsulates all garbage collection functionality for the D | |
59 * programming language. | |
60 */ | |
61 struct GC | |
62 { | |
63 /** | |
64 * Enables the garbage collector if collections have previously been | |
65 * suspended by a call to disable. This function is reentrant, and | |
66 * must be called once for every call to disable before the garbage | |
67 * collector is enabled. | |
68 */ | |
69 static void enable() | |
70 { | |
71 gc_enable(); | |
72 } | |
73 | |
74 | |
75 /** | |
76 * Disables the garbage collector. This function is reentrant, but | |
77 * enable must be called once for each call to disable. | |
78 */ | |
79 static void disable() | |
80 { | |
81 gc_disable(); | |
82 } | |
83 | |
84 | |
85 /** | |
86 * Begins a full collection. While the meaning of this may change based | |
87 * on the garbage collector implementation, typical behavior is to scan | |
88 * all stack segments for roots, mark accessible memory blocks as alive, | |
89 * and then to reclaim free space. This action may need to suspend all | |
90 * running threads for at least part of the collection process. | |
91 */ | |
92 static void collect() | |
93 { | |
94 gc_collect(); | |
95 } | |
96 | |
97 /** | |
98 * Indicates that the managed memory space be minimized by returning free | |
99 * physical memory to the operating system. The amount of free memory | |
100 * returned depends on the allocator design and on program behavior. | |
101 */ | |
102 static void minimize() | |
103 { | |
104 gc_minimize(); | |
105 } | |
106 | |
107 | |
108 /** | |
109 * Elements for a bit field representing memory block attributes. These | |
110 * are manipulated via the getAttr, setAttr, clrAttr functions. | |
111 */ | |
112 enum BlkAttr : uint | |
113 { | |
114 FINALIZE = 0b0000_0001, /// Finalize the data in this block on collect. | |
115 NO_SCAN = 0b0000_0010, /// Do not scan through this block on collect. | |
116 NO_MOVE = 0b0000_0100 /// Do not move this memory block on collect. | |
117 } | |
118 | |
119 | |
120 /** | |
121 * Contains aggregate information about a block of managed memory. The | |
122 * purpose of this struct is to support a more efficient query style in | |
123 * instances where detailed information is needed. | |
124 * | |
125 * base = A pointer to the base of the block in question. | |
126 * size = The size of the block, calculated from base. | |
127 * attr = Attribute bits set on the memory block. | |
128 */ | |
129 alias BlkInfo_ BlkInfo; | |
130 | |
131 | |
132 /** | |
133 * Returns a bit field representing all block attributes set for the memory | |
134 * referenced by p. If p references memory not originally allocated by | |
135 * this garbage collector, points to the interior of a memory block, or if | |
136 * p is null, zero will be returned. | |
137 * | |
138 * Params: | |
139 * p = A pointer to the root of a valid memory block or to null. | |
140 * | |
141 * Returns: | |
142 * A bit field containing any bits set for the memory block referenced by | |
143 * p or zero on error. | |
144 */ | |
145 static uint getAttr( void* p ) | |
146 { | |
147 return gc_getAttr( p ); | |
148 } | |
149 | |
150 | |
151 /** | |
152 * Sets the specified bits for the memory references by p. If p references | |
153 * memory not originally allocated by this garbage collector, points to the | |
154 * interior of a memory block, or if p is null, no action will be | |
155 * performed. | |
156 * | |
157 * Params: | |
158 * p = A pointer to the root of a valid memory block or to null. | |
159 * a = A bit field containing any bits to set for this memory block. | |
160 * | |
161 * The result of a call to getAttr after the specified bits have been | |
162 * set. | |
163 */ | |
164 static uint setAttr( void* p, uint a ) | |
165 { | |
166 return gc_setAttr( p, a ); | |
167 } | |
168 | |
169 | |
170 /** | |
171 * Clears the specified bits for the memory references by p. If p | |
172 * references memory not originally allocated by this garbage collector, | |
173 * points to the interior of a memory block, or if p is null, no action | |
174 * will be performed. | |
175 * | |
176 * Params: | |
177 * p = A pointer to the root of a valid memory block or to null. | |
178 * a = A bit field containing any bits to clear for this memory block. | |
179 * | |
180 * Returns: | |
181 * The result of a call to getAttr after the specified bits have been | |
182 * cleared. | |
183 */ | |
184 static uint clrAttr( void* p, uint a ) | |
185 { | |
186 return gc_clrAttr( p, a ); | |
187 } | |
188 | |
189 | |
190 /** | |
191 * Requests an aligned block of managed memory from the garbage collector. | |
192 * This memory may be deleted at will with a call to free, or it may be | |
193 * discarded and cleaned up automatically during a collection run. If | |
194 * allocation fails, this function will call onOutOfMemory which is | |
195 * expected to throw an OutOfMemoryException. | |
196 * | |
197 * Params: | |
198 * sz = The desired allocation size in bytes. | |
199 * ba = A bitmask of the attributes to set on this block. | |
200 * | |
201 * Returns: | |
202 * A reference to the allocated memory or null if insufficient memory | |
203 * is available. | |
204 * | |
205 * Throws: | |
206 * OutOfMemoryException on allocation failure. | |
207 */ | |
208 static void* malloc( size_t sz, uint ba = 0 ) | |
209 { | |
210 return gc_malloc( sz, ba ); | |
211 } | |
212 | |
213 | |
214 /** | |
215 * Requests an aligned block of managed memory from the garbage collector, | |
216 * which is initialized with all bits set to zero. This memory may be | |
217 * deleted at will with a call to free, or it may be discarded and cleaned | |
218 * up automatically during a collection run. If allocation fails, this | |
219 * function will call onOutOfMemory which is expected to throw an | |
220 * OutOfMemoryException. | |
221 * | |
222 * Params: | |
223 * sz = The desired allocation size in bytes. | |
224 * ba = A bitmask of the attributes to set on this block. | |
225 * | |
226 * Returns: | |
227 * A reference to the allocated memory or null if insufficient memory | |
228 * is available. | |
229 * | |
230 * Throws: | |
231 * OutOfMemoryException on allocation failure. | |
232 */ | |
233 static void* calloc( size_t sz, uint ba = 0 ) | |
234 { | |
235 return gc_calloc( sz, ba ); | |
236 } | |
237 | |
238 | |
239 /** | |
240 * If sz is zero, the memory referenced by p will be deallocated as if | |
241 * by a call to free. A new memory block of size sz will then be | |
242 * allocated as if by a call to malloc, or the implementation may instead | |
243 * resize the memory block in place. The contents of the new memory block | |
244 * will be the same as the contents of the old memory block, up to the | |
245 * lesser of the new and old sizes. Note that existing memory will only | |
246 * be freed by realloc if sz is equal to zero. The garbage collector is | |
247 * otherwise expected to later reclaim the memory block if it is unused. | |
248 * If allocation fails, this function will call onOutOfMemory which is | |
249 * expected to throw an OutOfMemoryException. If p references memory not | |
250 * originally allocated by this garbage collector, or if it points to the | |
251 * interior of a memory block, no action will be taken. If ba is zero | |
252 * (the default) and p references the head of a valid, known memory block | |
253 * then any bits set on the current block will be set on the new block if a | |
254 * reallocation is required. If ba is not zero and p references the head | |
255 * of a valid, known memory block then the bits in ba will replace those on | |
256 * the current memory block and will also be set on the new block if a | |
257 * reallocation is required. | |
258 * | |
259 * Params: | |
260 * p = A pointer to the root of a valid memory block or to null. | |
261 * sz = The desired allocation size in bytes. | |
262 * ba = A bitmask of the attributes to set on this block. | |
263 * | |
264 * Returns: | |
265 * A reference to the allocated memory on success or null if sz is | |
266 * zero. On failure, the original value of p is returned. | |
267 * | |
268 * Throws: | |
269 * OutOfMemoryException on allocation failure. | |
270 */ | |
271 static void* realloc( void* p, size_t sz, uint ba = 0 ) | |
272 { | |
273 return gc_realloc( p, sz, ba ); | |
274 } | |
275 | |
276 | |
277 /** | |
278 * Requests that the managed memory block referenced by p be extended in | |
279 * place by at least mx bytes, with a desired extension of sz bytes. If an | |
280 * extension of the required size is not possible, if p references memory | |
281 * not originally allocated by this garbage collector, or if p points to | |
282 * the interior of a memory block, no action will be taken. | |
283 * | |
284 * Params: | |
285 * mx = The minimum extension size in bytes. | |
286 * sz = The desired extension size in bytes. | |
287 * | |
288 * Returns: | |
289 * The size in bytes of the extended memory block referenced by p or zero | |
290 * if no extension occurred. | |
291 */ | |
292 static size_t extend( void* p, size_t mx, size_t sz ) | |
293 { | |
294 return gc_extend( p, mx, sz ); | |
295 } | |
296 | |
297 | |
298 /** | |
299 * Requests that at least sz bytes of memory be obtained from the operating | |
300 * system and marked as free. | |
301 * | |
302 * Params: | |
303 * sz = The desired size in bytes. | |
304 * | |
305 * Returns: | |
306 * The actual number of bytes reserved or zero on error. | |
307 */ | |
308 static size_t reserve( size_t sz ) | |
309 { | |
310 return gc_reserve( sz ); | |
311 } | |
312 | |
313 | |
314 /** | |
315 * Deallocates the memory referenced by p. If p is null, no action | |
316 * occurs. If p references memory not originally allocated by this | |
317 * garbage collector, or if it points to the interior of a memory block, | |
318 * no action will be taken. The block will not be finalized regardless | |
319 * of whether the FINALIZE attribute is set. If finalization is desired, | |
320 * use delete instead. | |
321 * | |
322 * Params: | |
323 * p = A pointer to the root of a valid memory block or to null. | |
324 */ | |
325 static void free( void* p ) | |
326 { | |
327 gc_free( p ); | |
328 } | |
329 | |
330 | |
331 /** | |
332 * Returns the base address of the memory block containing p. This value | |
333 * is useful to determine whether p is an interior pointer, and the result | |
334 * may be passed to routines such as sizeOf which may otherwise fail. If p | |
335 * references memory not originally allocated by this garbage collector, if | |
336 * p is null, or if the garbage collector does not support this operation, | |
337 * null will be returned. | |
338 * | |
339 * Params: | |
340 * p = A pointer to the root or the interior of a valid memory block or to | |
341 * null. | |
342 * | |
343 * Returns: | |
344 * The base address of the memory block referenced by p or null on error. | |
345 */ | |
346 static void* addrOf( void* p ) | |
347 { | |
348 return gc_addrOf( p ); | |
349 } | |
350 | |
351 | |
352 /** | |
353 * Returns the true size of the memory block referenced by p. This value | |
354 * represents the maximum number of bytes for which a call to realloc may | |
355 * resize the existing block in place. If p references memory not | |
356 * originally allocated by this garbage collector, points to the interior | |
357 * of a memory block, or if p is null, zero will be returned. | |
358 * | |
359 * Params: | |
360 * p = A pointer to the root of a valid memory block or to null. | |
361 * | |
362 * Returns: | |
363 * The size in bytes of the memory block referenced by p or zero on error. | |
364 */ | |
365 static size_t sizeOf( void* p ) | |
366 { | |
367 return gc_sizeOf( p ); | |
368 } | |
369 | |
370 | |
371 /** | |
372 * Returns aggregate information about the memory block containing p. If p | |
373 * references memory not originally allocated by this garbage collector, if | |
374 * p is null, or if the garbage collector does not support this operation, | |
375 * BlkInfo.init will be returned. Typically, support for this operation | |
376 * is dependent on support for addrOf. | |
377 * | |
378 * Params: | |
379 * p = A pointer to the root or the interior of a valid memory block or to | |
380 * null. | |
381 * | |
382 * Returns: | |
383 * Information regarding the memory block referenced by p or BlkInfo.init | |
384 * on error. | |
385 */ | |
386 static BlkInfo query( void* p ) | |
387 { | |
388 return gc_query( p ); | |
389 } | |
390 | |
391 | |
392 /** | |
393 * Adds the memory address referenced by p to an internal list of roots to | |
394 * be scanned during a collection. If p is null, no operation is | |
395 * performed. | |
396 * | |
397 * Params: | |
398 * p = A pointer to a valid memory address or to null. | |
399 */ | |
400 static void addRoot( void* p ) | |
401 { | |
402 gc_addRoot( p ); | |
403 } | |
404 | |
405 | |
406 /** | |
407 * Adds the memory block referenced by p and of size sz to an internal list | |
408 * of ranges to be scanned during a collection. If p is null, no operation | |
409 * is performed. | |
410 * | |
411 * Params: | |
412 * p = A pointer to a valid memory address or to null. | |
413 * sz = The size in bytes of the block to add. If sz is zero then the | |
414 * no operation will occur. If p is null then sz must be zero. | |
415 */ | |
416 static void addRange( void* p, size_t sz ) | |
417 { | |
418 gc_addRange( p, sz ); | |
419 } | |
420 | |
421 | |
422 /** | |
423 * Removes the memory block referenced by p from an internal list of roots | |
424 * to be scanned during a collection. If p is null or does not represent | |
425 * a value previously passed to add(void*) then no operation is performed. | |
426 * | |
427 * p = A pointer to a valid memory address or to null. | |
428 */ | |
429 static void removeRoot( void* p ) | |
430 { | |
431 gc_removeRoot( p ); | |
432 } | |
433 | |
434 | |
435 /** | |
436 * Removes the memory block referenced by p from an internal list of ranges | |
437 * to be scanned during a collection. If p is null or does not represent | |
438 * a value previously passed to add(void*, size_t) then no operation is | |
439 * performed. | |
440 * | |
441 * Params: | |
442 * p = A pointer to a valid memory address or to null. | |
443 */ | |
444 static void removeRange( void* p ) | |
445 { | |
446 gc_removeRange( p ); | |
447 } | |
448 | |
449 /** | |
450 * Get handle to the collector. | |
451 * The only thing that can be done with this handle is pass it to | |
452 * setHandle(). getHandle/setHandle/endHandle work together so that | |
453 * if there are multiple instances of the gc running, only one instance | |
454 * can be set to run. | |
455 * The most common case of this is under Windows where a D application | |
456 * calls functions in a DLL that is implemented in D. | |
457 */ | |
458 | |
459 static void* getHandle() | |
460 { | |
461 return gc_getHandle(); | |
462 } | |
463 | |
464 /** | |
465 * Set handle to the collector. | |
466 * The handle p is an opaque handle, acquired by a call to | |
467 * getHandle(). | |
468 */ | |
469 | |
470 static void setHandle(void* p) | |
471 { | |
472 gc_setHandle(p); | |
473 } | |
474 | |
475 /** | |
476 * Call when done using the collector specified by the | |
477 * call to setHandle(). | |
478 */ | |
479 | |
480 static void endHandle() | |
481 { | |
482 gc_endHandle(); | |
483 } | |
484 } |