summaryrefslogtreecommitdiff
path: root/doc/ref/api-init.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/api-init.texi')
-rw-r--r--doc/ref/api-init.texi128
1 files changed, 41 insertions, 87 deletions
diff --git a/doc/ref/api-init.texi b/doc/ref/api-init.texi
index 795b6d5f9..94407114b 100644
--- a/doc/ref/api-init.texi
+++ b/doc/ref/api-init.texi
@@ -8,96 +8,50 @@
@node Initialization
@section Initializing Guile
-Each thread that wants to use function from the Guile API needs to put
-itself into guile mode with either @code{scm_with_guile} or
-@code{scm_init_guile}. The global state of Guile is initialized
-automatically when the first thread enters guile mode.
-
-When a thread wants to block outside of a Guile API function, it should
-leave guile mode temporarily with either @code{scm_without_guile} or
-@code{scm_leave_guile}, @xref{Threads}.
-
-Threads that are created by @code{call-with-new-thread} or
-@code{scm_spawn_thread} start out in guile mode so you don't need to
-initialize them.
-
-@deftypefn {C Function} void *scm_with_guile (void *(*func)(void *), void *data)
-Call @var{func}, passing it @var{data} and return what @var{func}
-returns. While @var{func} is running, the current thread is in guile
-mode and can thus use the Guile API.
-
-When @code{scm_with_guile} is called from guile mode, the thread remains
-in guile mode when @code{scm_with_guile} returns.
-
-Otherwise, it puts the current thread into guile mode and, if needed,
-gives it a Scheme representation that is contained in the list returned
-by @code{all-threads}, for example. This Scheme representation is not
-removed when @code{scm_with_guile} returns so that a given thread is
-always represented by the same Scheme value during its lifetime, if at
-all.
-
-When this is the first thread that enters guile mode, the global state
-of Guile is initialized before calling @code{func}.
-
-When a throw happens while @var{func} runs (such as a signalled error)
-that is not caught, a short message is printed to the current error port
-and @code{scm_with_guile} returns @code{NULL}. When a continuation is
-invoked that would make the control flow cross this call to
-@code{scm_with_guile}, an error will be signalled at the point of
-continuation invokation. Thus, @code{scm_with_guile} guaranteed to
-return exactly once.
-
-When @code{scm_with_guile} returns, the thread is no longer in guile
-mode (except when @code{scm_with_guile} was called from guile mode, see
-above). Thus, only @code{func} can store @code{SCM} variables on the
-stack and be sure that they are protected from the garbage collector.
-See @code{scm_init_guile} for another approach at initializing Guile
-that does not have this restriction.
-
-It is OK to call @code{scm_with_guile} while a thread has temporarily
-left guile mode via @code{scm_without_guile} or @code{scm_leave_guile}.
-It will then simply temporarily enter guile mode again.
+@deftypefn {C Function} void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (void *@var{data}, int @var{argc}, char **@var{argv}), void *@var{data})
+Initialize the Guile Scheme interpreter. Then call @var{main_func},
+passing it @var{data}, @var{argc}, and @var{argv} as indicated. The
+function @var{main_func} should do all the work of the program
+(initializing other packages, defining application-specific functions,
+reading user input, and so on) before returning. When @var{main_func}
+returns, @code{scm_boot_guile} calls @code{exit (0)};
+@code{scm_boot_guile} never returns. If you want some other exit
+value, have @var{main_func} call @code{exit} itself.
+
+@code{scm_boot_guile} arranges for the Scheme @code{command-line}
+function to return the strings given by @var{argc} and @var{argv}. If
+@var{main_func} modifies @var{argc} or @var{argv}, it should call
+@code{scm_set_program_arguments} with the final list, so Scheme code
+will know which arguments have been processed.
+
+Why must the caller do all the real work from @var{main_func}? Guile's
+garbage collector scans the stack to find all local variables that
+reference Scheme objects. To do this, it needs to know the bounds of
+the stack that might contain such references. Because there is no
+portable way in C to find the base of the stack, @code{scm_boot_guile}
+assumes that all references are above its own stack frame. If you try
+to manipulate Scheme objects after this function returns, it's the luck
+of the draw whether Guile's storage manager will be able to find the
+objects you allocate. So, @code{scm_boot_guile} function exits, rather
+than returning, to discourage you from making that mistake.
+
+See @code{scm_init_guile}, below, for a function that can find the real
+base of the stack, but not in a portable way.
@end deftypefn
@deftypefn {C Function} void scm_init_guile ()
-Arrange things so as if all of the code of the current thread would be
-executed from within a call to @code{scm_with_guile}. That is, all
-functions called by the current thread can assume that @code{SCM} values
-on their stack frames are protected from the garbage collector (except
-when the thread has explicitely left guile mode, of course).
-
-When @code{scm_init_guile} is called from a thread that already has been
-in guile mode once, nothing happens. This behavior matters when you
-call @code{scm_init_guile} while the thread has only temporarily left
-guile mode: in that case the thread will not be in guile mode after
-@code{scm_init_guile} returns. Thus, you should not use
-@code{scm_init_guile} in such a scenario.
-
-When a uncaught throw happens in a thread that has been put into guile
-mode via @code{scm_init_guile}, a short message is printed to the
-current error port and the thread is exited via @code{scm_pthread_exit
-(NULL)}. No restrictions are placed on continuations.
-
-The function @code{scm_init_guile} might not be available on all
-platforms since it requires some stack-bounds-finding magic that might
-not have been to all platforms that Guile runs on. Thus, if you can, it
-is better to use @code{scm_with_guile} or its variation
-@code{scm_boot_guile} instead of this function.
-@end deftypefn
-
-@deftypefn {C Function} void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (void *@var{data}, int @var{argc}, char **@var{argv}), void *@var{data})
-Enter guile mode as with @code{scm_with_guile} and call @var{main_func},
-passing it @var{data}, @var{argc}, and @var{argv} as indicated. When
-@var{main_func} returns, @code{scm_boot_guile} calls @code{exit (0)};
-@code{scm_boot_guile} never returns. If you want some other exit value,
-have @var{main_func} call @code{exit} itself. If you don't want to exit
-at all, use @code{scm_with_guile} instead of @code{scm_boot_guile}.
-
-The function @code{scm_boot_guile} arranges for the Scheme
-@code{command-line} function to return the strings given by @var{argc}
-and @var{argv}. If @var{main_func} modifies @var{argc} or @var{argv},
-it should call @code{scm_set_program_arguments} with the final list, so
-Scheme code will know which arguments have been processed.
+Initialize the Guile Scheme interpreter.
+
+In contrast to @code{scm_boot_guile}, this function knows how to find
+the true base of the stack and thus does not need to usurp the control
+flow of your program. However, since finding the stack base can not be
+done portably, this function might not be available in all installations
+of Guile. If you can, you should use @code{scm_boot_guile} instead.
+
+Note that @code{scm_init_guile} does not inform Guile about the command
+line arguments that should be returned by the Scheme function
+@code{command-line}. You can use @code{scm_set_program_arguments} to do
+this.
@end deftypefn
@deftypefn {C Function} void scm_shell (int @var{argc}, char **@var{argv})