[Guile-commits] 01/02: Document JIT environment variables

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit c23fe0ec5ab0d3d98f42d99d7b5c26159c97c8ac
Author: Andy Wingo <address@hidden>
Date:   Wed Dec 11 21:55:49 2019 +0100

    Document JIT environment variables
    
    * 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.
---
 doc/ref/guile-invoke.texi | 37 +++++++++++++++++++++++++------------
 doc/ref/vm.texi           | 16 ++++++++++------
 2 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/doc/ref/guile-invoke.texi b/doc/ref/guile-invoke.texi
index 90f1f49..42bbd35 100644
--- a/doc/ref/guile-invoke.texi
+++ b/doc/ref/guile-invoke.texi
@@ -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
 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
 @vindex GUILE_LOAD_COMPILED_PATH
 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
 @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
 
 @c Local Variables: 
diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi
index e603204..d5a2c96 100644
--- a/doc/ref/vm.texi
+++ b/doc/ref/vm.texi
@@ -87,11 +87,11 @@ optimized inline instructions for Guile as well (GC-managed 
allocations,
 type checks, etc.).
 
 Guile also includes a just-in-time (JIT) compiler to translate bytecode
-to native code.  Because Guile uses the portable GNU Lightning library
-to emit that code, we keep the benefits of portability while also
-benefitting from fast native code.  To avoid too much time spent in the
-JIT compiler itself, Guile is tuned to only emit machine code for
-bytecode that is called often.
+to native code.  Because Guile embeds a portable code generation library
+(@url{https://gitlab.com/wingo/lightening}), we keep the benefits of
+portability while also benefitting from fast native code.  To avoid too
+much time spent in the JIT compiler itself, Guile is tuned to only emit
+machine code for bytecode that is called often.
 
 The rest of this section describes that VM that Guile implements, and
 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
 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
 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
@@ -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
 can allow Guile to experiment with speculative optimizations in Scheme
 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.