Debian Codegraph @

external/bdwgc/doc/simple_example.md

raw
1 # Using the Garbage Collector: A simple example
2
3 The following consists of step-by-step instructions for building and using the
4 collector. We'll assume a Linux/gcc platform and a single-threaded
5 application. The green text contains information about other platforms
6 or scenarios. It can be skipped, especially on first reading.
7
8 ## Building the collector
9
10 If you have not so yet, unpack the collector and enter the newly created
11 directory with:
12
13
14 tar xvfz gc-<version>.tar.gz
15 cd gc-<version>
16
17
18 You can configure, build, and install the collector in a private directory,
19 say /home/xyz/gc, with the following commands:
20
21
22 ./configure --prefix=/home/xyz/gc --disable-threads
23 make
24 make check
25 make install
26
27
28 Here the `make check` command is optional, but highly recommended. It runs
29 a basic correctness test which usually takes well under a minute.
30
31 ### Other platforms
32
33 On non-Unix, non-Linux platforms, the collector is usually built by copying
34 the appropriate makefile (see the platform-specific README in doc/README.xxx
35 in the distribution) to the file "Makefile", and then typing `make` (or
36 `nmake` or ...). This builds the library in the source tree. You may want
37 to move it and the files in the include directory to a more convenient place.
38
39 If you use a makefile that does not require running a configure script, you
40 should first look at the makefile, and adjust any options that are documented
41 there.
42
43 If your platform provides a `make` utility, that is generally preferred
44 to platform- and compiler- dependent "project" files. (At least that is the
45 strong preference of the would-be maintainer of those project files.)
46
47 ### Threads
48
49 If you do not need thread support, configure the collector with:
50
51
52 --disable-threads
53
54
55 Alternatively, if your target is a real old-fashioned uniprocessor (no
56 "hyperthreading", etc.), you may just want to turn off parallel marking with
57 `--disable-parallel-mark`.
58
59 ### C++
60
61 You will need to include the C++ support, which unfortunately tends to be
62 among the least portable parts of the collector, since it seems to rely
63 on some corner cases of the language. On Linux, it suffices to add
64 `--enable-cplusplus` to the configure options.
65
66 ## Writing the program
67
68 You will need to include "gc.h" at the beginning of every file that allocates
69 memory through the garbage collector. Call `GC_MALLOC` wherever you would have
70 call `malloc`. This initializes memory to zero like `calloc`; there is no need
71 to explicitly clear the result.
72
73 If you know that an object will not contain pointers to the garbage-collected
74 heap, and you don't need it to be initialized, call `GC_MALLOC_ATOMIC`
75 instead.
76
77 A function `GC_FREE` is provided but need not be called. For very small
78 objects, your program will probably perform better if you do not call it, and
79 let the collector do its job.
80
81 A `GC_REALLOC` function behaves like the C library `realloc`. It allocates
82 uninitialized pointer-free memory if the original object was allocated that
83 way.
84
85 The following program `loop.c` is a trivial example:
86
87
88 #include "gc.h"
89 #include <assert.h>
90 #include <stdio.h>
91
92 int main(void) {
93 int i;
94
95 GC_INIT();
96 for (i = 0; i < 10000000; ++i) {
97 int **p = (int **) GC_MALLOC(sizeof(int *));
98 int *q = (int *) GC_MALLOC_ATOMIC(sizeof(int));
99 assert(*p == 0);
100 *p = (int *) GC_REALLOC(q, 2 * sizeof(int));
101 if (i % 100000 == 0)
102 printf("Heap size = %d\n", GC_get_heap_size());
103 }
104 return 0;
105 }
106
107
108 ### Interaction with the system malloc
109
110 It is usually best not to mix garbage-collected allocation with the system
111 `malloc`-`free`. If you do, you need to be careful not to store pointers
112 to the garbage-collected heap in memory allocated with the system `malloc`.
113
114 ### Other Platforms
115
116 On some other platforms it is necessary to call `GC_INIT` from the main
117 program, which is presumed to be part of the main executable, not a dynamic
118 library. This can never hurt, and is thus generally good practice.
119
120 ### Threads
121
122 For a multi-threaded program, some more rules apply:
123
124 * Files that either allocate through the GC _or make thread-related calls_
125 should first define the macro `GC_THREADS`, and then include `gc.h`. On some
126 platforms this will redefine some threads primitives, e.g. to let the
127 collector keep track of thread creation.
128
129 ### C++
130
131 In the case of C++, you need to be especially careful not to store pointers
132 to the garbage-collected heap in areas that are not traced by the collector.
133 The collector includes some _alternate interfaces_ to make that easier.
134
135 ### Debugging
136
137 Additional debug checks can be performed by defining `GC_DEBUG` before
138 including `gc.h`. Additional options are available if the collector is also
139 built with `--enable-gc-debug` (`--enable-full-debug` in some older versions)
140 and all allocations are performed with `GC_DEBUG` defined.
141
142 ### What if I can't rewrite/recompile my program?
143
144 You may be able to build the collector with `--enable-redirect-malloc` and set
145 the `LD_PRELOAD` environment variable to point to the resulting library, thus
146 replacing the standard `malloc` with its garbage-collected counterpart. This
147 is rather platform dependent. See the _GC leak detection documentation_ for
148 some more details.
149
150 ## Compiling and linking
151
152 The above application `loop.c` test program can be compiled and linked with:
153
154
155 cc -I/home/xyz/gc/include loop.c /home/xyz/gc/lib/libgc.a -o loop
156
157
158 The `-I` option directs the compiler to the right include directory. In this
159 case, we list the static library directly on the compile line; the dynamic
160 library could have been used instead, provided we arranged for the dynamic
161 loader to find it, e.g. by setting `LD_LIBRARY_PATH`.
162
163 ### Threads
164
165 On pthread platforms, you will of course also have to link with `-lpthread`,
166 and compile with any thread-safety options required by your compiler. On some
167 platforms, you may also need to link with `-ldl` or `-lrt`. Looking
168 at `tools/threadlibs.c` should give you the appropriate list if a plain
169 `-lpthread` does not work.
170
171 ## Running the executable
172
173 The executable can of course be run normally, e.g. by typing:
174
175
176 ./loop
177
178
179 The operation of the collector is affected by a number of environment
180 variables. For example, setting `GC_PRINT_STATS` produces some GC statistics
181 on stdout. See `README.environment` in the distribution for details.