========================
translation.gcrootfinder
========================

* **name:** gcrootfinder

* **description:** Strategy for finding GC Roots (framework GCs only)

* **command-line:** --gcrootfinder

* **option type:** choice option

* **possible values:**

  + n/a

  + shadowstack

  + asmgcc

* **default:** shadowstack

* **requirements:**

  + value 'shadowstack' requires\:

    - `translation.gctransformer`_ to be set to 'framework'

  + value 'asmgcc' requires\:

    - `translation.gctransformer`_ to be set to 'framework'

    - `translation.backend`_ to be set to 'c'

.. _translation.backend: translation.backend.html
.. _translation.gctransformer: translation.gctransformer.html





Choose the method used to find the roots in the GC.  This only
applies to our framework GCs.  You have a choice of two
alternatives:

- ``--gcrootfinder=shadowstack``: use a so-called "shadow
  stack", which is an explicitly maintained custom stack of
  root pointers.  This is the most portable solution.

- ``--gcrootfinder=asmgcc``: use assembler hackery to find the
  roots directly from the normal stack.  This is a bit faster,
  but platform specific.  It works so far with GCC or MSVC,
  on i386 and x86-64.  It is tested only on Linux (where it is
  the default) so other platforms (as well as MSVC) may need
  various fixes before they can be used.

You may have to force the use of the shadowstack root finder if
you are running into troubles or if you insist on translating
PyPy with other compilers like clang.
