|
131
|
1
|
|
|
2 /*
|
|
|
3 * Copyright (C) 1999-2006 by Digital Mars, www.digitalmars.com
|
|
|
4 * Written by Walter Bright
|
|
|
5 *
|
|
|
6 * This software is provided 'as-is', without any express or implied
|
|
|
7 * warranty. In no event will the authors be held liable for any damages
|
|
|
8 * arising from the use of this software.
|
|
|
9 *
|
|
|
10 * Permission is granted to anyone to use this software for any purpose,
|
|
|
11 * including commercial applications, and to alter it and redistribute it
|
|
|
12 * freely, subject to the following restrictions:
|
|
|
13 *
|
|
|
14 * o The origin of this software must not be misrepresented; you must not
|
|
|
15 * claim that you wrote the original software. If you use this software
|
|
|
16 * in a product, an acknowledgment in the product documentation would be
|
|
|
17 * appreciated but is not required.
|
|
|
18 * o Altered source versions must be plainly marked as such, and must not
|
|
|
19 * be misrepresented as being the original software.
|
|
|
20 * o This notice may not be removed or altered from any source
|
|
|
21 * distribution.
|
|
|
22 */
|
|
|
23
|
|
|
24
|
|
|
25 /**
|
|
|
26 * The garbage collector normally works behind the scenes without needing any
|
|
|
27 * specific interaction. These functions are for advanced applications that
|
|
|
28 * benefit from tuning the operation of the collector.
|
|
|
29 * Macros:
|
|
|
30 * WIKI=Phobos/StdGc
|
|
|
31 */
|
|
|
32
|
|
|
33 module std.gc;
|
|
|
34
|
|
|
35 import gcstats;
|
|
|
36
|
|
|
37 /**
|
|
|
38 * Add p to list of roots. Roots are references to memory allocated by the
|
|
|
39 collector that are maintained in memory outside the collector pool. The garbage
|
|
|
40 collector will by default look for roots in the stacks of each thread, the
|
|
|
41 registers, and the default static data segment. If roots are held elsewhere,
|
|
|
42 use addRoot() or addRange() to tell the collector not to free the memory it
|
|
|
43 points to.
|
|
|
44 */
|
|
|
45 void addRoot(void *p); // add p to list of roots
|
|
|
46
|
|
|
47 /**
|
|
|
48 * Remove p from list of roots.
|
|
|
49 */
|
|
|
50 void removeRoot(void *p); // remove p from list of roots
|
|
|
51
|
|
|
52 /**
|
|
|
53 * Add range to scan for roots.
|
|
|
54 */
|
|
|
55 void addRange(void *pbot, void *ptop); // add range to scan for roots
|
|
|
56
|
|
|
57 /**
|
|
|
58 * Remove range.
|
|
|
59 */
|
|
|
60 void removeRange(void *pbot); // remove range
|
|
|
61
|
|
|
62 /**
|
|
|
63 * Mark a gc allocated block of memory as possibly containing pointers.
|
|
|
64 */
|
|
|
65 void hasPointers(void* p);
|
|
|
66
|
|
|
67 /**
|
|
|
68 * Mark a gc allocated block of memory as definitely NOT containing pointers.
|
|
|
69 */
|
|
|
70 void hasNoPointers(void* p);
|
|
|
71
|
|
|
72 /**
|
|
|
73 * Mark a gc allocated block of memory pointed to by p as being populated with
|
|
|
74 * an array of TypeInfo ti (as many as will fit).
|
|
|
75 */
|
|
|
76 void setTypeInfo(TypeInfo ti, void* p);
|
|
|
77
|
|
|
78 /**
|
|
|
79 * Allocate nbytes of uninitialized data.
|
|
|
80 * The allocated memory will be scanned for pointers during
|
|
|
81 * a gc collection cycle, unless
|
|
|
82 * it is followed by a call to hasNoPointers().
|
|
|
83 */
|
|
|
84 void[] malloc(size_t nbytes);
|
|
|
85
|
|
|
86 /**
|
|
|
87 * Resize allocated memory block pointed to by p to be at least nbytes long.
|
|
|
88 * It will try to resize the memory block in place.
|
|
|
89 * If nbytes is 0, the memory block is free'd.
|
|
|
90 * If p is null, the memory block is allocated using malloc.
|
|
|
91 * The returned array may not be at the same location as the original
|
|
|
92 * memory block.
|
|
|
93 * The allocated memory will be scanned for pointers during
|
|
|
94 * a gc collection cycle, unless
|
|
|
95 * it is followed by a call to hasNoPointers().
|
|
|
96 */
|
|
|
97 void[] realloc(void* p, size_t nbytes);
|
|
|
98
|
|
|
99 /**
|
|
|
100 * Attempt to enlarge the memory block pointed to by p
|
|
|
101 * by at least minbytes beyond its current capacity,
|
|
|
102 * up to a maximum of maxbytes.
|
|
|
103 * Returns:
|
|
|
104 * 0 if could not extend p,
|
|
|
105 * total size of entire memory block if successful.
|
|
|
106 */
|
|
|
107 size_t extend(void* p, size_t minbytes, size_t maxbytes);
|
|
|
108
|
|
|
109 /**
|
|
|
110 * Returns capacity (size of the memory block) that p
|
|
|
111 * points to the beginning of.
|
|
|
112 * If p does not point into the gc memory pool, or does
|
|
|
113 * not point to the beginning of an allocated memory block,
|
|
|
114 * 0 is returned.
|
|
|
115 */
|
|
|
116 size_t capacity(void* p);
|
|
|
117
|
|
|
118 /**
|
|
|
119 * Set gc behavior to match that of 1.0.
|
|
|
120 */
|
|
|
121 void setV1_0();
|
|
|
122
|
|
|
123 /***********************************
|
|
|
124 * Run a full garbage collection cycle.
|
|
|
125 *
|
|
|
126 * The collector normally runs synchronously with a storage allocation request
|
|
|
127 (i.e. it never happens when in code that does not allocate memory). In some
|
|
|
128 circumstances, for example when a particular task is finished, it is convenient
|
|
|
129 to explicitly run the collector and free up all memory used by that task. It
|
|
|
130 can also be helpful to run a collection before starting a new task that would
|
|
|
131 be annoying if it ran a collection in the middle of that task. Explicitly
|
|
|
132 running a collection can also be done in a separate very low priority thread,
|
|
|
133 so that if the program is idly waiting for input, memory can be cleaned up.
|
|
|
134 */
|
|
|
135
|
|
|
136 void fullCollect();
|
|
|
137
|
|
|
138 /***********************************
|
|
|
139 * Run a generational garbage collection cycle.
|
|
|
140 * Takes less time than a fullcollect(), but isn't
|
|
|
141 * as effective.
|
|
|
142 */
|
|
|
143
|
|
|
144 void genCollect();
|
|
|
145
|
|
|
146 void genCollectNoStack();
|
|
|
147
|
|
|
148 /**
|
|
|
149 * Minimizes physical memory usage
|
|
|
150 */
|
|
|
151 void minimize();
|
|
|
152
|
|
|
153 /***************************************
|
|
|
154 * disable() temporarily disables garbage collection cycle, enable()
|
|
|
155 * then reenables them.
|
|
|
156 *
|
|
|
157 * This is used for brief time critical sections of code, so the amount of time
|
|
|
158 * it will take is predictable.
|
|
|
159 * If the collector runs out of memory while it is disabled, it will throw an
|
|
|
160 * std.outofmemory.OutOfMemoryException.
|
|
|
161 * The disable() function calls can be nested, but must be
|
|
|
162 * matched with corresponding enable() calls.
|
|
|
163 * By default collections are enabled.
|
|
|
164 */
|
|
|
165
|
|
|
166 void disable();
|
|
|
167
|
|
|
168 /**
|
|
|
169 * ditto
|
|
|
170 */
|
|
|
171 void enable();
|
|
|
172
|
|
|
173 void getStats(out GCStats stats);
|
|
|
174
|
|
|
175 /***************************************
|
|
|
176 * Get handle to the collector.
|
|
|
177 */
|
|
|
178
|
|
|
179 void* getGCHandle();
|
|
|
180
|
|
|
181 /***************************************
|
|
|
182 * Set handle to the collector.
|
|
|
183 */
|
|
|
184
|
|
|
185 void setGCHandle(void* p);
|
|
|
186
|
|
|
187 void endGCHandle();
|
|
|
188
|
|
|
189 extern (C)
|
|
|
190 {
|
|
|
191 void gc_init();
|
|
|
192 void gc_term();
|
|
|
193 }
|
