You will need to identify roots (i.e. references to heap objects your collector
needs to know about) in your generated IR, so that LLVM can encode them into
your final stack maps. Depending on the collector strategy chosen, this is
-accomplished by using either the ''@llvm.gcroot'' intrinsics or an
-''gc.statepoint'' relocation sequence.
+accomplished by using either the ``@llvm.gcroot`` intrinsics or an
+``gc.statepoint`` relocation sequence.
Don't forget to create a root for each intermediate value that is generated when
evaluating an expression. In ``h(f(), g())``, the result of ``f()`` could
The ``llvm.gcroot`` intrinsic is used to inform LLVM that a stack variable
references an object on the heap and is to be tracked for garbage collection.
-The exact impact on generated code is specified by a :ref:`compiler plugin
-<plugin>`. All calls to ``llvm.gcroot`` **must** reside inside the first basic
-block.
+The exact impact on generated code is specified by the Function's selected
+:ref:`GC strategy <plugin>`. All calls to ``llvm.gcroot`` **must** reside
+inside the first basic block.
The first argument **must** be a value referring to an alloca instruction or a
bitcast of an alloca. The second contains a pointer to metadata that should be
.. _plugin:
-Built In Collectors
-====================
+.. _builtin-gc-strategies:
+
+Built In GC Strategies
+======================
LLVM includes built in support for several varieties of garbage collectors.
The 'Erlang' and 'Ocaml' GCs
-----------------------------
-LLVM ships with two example collectors which leverage the ''gcroot''
+LLVM ships with two example collectors which leverage the ``gcroot``
mechanisms. To our knowledge, these are not actually used by any language
runtime, but they do provide a reasonable starting point for someone interested
-in writing an ''gcroot' compatible GC plugin. In particular, these are the
+in writing an ``gcroot`` compatible GC plugin. In particular, these are the
only in tree examples of how to produce a custom binary stack map format using
-a ''gcroot'' strategy.
+a ``gcroot`` strategy.
As there names imply, the binary format produced is intended to model that
used by the Erlang and OCaml compilers respectively.
F.setGC("statepoint-example");
This GC provides an example of how one might use the infrastructure provided
-by ''gc.statepoint''.
+by ``gc.statepoint``. This example GC is compatible with the
+:ref:`PlaceSafepoints` and :ref:`RewriteStatepointsForGC` utility passes
+which simplify ``gc.statepoint`` sequence insertion. If you need to build a
+custom GC strategy around the ``gc.statepoints`` mechanisms, it is recommended
+that you use this one as a starting point.
+
+This GC strategy does not support read or write barriers. As a result, these
+intrinsics are lowered to normal loads and stores.
+
+The stack map format generated by this GC strategy can be found in the
+:ref:`stackmap-section` using a format documented :ref:`here
+<statepoint-stackmap-format>`. This format is intended to be the standard
+format supported by LLVM going forward.
Custom GC Strategies