]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. index:: garbage collector, invocation, ggc_collect | |
7 | ||
8 | .. _invoking-the-garbage-collector: | |
9 | ||
10 | How to invoke the garbage collector | |
11 | *********************************** | |
12 | ||
13 | The GCC garbage collector GGC is only invoked explicitly. In contrast | |
14 | with many other garbage collectors, it is not implicitly invoked by | |
15 | allocation routines when a lot of memory has been consumed. So the | |
16 | only way to have GGC reclaim storage is to call the ``ggc_collect`` | |
17 | function explicitly. | |
18 | With :samp:`{mode}` ``GGC_COLLECT_FORCE`` or otherwise (default | |
19 | ``GGC_COLLECT_HEURISTIC``) when the internal heuristic decides to | |
20 | collect, this call is potentially an expensive operation, as it may | |
21 | have to scan the entire heap. Beware that local variables (on the GCC | |
22 | call stack) are not followed by such an invocation (as many other | |
23 | garbage collectors do): you should reference all your data from static | |
24 | or external ``GTY`` -ed variables, and it is advised to call | |
25 | ``ggc_collect`` with a shallow call stack. The GGC is an exact mark | |
26 | and sweep garbage collector (so it does not scan the call stack for | |
27 | pointers). In practice GCC passes don't often call ``ggc_collect`` | |
28 | themselves, because it is called by the pass manager between passes. | |
29 | ||
30 | At the time of the ``ggc_collect`` call all pointers in the GC-marked | |
31 | structures must be valid or ``NULL``. In practice this means that | |
32 | there should not be uninitialized pointer fields in the structures even | |
33 | if your code never reads or writes those fields at a particular | |
34 | instance. One way to ensure this is to use cleared versions of | |
35 | allocators unless all the fields are initialized manually immediately | |
3ed1b4ce | 36 | after allocation. |