diff options
author | Marius Vollmer <mvo@zagadka.de> | 2005-01-24 23:41:14 +0000 |
---|---|---|
committer | Marius Vollmer <mvo@zagadka.de> | 2005-01-24 23:41:14 +0000 |
commit | 76da80e7881947ebcdb647e5ce4be029fece29f2 (patch) | |
tree | 9a56249fecf0002eefc25c6a0bfeb53a2b277d7f /doc/ref/api-init.texi | |
parent | a54a94b39707f47a1f30533bcf7664094d65d073 (diff) | |
download | guile-76da80e7881947ebcdb647e5ce4be029fece29f2.tar.gz |
Reverted changed from 2005/01/24 19:14:54, which was a commit to the
wrong branch. Sorry.
Diffstat (limited to 'doc/ref/api-init.texi')
-rw-r--r-- | doc/ref/api-init.texi | 128 |
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}) |