Each thread that wants to use functions from the Guile API needs to
put itself into guile mode with either
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
Threads that are created by
scm_spawn_thread start out in guile mode so you don't need to
Call func, passing it data and return what func returns. While func is running, the current thread is in guile mode and can thus use the Guile API.
scm_with_guileis called from guile mode, the thread remains in guile mode when
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
all-threads, for example. This Scheme representation is not removed when
scm_with_guilereturns 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
The function func is called via
scm_with_guilereturns exactly once.
scm_with_guilereturns, the thread is no longer in guile mode (except when
scm_with_guilewas called from guile mode, see above). Thus, only
SCMvariables on the stack and be sure that they are protected from the garbage collector. See
scm_init_guilefor another approach at initializing Guile that does not have this restriction.
It is OK to call
scm_with_guilewhile a thread has temporarily left guile mode via
scm_without_guile. It will then simply temporarily enter guile mode again.
Arrange things so that all of the code in the current thread executes as if from within a call to
scm_with_guile. That is, all functions called by the current thread can assume that
SCMvalues on their stack frames are protected from the garbage collector (except when the thread has explicitly left guile mode, of course).
scm_init_guileis called from a thread that already has been in guile mode once, nothing happens. This behavior matters when you call
scm_init_guilewhile the thread has only temporarily left guile mode: in that case the thread will not be in guile mode after
scm_init_guilereturns. Thus, you should not use
scm_init_guilein such a scenario.
When a uncaught throw happens in a thread that has been put into guile mode via
scm_init_guile, a short message is printed to the current error port and the thread is exited via
scm_pthread_exit (NULL). No restrictions are placed on continuations.
scm_init_guilemight not be available on all platforms since it requires some stack-bounds-finding magic that might not have been ported to all platforms that Guile runs on. Thus, if you can, it is better to use
scm_with_guileor its variation
scm_boot_guileinstead of this function.
Enter guile mode as with
scm_with_guileand call main_func, passing it data, argc, and argv as indicated. When main_func returns,
scm_boot_guilenever returns. If you want some other exit value, have main_func call
exititself. If you don't want to exit at all, use
scm_boot_guilearranges for the Scheme
command-linefunction to return the strings given by argc and argv. If main_func modifies argc or argv, it should call
scm_set_program_argumentswith the final list, so Scheme code will know which arguments have been processed (see Runtime Environment).
Process command-line arguments in the manner of the
guileexecutable. This includes loading the normal Guile initialization files, interacting with the user or running any scripts or expressions specified by
-eoptions, and then exiting. See Invoking Guile, for more details.
Since this function does not return, you must do all application-specific initialization before calling this function.