From beac60391264765f0edcb5d2c5cebe017b8969bb Mon Sep 17 00:00:00 2001 From: Marius Vollmer Date: Fri, 4 Mar 2005 16:05:01 +0000 Subject: [PATCH] Talk about new init functions. --- doc/ref/libguile-linking.texi | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/doc/ref/libguile-linking.texi b/doc/ref/libguile-linking.texi index 6fb667caa..f28de6f9d 100644 --- a/doc/ref/libguile-linking.texi +++ b/doc/ref/libguile-linking.texi @@ -35,19 +35,20 @@ use the obtained information in the Makefile. @node Guile Initialization Functions @subsection Guile Initialization Functions -To initialize Guile, you can use one of two functions. The first, -@code{scm_boot_guile}, is the most portable way to initialize Guile. It -should be used whenever you have control over the main function of your -program because it never returns. The second function, -@code{scm_init_guile}, does return and can thus be used in more -situations. However, @code{scm_init_guile} is not as widely available -as @code{scm_boot_guile} because it needs to rely on non-portable code -to find the stack bounds. When Guile does not know how to find these -bounds on your system, it will not provide @code{scm_init_guile}. - -When you can tolerate the limits of @code{scm_boot_guile}, you should -use it in favor of @code{scm_init_guile} since that will make your -program more portable. +To initialize Guile, you can use one of several functions. The first, +@code{scm_with_guile}, is the most portable way to initialize Guile. It +will initialize Guile when necessary and then call a function that you +can specify. Multiple threads can call @code{scm_with_guile} +concurrently and it can also be called more than once in a given thread. +The global state of Guile will survive from one call of +@code{scm_with_guile} to the next. Your function is called from within +@code{scm_with_guile} since the garbage collector of Guile needs to know +where the stack of each thread is. + +A second function, @code{scm_init_guile}, initializes Guile for the +current thread. When it returns, you can use the Guile API in the +current thread. This function employs some non-portable magic to learn +about stack bounds and might thus not be available on all platforms. One common way to use Guile is to write a set of C functions which perform some useful task, make them callable from Scheme, and then link @@ -58,7 +59,7 @@ application --- a special-purpose scripting language. In this situation, the application should probably process its command-line arguments in the same manner as the stock Guile interpreter. To make that straightforward, Guile provides the -@code{scm_shell} function. +@code{scm_boot_guile} and @code{scm_shell} function. @node A Sample Guile Main Program @subsection A Sample Guile Main Program -- 2.20.1