diff --git a/doc/ref/guile-invoke.texi b/doc/ref/guile-invoke.texi index 90f1f496b..42bbd35f3 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 e603204ca..d5a2c9683 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.