mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-02 13:00:26 +02:00
Code Activity

Document JIT environment variables

Browse source 
* doc/ref/guile-invoke.texi (Environment Variables): Remove
  GUILE_STACK_SIZE which is no longer needed, and document some JIT
  debugging environment variables.
* doc/ref/vm.texi (Why a VM?, Just-In-Time Native Code): Update and link
  to environment variables documentation.
This commit is contained in:
Andy Wingo 2019-12-11 21:55:49 +01:00
parent bcb4f7dca8
commit c23fe0ec5a
2 changed files with 35 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

37
doc/ref/guile-invoke.texi
View file

@ -355,18 +355,6 @@ Usually, installing the current locale is the right thing to do. It
allows Guile to correctly parse and print strings with non-ASCII allows Guile to correctly parse and print strings with non-ASCII
characters. Therefore, this option is on by default. characters. Therefore, this option is on by default.
@item GUILE_STACK_SIZE
@vindex GUILE_STACK_SIZE
Guile currently has a limited stack size for Scheme computations.
Attempting to call too many nested functions will signal an error. This
is good to detect infinite recursion, but sometimes the limit is reached
for normal computations. This environment variable, if set to a
positive integer, specifies the number of Scheme value slots to allocate
for the stack.
In the future we will implement stacks that can grow and shrink, but for
now this hack will have to do.
@item GUILE_LOAD_COMPILED_PATH @item GUILE_LOAD_COMPILED_PATH
@vindex GUILE_LOAD_COMPILED_PATH @vindex GUILE_LOAD_COMPILED_PATH
This variable may be used to augment the path that is searched for This variable may be used to augment the path that is searched for
@ -428,6 +416,31 @@ Guile uses the environment variable @env{HOME}, the name of your home
directory, to locate various files, such as @file{.guile} or directory, to locate various files, such as @file{.guile} or
@file{.guile_history}. @file{.guile_history}.
@item GUILE_JIT_THRESHOLD
@vindex GUILE_JIT_THRESHOLD
Guile has a just-in-time (JIT) code generator that makes running Guile
code fast. @xref{Just-In-Time Native Code}, for more. The unit of code
generation is the function. Each function has its own counter that gets
incremented when the function is called and at each loop iteration in
the function. When the counter exceeds the @env{GUILE_JIT_THRESHOLD},
the function will get JIT-compiled. Set @env{GUILE_JIT_THRESHOLD} to
@code{-1} to disable JIT compilation, or @code{0} to eagerly JIT-compile
each function as it's first seen.
@item GUILE_JIT_LOG
@vindex GUILE_JIT_LOG
Set to @code{1}, @code{2}, or @code{3} to give increasing amounts of
logging for JIT compilation events. Used for debugging.
@item GUILE_JIT_STOP_AFTER
@vindex GUILE_JIT_STOP_AFTER
Though we have tested the JIT compiler as well as we can, it's possible
that it has bugs. If you suspect that Guile's JIT compiler is causing
your program to fail, set @env{GUILE_JIT_STOP_AFTER} to a positive
integer indicating the maximum number of functions to JIT-compile. By
bisecting over the value of @env{GUILE_JIT_STOP_AFTER}, you can pinpoint
the precise function that is being miscompiled.
@end table @end table
@c Local Variables: @c Local Variables:

16
doc/ref/vm.texi
View file

@ -87,11 +87,11 @@ optimized inline instructions for Guile as well (GC-managed allocations,
type checks, etc.). type checks, etc.).
Guile also includes a just-in-time (JIT) compiler to translate bytecode Guile also includes a just-in-time (JIT) compiler to translate bytecode
to native code. Because Guile uses the portable GNU Lightning library to native code. Because Guile embeds a portable code generation library
to emit that code, we keep the benefits of portability while also (@url{https://gitlab.com/wingo/lightening}), we keep the benefits of
benefitting from fast native code. To avoid too much time spent in the portability while also benefitting from fast native code. To avoid too
JIT compiler itself, Guile is tuned to only emit machine code for much time spent in the JIT compiler itself, Guile is tuned to only emit
bytecode that is called often. machine code for bytecode that is called often.
The rest of this section describes that VM that Guile implements, and The rest of this section describes that VM that Guile implements, and
the compiled procedures that run on it. the compiled procedures that run on it.
@ -1915,7 +1915,7 @@ breakpoint, Guile will disable the JIT for the thread being debugged,
falling back to the interpreter (which has the corresponding code to run falling back to the interpreter (which has the corresponding code to run
the hooks). @xref{VM Hooks}. the hooks). @xref{VM Hooks}.
To emit native code, Guile uses a forked version of GNU Lightning.This To emit native code, Guile uses a forked version of GNU Lightning. This
"Lightening" effort, spun out as a separate project, aims to build on "Lightening" effort, spun out as a separate project, aims to build on
the back-end support from GNU Lightning, but adapting the API and the back-end support from GNU Lightning, but adapting the API and
behavior of the library to match Guile's needs. This code is included behavior of the library to match Guile's needs. This code is included
@ -1967,3 +1967,7 @@ written in Scheme, to take advantage of the opportunity to do global
register allocation and instruction selection. Once this is working, it register allocation and instruction selection. Once this is working, it
can allow Guile to experiment with speculative optimizations in Scheme can allow Guile to experiment with speculative optimizations in Scheme
as well. @xref{Extending the Compiler}, for more on future directions. as well. @xref{Extending the Compiler}, for more on future directions.
Finally, note that there are a few environment variables that can be
tweaked to make JIT compilation happen sooner, later, or never.
@xref{Environment Variables}, for more.