BDWGC(3)

🎀 BDWGC(3) — the garbage-collecting malloc replacement, explained by your favorite unix girlie 🎀

okay so bestie, this is the BDWGC manual page — section 3 of the Library Functions Manual, iykyk. it's the whole "malloc but make it ✨self-cleaning✨" situation, and honestly? it's giving main character energy. let's get into it 💅

---

✨ NAME ✨

GC_malloc, GC_malloc_atomic, GC_free, GC_realloc, GC_enable_incremental, GC_register_finalizer, GC_malloc_ignore_off_page, GC_malloc_atomic_ignore_off_page, GC_set_warn_proc — a garbage collecting malloc replacement 🗑️💖

---

🌸 SYNOPSIS 🌸

#include <gc/gc.h>
void * GC_malloc(size_t size);
void * GC_malloc_atomic(size_t size);
void GC_free(void *ptr);
void * GC_realloc(void *ptr, size_t size);
void GC_enable_incremental(void);
void * GC_malloc_ignore_off_page(size_t size);
void * GC_malloc_atomic_ignore_off_page(size_t size);
void GC_set_warn_proc(void (*proc)(char *, GC_word));

and then you link it like this, no cap:

cc ... -lgc

---

💜 DESCRIPTION 💜

so GC_malloc and GC_free are literally plug-in replacements for the standard malloc and free. like, drop-in. swopped in. but here's the iconic part — GC_malloc will attempt to reclaim inaccessible space automatically by invoking a conservative garbage collector at appropriate points 🔥. the collector traverses all data structures accessible by following pointers from the machine's registers, stack(s), data, and bss segments. inaccessible structures get reclaimed. and a machine word counts as a valid pointer if it's an address inside an object allocated by GC_malloc or its friends 🫶

in most cases it's preferable to call the macros GC_MALLOC, GC_FREE, etc. instead of calling GC_malloc and friends directly — because that way debugging versions of the routines can be substituted in by defining GC_DEBUG before including gc.h. free upgrade, honestly 💅

check the documentation in the include files gc_cpp.h and gc_allocator.h, plus the gcinterface.md file in the distribution, for an alternate, C++ specific interface to the garbage collector 👑. and note that C++ programs generally need to be careful to ensure that all allocated memory (whether via new, malloc, or STL allocators) that may point to garbage collected memory is either itself garbage collected, or at least traced by the collector. that part matters, bestie, don't skip it 🙈

unlike the standard implementations of malloc, GC_malloc clears the newly allocated storage. GC_malloc_atomic does not. and on top of that, it informs the collector that the resulting object will never contain any pointers, so it should therefore not be scanned by the collector. no pointers, no scanning, we love an efficient queen ✨

GC_free can be used to deallocate objects, but its use is optional and generally discouraged. GC_realloc has the standard realloc semantics — and it preserves pointer-free-ness 🦋. GC_register_finalizer lets you register functions that get invoked when an object becomes inaccessible. it's giving "call me when I'm gone" energy 😭

the garbage collector tries to avoid allocating memory at locations that already appear to be referenced before allocation. (such apparent "pointers" are usually large integers and the like that just happen to look like an address.) this may make it hard to allocate very large objects, and an attempt to do so may generate a warning ⚠️

GC_malloc_ignore_off_page and GC_malloc_atomic_ignore_off_page inform the collector that the client code will always maintain a pointer to near the beginning (i.e. within the first heap block) of the object, and that pointers beyond that can be ignored by the collector 🌈. this makes it much easier for the collector to place large objects. these are recommended for large object allocation — objects expected to be > ~100 KB should be allocated this way, fr fr 📏

it's also possible to use the collector to find storage leaks in programs destined to be run with standard malloc/free 👀. the collector can be compiled for thread-safe operation. and unlike standard malloc, it is safe to call malloc after a previous malloc call was interrupted by a signal — provided the original malloc call is not resumed 💀

the collector may, on rare occasion, produce warning messages. on UNIX machines these appear on stderr. warning messages can be filtered, redirected, or ignored with GC_set_warn_proc — and this is recommended for production code 🫶. see gc.h for details.

fully portable code should call GC_INIT from the primordial thread of the main program before making any other GC calls 🌱. on most platforms this does nothing and the collector is initialized on first use. on a few platforms explicit initialization is necessary. and it can never hurt. lowkey the safest little function ever 💖

debugging versions of many of the above routines are provided as macros ✨ — their names are identical to the above, but consist of all capital letters. if GC_DEBUG is defined before gc.h is included, these routines do additional checking, and allow the leak detecting version of the collector to produce slightly more useful output. without GC_DEBUG defined, they behave exactly like the lower-case versions. same energy, different outfit 💅

on some machines, collection will be performed incrementally after a call to GC_enable_incremental 🌸. this may temporarily write protect pages in the heap. see the README file for more information on how this interacts with system calls that write to the heap. (yes, that's a real caveat, don't come for me 🙈)

other facilities not discussed here include limited facilities to support incremental collection on machines without appropriate VM support, provisions for providing more explicit object layout information to the garbage collector, more direct support for "weak" pointers, support for "abortable" garbage collections during idle time, etc. the lore is deep, bestie 🧚

---

🦋 SEE ALSO 🦋

• the README and gc.h files in the distribution — more detailed definitions of the functions exported by the collector are given there. (the above list is not complete, i know, i know 😭)
• the web site at http://www.hboehm.info/gc/ (or https://github.com/ivmai/bdwgc/) 🌐
• Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Environment", "Software Practice & Experience", September 1988, pp. 807-820 📚
• the malloc(3) man page 👑

---

⭐ AUTHOR ⭐

Hans-J. Boehm (boehm@acm.org). some of the code was written by others (see the AUTHORS file for the details), most notably by Alan Demers, and, recently, Ivan Maidanski 🫶👑

---

okay that's the whole page!! and for the cute sign-off: this iconic lil document is dated 23 Aug 2023 and lives at BDWGC(3) — go forth and let the collector handle it, bestie, you deserve a break 💖✨🎀