Debian Codegraph @

gc/include/gc_cpp.h

raw
1 /*
2 * Copyright (c) 1994 by Xerox Corporation. All rights reserved.
3 *
4 * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
5 * OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
6 *
7 * Permission is hereby granted to use or copy this program for any
8 * purpose, provided the above notices are retained on all copies.
9 * Permission to modify the code and to distribute modified code is
10 * granted, provided the above notices are retained, and a notice that
11 * the code was modified is included with the above copyright notice.
12 */
13
14 #ifndef GC_CPP_H
15 #define GC_CPP_H
16
17 /****************************************************************************
18 C++ Interface to the Boehm Collector
19
20 John R. Ellis and Jesse Hull
21
22 This interface provides access to the Boehm collector. It provides
23 basic facilities similar to those described in "Safe, Efficient
24 Garbage Collection for C++", by John R. Ellis and David L. Detlefs
25 (ftp://ftp.parc.xerox.com/pub/ellis/gc).
26
27 All heap-allocated objects are either "collectible" or
28 "uncollectible". Programs must explicitly delete uncollectible
29 objects, whereas the garbage collector will automatically delete
30 collectible objects when it discovers them to be inaccessible.
31 Collectible objects may freely point at uncollectible objects and vice
32 versa.
33
34 Objects allocated with the built-in "::operator new" are uncollectible.
35
36 Objects derived from class "gc" are collectible. For example:
37
38 class A: public gc {...};
39 A* a = new A; // a is collectible.
40
41 Collectible instances of non-class types can be allocated using the GC
42 (or UseGC) placement:
43
44 typedef int A[ 10 ];
45 A* a = new (GC) A;
46
47 Uncollectible instances of classes derived from "gc" can be allocated
48 using the NoGC placement:
49
50 class A: public gc {...};
51 A* a = new (NoGC) A; // a is uncollectible.
52
53 The new(PointerFreeGC) syntax allows the allocation of collectible
54 objects that are not scanned by the collector. This useful if you
55 are allocating compressed data, bitmaps, or network packets. (In
56 the latter case, it may remove danger of unfriendly network packets
57 intentionally containing values that cause spurious memory retention.)
58
59 Both uncollectible and collectible objects can be explicitly deleted
60 with "delete", which invokes an object's destructors and frees its
61 storage immediately.
62
63 A collectible object may have a clean-up function, which will be
64 invoked when the collector discovers the object to be inaccessible.
65 An object derived from "gc_cleanup" or containing a member derived
66 from "gc_cleanup" has a default clean-up function that invokes the
67 object's destructors. Explicit clean-up functions may be specified as
68 an additional placement argument:
69
70 A* a = ::new (GC, MyCleanup) A;
71
72 An object is considered "accessible" by the collector if it can be
73 reached by a path of pointers from static variables, automatic
74 variables of active functions, or from some object with clean-up
75 enabled; pointers from an object to itself are ignored.
76
77 Thus, if objects A and B both have clean-up functions, and A points at
78 B, B is considered accessible. After A's clean-up is invoked and its
79 storage released, B will then become inaccessible and will have its
80 clean-up invoked. If A points at B and B points to A, forming a
81 cycle, then that's considered a storage leak, and neither will be
82 collectible. See the interface gc.h for low-level facilities for
83 handling such cycles of objects with clean-up.
84
85 The collector cannot guarantee that it will find all inaccessible
86 objects. In practice, it finds almost all of them.
87
88
89 Cautions:
90
91 1. Be sure the collector has been augmented with "make c++" or
92 "--enable-cplusplus".
93
94 2. If your compiler supports the new "operator new[]" syntax, then
95 add -DGC_OPERATOR_NEW_ARRAY to the Makefile.
96
97 If your compiler doesn't support "operator new[]", beware that an
98 array of type T, where T is derived from "gc", may or may not be
99 allocated as a collectible object (it depends on the compiler). Use
100 the explicit GC placement to make the array collectible. For example:
101
102 class A: public gc {...};
103 A* a1 = new A[ 10 ]; // collectible or uncollectible?
104 A* a2 = new (GC) A[ 10 ]; // collectible.
105
106 3. The destructors of collectible arrays of objects derived from
107 "gc_cleanup" will not be invoked properly. For example:
108
109 class A: public gc_cleanup {...};
110 A* a = new (GC) A[ 10 ]; // destructors not invoked correctly
111
112 Typically, only the destructor for the first element of the array will
113 be invoked when the array is garbage-collected. To get all the
114 destructors of any array executed, you must supply an explicit
115 clean-up function:
116
117 A* a = new (GC, MyCleanUp) A[ 10 ];
118
119 (Implementing clean-up of arrays correctly, portably, and in a way
120 that preserves the correct exception semantics requires a language
121 extension, e.g. the "gc" keyword.)
122
123 4. Compiler bugs (now hopefully history):
124
125 * Solaris 2's CC (SC3.0) doesn't implement t->~T() correctly, so the
126 destructors of classes derived from gc_cleanup won't be invoked.
127 You'll have to explicitly register a clean-up function with
128 new-placement syntax.
129
130 * Evidently cfront 3.0 does not allow destructors to be explicitly
131 invoked using the ANSI-conforming syntax t->~T(). If you're using
132 cfront 3.0, you'll have to comment out the class gc_cleanup, which
133 uses explicit invocation.
134
135 5. GC name conflicts:
136
137 Many other systems seem to use the identifier "GC" as an abbreviation
138 for "Graphics Context". Thus, GC placement has been replaced
139 by UseGC. GC is an alias for UseGC, unless GC_NAME_CONFLICT is defined.
140
141 ****************************************************************************/
142
143 #include "gc.h"
144
145 #ifdef GC_INCLUDE_NEW
146 # include <new> // for std, bad_alloc
147 #endif
148
149 #ifdef GC_NAMESPACE
150 # define GC_NS_QUALIFY(T) boehmgc::T
151 #else
152 # define GC_NS_QUALIFY(T) T
153 #endif
154
155 #ifndef THINK_CPLUS
156 # define GC_cdecl GC_CALLBACK
157 #else
158 # define GC_cdecl _cdecl
159 #endif
160
161 #if !defined(GC_NO_OPERATOR_NEW_ARRAY) \
162 && !defined(_ENABLE_ARRAYNEW) /* Digimars */ \
163 && (defined(__BORLANDC__) && (__BORLANDC__ < 0x450) \
164 || (defined(__GNUC__) && !GC_GNUC_PREREQ(2, 6)) \
165 || (defined(_MSC_VER) && _MSC_VER <= 1020) \
166 || (defined(__WATCOMC__) && __WATCOMC__ < 1050))
167 # define GC_NO_OPERATOR_NEW_ARRAY
168 #endif
169
170 #if !defined(GC_NO_OPERATOR_NEW_ARRAY) && !defined(GC_OPERATOR_NEW_ARRAY)
171 # define GC_OPERATOR_NEW_ARRAY
172 #endif
173
174 #if (!defined(__BORLANDC__) || __BORLANDC__ > 0x0620) \
175 && ! defined (__sgi) && ! defined(__WATCOMC__) \
176 && (!defined(_MSC_VER) || _MSC_VER > 1020)
177 # define GC_PLACEMENT_DELETE
178 #endif
179
180 #if !defined(GC_NEW_DELETE_THROW_NOT_NEEDED) \
181 && !defined(GC_NEW_DELETE_NEED_THROW) && GC_GNUC_PREREQ(4, 2) \
182 && (__cplusplus < 201103L || defined(__clang__))
183 # define GC_NEW_DELETE_NEED_THROW
184 #endif
185
186 #ifndef GC_NEW_DELETE_NEED_THROW
187 # define GC_DECL_NEW_THROW /* empty */
188 #elif __cplusplus >= 201703L || _MSVC_LANG >= 201703L
189 // The "dynamic exception" syntax had been deprecated in C++11
190 // and was removed in C++17.
191 # define GC_DECL_NEW_THROW noexcept(false)
192 #elif defined(GC_INCLUDE_NEW)
193 # define GC_DECL_NEW_THROW throw(std::bad_alloc)
194 #else
195 # define GC_DECL_NEW_THROW /* empty (as bad_alloc might be undeclared) */
196 #endif
197
198 #if defined(GC_NEW_ABORTS_ON_OOM) || defined(_LIBCPP_NO_EXCEPTIONS)
199 # define GC_OP_NEW_OOM_CHECK(obj) \
200 do { if (!(obj)) GC_abort_on_oom(); } while (0)
201 #elif defined(GC_INCLUDE_NEW)
202 # define GC_OP_NEW_OOM_CHECK(obj) if (obj) {} else throw std::bad_alloc()
203 #else
204 // "new" header is not included, so bad_alloc cannot be thrown directly.
205 GC_API void GC_CALL GC_throw_bad_alloc();
206 # define GC_OP_NEW_OOM_CHECK(obj) if (obj) {} else GC_throw_bad_alloc()
207 #endif // !GC_NEW_ABORTS_ON_OOM && !GC_INCLUDE_NEW
208
209 #ifdef GC_NAMESPACE
210 namespace boehmgc
211 {
212 #endif
213
214 enum GCPlacement
215 {
216 UseGC,
217 # ifndef GC_NAME_CONFLICT
218 GC = UseGC,
219 # endif
220 NoGC,
221 PointerFreeGC
222 # ifdef GC_ATOMIC_UNCOLLECTABLE
223 , PointerFreeNoGC
224 # endif
225 };
226
227 /**
228 * Instances of classes derived from "gc" will be allocated in the collected
229 * heap by default, unless an explicit NoGC placement is specified.
230 */
231 class gc
232 {
233 public:
234 inline void* operator new(size_t size);
235 inline void* operator new(size_t size, GCPlacement gcp);
236 inline void* operator new(size_t size, void* p) GC_NOEXCEPT;
237 // Must be redefined here, since the other overloadings hide
238 // the global definition.
239 inline void operator delete(void* obj) GC_NOEXCEPT;
240
241 # ifdef GC_PLACEMENT_DELETE
242 inline void operator delete(void*, GCPlacement) GC_NOEXCEPT;
243 // Called if construction fails.
244 inline void operator delete(void*, void*) GC_NOEXCEPT;
245 # endif // GC_PLACEMENT_DELETE
246
247 # ifdef GC_OPERATOR_NEW_ARRAY
248 inline void* operator new[](size_t size);
249 inline void* operator new[](size_t size, GCPlacement gcp);
250 inline void* operator new[](size_t size, void* p) GC_NOEXCEPT;
251 inline void operator delete[](void* obj) GC_NOEXCEPT;
252 # ifdef GC_PLACEMENT_DELETE
253 inline void operator delete[](void*, GCPlacement) GC_NOEXCEPT;
254 inline void operator delete[](void*, void*) GC_NOEXCEPT;
255 # endif
256 # endif // GC_OPERATOR_NEW_ARRAY
257 };
258
259 /**
260 * Instances of classes derived from "gc_cleanup" will be allocated
261 * in the collected heap by default. When the collector discovers
262 * an inaccessible object derived from "gc_cleanup" or containing
263 * a member derived from "gc_cleanup", its destructors will be invoked.
264 */
265 class gc_cleanup: virtual public gc
266 {
267 public:
268 inline gc_cleanup();
269 inline virtual ~gc_cleanup();
270
271 private:
272 inline static void GC_cdecl cleanup(void* obj, void* clientData);
273 };
274
275 extern "C" {
276 typedef void (GC_CALLBACK * GCCleanUpFunc)(void* obj, void* clientData);
277 }
278
279 #ifdef GC_NAMESPACE
280 }
281 #endif
282
283 #ifdef _MSC_VER
284 // Disable warning that "no matching operator delete found; memory will
285 // not be freed if initialization throws an exception"
286 # pragma warning(disable:4291)
287 // TODO: "non-member operator new or delete may not be declared inline"
288 // warning is disabled for now.
289 # pragma warning(disable:4595)
290 #endif
291
292 inline void* operator new(size_t size, GC_NS_QUALIFY(GCPlacement) gcp,
293 GC_NS_QUALIFY(GCCleanUpFunc) /* cleanup */ = 0,
294 void* /* clientData */ = 0);
295 // Allocates a collectible or uncollectible object, according to the
296 // value of "gcp".
297 //
298 // For collectible objects, if "cleanup" is non-null, then when the
299 // allocated object "obj" becomes inaccessible, the collector will
300 // invoke the function "cleanup(obj, clientData)" but will not
301 // invoke the object's destructors. It is an error to explicitly
302 // delete an object allocated with a non-null "cleanup".
303 //
304 // It is an error to specify a non-null "cleanup" with NoGC or for
305 // classes derived from "gc_cleanup" or containing members derived
306 // from "gc_cleanup".
307
308 #ifdef GC_PLACEMENT_DELETE
309 inline void operator delete(void*, GC_NS_QUALIFY(GCPlacement),
310 GC_NS_QUALIFY(GCCleanUpFunc),
311 void*) GC_NOEXCEPT;
312 #endif
313
314 #ifndef GC_NO_INLINE_STD_NEW
315
316 #if defined(_MSC_VER) || defined(__DMC__) \
317 || ((defined(__BORLANDC__) || defined(__CYGWIN__) \
318 || defined(__CYGWIN32__) || defined(__MINGW32__) \
319 || defined(__WATCOMC__)) \
320 && !defined(GC_BUILD) && !defined(GC_NOT_DLL))
321 // Inlining done to avoid mix up of new and delete operators by VC++ 9 (due
322 // to arbitrary ordering during linking).
323
324 # ifdef GC_OPERATOR_NEW_ARRAY
325 inline void* operator new[](size_t size) GC_DECL_NEW_THROW
326 {
327 void* obj = GC_MALLOC_UNCOLLECTABLE(size);
328 GC_OP_NEW_OOM_CHECK(obj);
329 return obj;
330 }
331
332 inline void operator delete[](void* obj) GC_NOEXCEPT
333 {
334 GC_FREE(obj);
335 }
336 # endif
337
338 inline void* operator new(size_t size) GC_DECL_NEW_THROW
339 {
340 void* obj = GC_MALLOC_UNCOLLECTABLE(size);
341 GC_OP_NEW_OOM_CHECK(obj);
342 return obj;
343 }
344
345 inline void operator delete(void* obj) GC_NOEXCEPT
346 {
347 GC_FREE(obj);
348 }
349
350 # if __cplusplus >= 201402L || _MSVC_LANG >= 201402L // C++14
351 inline void operator delete(void* obj, size_t size) GC_NOEXCEPT {
352 (void)size; // size is ignored
353 GC_FREE(obj);
354 }
355
356 # if defined(GC_OPERATOR_NEW_ARRAY)
357 inline void operator delete[](void* obj, size_t size) GC_NOEXCEPT {
358 (void)size;
359 GC_FREE(obj);
360 }
361 # endif
362 # endif // C++14
363 #endif
364
365 #ifdef _MSC_VER
366
367 // This new operator is used by VC++ in case of Debug builds:
368 # ifdef GC_DEBUG
369 inline void* operator new(size_t size, int /* nBlockUse */,
370 const char* szFileName, int nLine)
371 {
372 void* obj = GC_debug_malloc_uncollectable(size, szFileName, nLine);
373 GC_OP_NEW_OOM_CHECK(obj);
374 return obj;
375 }
376 # else
377 inline void* operator new(size_t size, int /* nBlockUse */,
378 const char* /* szFileName */, int /* nLine */)
379 {
380 void* obj = GC_malloc_uncollectable(size);
381 GC_OP_NEW_OOM_CHECK(obj);
382 return obj;
383 }
384 # endif /* !GC_DEBUG */
385
386 # ifdef GC_OPERATOR_NEW_ARRAY
387 // This new operator is used by VC++ 7+ in Debug builds:
388 inline void* operator new[](size_t size, int nBlockUse,
389 const char* szFileName, int nLine)
390 {
391 return operator new(size, nBlockUse, szFileName, nLine);
392 }
393 # endif
394
395 #endif // _MSC_VER
396
397 #elif defined(_MSC_VER)
398 // The following ensures that the system default operator new[] does not
399 // get undefined, which is what seems to happen on VC++ 6 for some reason
400 // if we define a multi-argument operator new[].
401 // There seems to be no way to redirect new in this environment without
402 // including this everywhere.
403 # ifdef GC_OPERATOR_NEW_ARRAY
404 void *operator new[](size_t size) GC_DECL_NEW_THROW;
405 void operator delete[](void* obj) GC_NOEXCEPT;
406
407 void* operator new[](size_t size, int /* nBlockUse */,
408 const char * szFileName, int nLine);
409 # endif // GC_OPERATOR_NEW_ARRAY
410
411 void* operator new(size_t size) GC_DECL_NEW_THROW;
412 void operator delete(void* obj) GC_NOEXCEPT;
413
414 void* operator new(size_t size, int /* nBlockUse */,
415 const char * szFileName, int nLine);
416 #endif // GC_NO_INLINE_STD_NEW && _MSC_VER
417
418 #ifdef GC_OPERATOR_NEW_ARRAY
419 // The operator new for arrays, identical to the above.
420 inline void* operator new[](size_t size, GC_NS_QUALIFY(GCPlacement) gcp,
421 GC_NS_QUALIFY(GCCleanUpFunc) /* cleanup */ = 0,
422 void* /* clientData */ = 0);
423 #endif // GC_OPERATOR_NEW_ARRAY
424
425 /* Inline implementation */
426
427 #ifdef GC_NAMESPACE
428 namespace boehmgc
429 {
430 #endif
431
432 inline void* gc::operator new(size_t size)
433 {
434 void* obj = GC_MALLOC(size);
435 GC_OP_NEW_OOM_CHECK(obj);
436 return obj;
437 }
438
439 inline void* gc::operator new(size_t size, GCPlacement gcp)
440 {
441 void* obj;
442 switch (gcp) {
443 case UseGC:
444 obj = GC_MALLOC(size);
445 break;
446 case PointerFreeGC:
447 obj = GC_MALLOC_ATOMIC(size);
448 break;
449 # ifdef GC_ATOMIC_UNCOLLECTABLE
450 case PointerFreeNoGC:
451 obj = GC_MALLOC_ATOMIC_UNCOLLECTABLE(size);
452 break;
453 # endif
454 case NoGC:
455 default:
456 obj = GC_MALLOC_UNCOLLECTABLE(size);
457 }
458 GC_OP_NEW_OOM_CHECK(obj);
459 return obj;
460 }
461
462 inline void* gc::operator new(size_t /* size */, void* p) GC_NOEXCEPT
463 {
464 return p;
465 }
466
467 inline void gc::operator delete(void* obj) GC_NOEXCEPT
468 {
469 GC_FREE(obj);
470 }
471
472 #ifdef GC_PLACEMENT_DELETE
473 inline void gc::operator delete(void*, void*) GC_NOEXCEPT {}
474
475 inline void gc::operator delete(void* p, GCPlacement /* gcp */) GC_NOEXCEPT
476 {
477 GC_FREE(p);
478 }
479 #endif // GC_PLACEMENT_DELETE
480
481 #ifdef GC_OPERATOR_NEW_ARRAY
482 inline void* gc::operator new[](size_t size)
483 {
484 return gc::operator new(size);
485 }
486
487 inline void* gc::operator new[](size_t size, GCPlacement gcp)
488 {
489 return gc::operator new(size, gcp);
490 }
491
492 inline void* gc::operator new[](size_t /* size */, void* p) GC_NOEXCEPT
493 {
494 return p;
495 }
496
497 inline void gc::operator delete[](void* obj) GC_NOEXCEPT
498 {
499 gc::operator delete(obj);
500 }
501
502 # ifdef GC_PLACEMENT_DELETE
503 inline void gc::operator delete[](void*, void*) GC_NOEXCEPT {}
504
505 inline void gc::operator delete[](void* p,
506 GCPlacement /* gcp */) GC_NOEXCEPT
507 {
508 gc::operator delete(p);
509 }
510 # endif
511 #endif // GC_OPERATOR_NEW_ARRAY
512
513 inline gc_cleanup::~gc_cleanup()
514 {
515 # ifndef GC_NO_FINALIZATION
516 void* base = GC_base(this);
517 if (0 == base) return; // Non-heap object.
518 GC_register_finalizer_ignore_self(base, 0, 0, 0, 0);
519 # endif
520 }
521
522 inline void GC_CALLBACK gc_cleanup::cleanup(void* obj, void* displ)
523 {
524 ((gc_cleanup*) ((char*) obj + (ptrdiff_t) displ))->~gc_cleanup();
525 }
526
527 inline gc_cleanup::gc_cleanup()
528 {
529 # ifndef GC_NO_FINALIZATION
530 GC_finalization_proc oldProc = 0;
531 void* oldData = NULL; // to avoid "might be uninitialized" compiler warning
532 void* this_ptr = (void*)this;
533 void* base = GC_base(this_ptr);
534 if (base != 0) {
535 // Don't call the debug version, since this is a real base address.
536 GC_register_finalizer_ignore_self(base, (GC_finalization_proc) cleanup,
537 (void*)((char*)this_ptr-(char*)base),
538 &oldProc, &oldData);
539 if (oldProc != 0) {
540 GC_register_finalizer_ignore_self(base, oldProc, oldData, 0, 0);
541 }
542 }
543 # elif defined(CPPCHECK)
544 (void)cleanup;
545 # endif
546 }
547
548 #ifdef GC_NAMESPACE
549 }
550 #endif
551
552 inline void* operator new(size_t size, GC_NS_QUALIFY(GCPlacement) gcp,
553 GC_NS_QUALIFY(GCCleanUpFunc) cleanup,
554 void* clientData)
555 {
556 void* obj;
557 switch (gcp) {
558 case GC_NS_QUALIFY(UseGC):
559 obj = GC_MALLOC(size);
560 # ifndef GC_NO_FINALIZATION
561 if (cleanup != 0 && obj != 0) {
562 GC_REGISTER_FINALIZER_IGNORE_SELF(obj, cleanup, clientData, 0, 0);
563 }
564 # else
565 (void)cleanup;
566 (void)clientData;
567 # endif
568 break;
569 case GC_NS_QUALIFY(PointerFreeGC):
570 obj = GC_MALLOC_ATOMIC(size);
571 break;
572 # ifdef GC_ATOMIC_UNCOLLECTABLE
573 case GC_NS_QUALIFY(PointerFreeNoGC):
574 obj = GC_MALLOC_ATOMIC_UNCOLLECTABLE(size);
575 break;
576 # endif
577 case GC_NS_QUALIFY(NoGC):
578 default:
579 obj = GC_MALLOC_UNCOLLECTABLE(size);
580 }
581 GC_OP_NEW_OOM_CHECK(obj);
582 return obj;
583 }
584
585 #ifdef GC_PLACEMENT_DELETE
586 inline void operator delete(void* p, GC_NS_QUALIFY(GCPlacement) /* gcp */,
587 GC_NS_QUALIFY(GCCleanUpFunc) /* cleanup */,
588 void* /* clientData */) GC_NOEXCEPT
589 {
590 GC_FREE(p);
591 }
592 #endif // GC_PLACEMENT_DELETE
593
594 #ifdef GC_OPERATOR_NEW_ARRAY
595 inline void* operator new[](size_t size, GC_NS_QUALIFY(GCPlacement) gcp,
596 GC_NS_QUALIFY(GCCleanUpFunc) cleanup,
597 void* clientData)
598 {
599 return ::operator new(size, gcp, cleanup, clientData);
600 }
601 #endif // GC_OPERATOR_NEW_ARRAY
602
603 #endif /* GC_CPP_H */