| 1 | @c -*-texinfo-*- |
| 2 | @c This is part of the GNU Guile Reference Manual. |
| 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007 |
| 4 | @c Free Software Foundation, Inc. |
| 5 | @c See the file guile.texi for copying conditions. |
| 6 | |
| 7 | |
| 8 | @node Initialization |
| 9 | @section Initializing Guile |
| 10 | @cindex Initializing Guile |
| 11 | |
| 12 | Each thread that wants to use functions from the Guile API needs to |
| 13 | put itself into guile mode with either @code{scm_with_guile} or |
| 14 | @code{scm_init_guile}. The global state of Guile is initialized |
| 15 | automatically when the first thread enters guile mode. |
| 16 | |
| 17 | When a thread wants to block outside of a Guile API function, it |
| 18 | should leave guile mode temporarily with @code{scm_without_guile}, |
| 19 | @xref{Blocking}. |
| 20 | |
| 21 | Threads that are created by @code{call-with-new-thread} or |
| 22 | @code{scm_spawn_thread} start out in guile mode so you don't need to |
| 23 | initialize them. |
| 24 | |
| 25 | @deftypefn {C Function} {void *} scm_with_guile (void *(*func)(void *), void *data) |
| 26 | Call @var{func}, passing it @var{data} and return what @var{func} |
| 27 | returns. While @var{func} is running, the current thread is in guile |
| 28 | mode and can thus use the Guile API. |
| 29 | |
| 30 | When @code{scm_with_guile} is called from guile mode, the thread remains |
| 31 | in guile mode when @code{scm_with_guile} returns. |
| 32 | |
| 33 | Otherwise, it puts the current thread into guile mode and, if needed, |
| 34 | gives it a Scheme representation that is contained in the list returned |
| 35 | by @code{all-threads}, for example. This Scheme representation is not |
| 36 | removed when @code{scm_with_guile} returns so that a given thread is |
| 37 | always represented by the same Scheme value during its lifetime, if at |
| 38 | all. |
| 39 | |
| 40 | When this is the first thread that enters guile mode, the global state |
| 41 | of Guile is initialized before calling @code{func}. |
| 42 | |
| 43 | The function @var{func} is called via |
| 44 | @code{scm_with_continuation_barrier}; thus, @code{scm_with_guile} |
| 45 | returns exactly once. |
| 46 | |
| 47 | When @code{scm_with_guile} returns, the thread is no longer in guile |
| 48 | mode (except when @code{scm_with_guile} was called from guile mode, see |
| 49 | above). Thus, only @code{func} can store @code{SCM} variables on the |
| 50 | stack and be sure that they are protected from the garbage collector. |
| 51 | See @code{scm_init_guile} for another approach at initializing Guile |
| 52 | that does not have this restriction. |
| 53 | |
| 54 | It is OK to call @code{scm_with_guile} while a thread has temporarily |
| 55 | left guile mode via @code{scm_without_guile}. It will then simply |
| 56 | temporarily enter guile mode again. |
| 57 | @end deftypefn |
| 58 | |
| 59 | @deftypefn {C Function} void scm_init_guile () |
| 60 | Arrange things so that all of the code in the current thread executes as |
| 61 | if from within a call to @code{scm_with_guile}. That is, all functions |
| 62 | called by the current thread can assume that @code{SCM} values on their |
| 63 | stack frames are protected from the garbage collector (except when the |
| 64 | thread has explicitly left guile mode, of course). |
| 65 | |
| 66 | When @code{scm_init_guile} is called from a thread that already has been |
| 67 | in guile mode once, nothing happens. This behavior matters when you |
| 68 | call @code{scm_init_guile} while the thread has only temporarily left |
| 69 | guile mode: in that case the thread will not be in guile mode after |
| 70 | @code{scm_init_guile} returns. Thus, you should not use |
| 71 | @code{scm_init_guile} in such a scenario. |
| 72 | |
| 73 | When a uncaught throw happens in a thread that has been put into guile |
| 74 | mode via @code{scm_init_guile}, a short message is printed to the |
| 75 | current error port and the thread is exited via @code{scm_pthread_exit |
| 76 | (NULL)}. No restrictions are placed on continuations. |
| 77 | |
| 78 | The function @code{scm_init_guile} might not be available on all |
| 79 | platforms since it requires some stack-bounds-finding magic that might |
| 80 | not have been ported to all platforms that Guile runs on. Thus, if you |
| 81 | can, it is better to use @code{scm_with_guile} or its variation |
| 82 | @code{scm_boot_guile} instead of this function. |
| 83 | @end deftypefn |
| 84 | |
| 85 | @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}) |
| 86 | Enter guile mode as with @code{scm_with_guile} and call @var{main_func}, |
| 87 | passing it @var{data}, @var{argc}, and @var{argv} as indicated. When |
| 88 | @var{main_func} returns, @code{scm_boot_guile} calls @code{exit (0)}; |
| 89 | @code{scm_boot_guile} never returns. If you want some other exit value, |
| 90 | have @var{main_func} call @code{exit} itself. If you don't want to exit |
| 91 | at all, use @code{scm_with_guile} instead of @code{scm_boot_guile}. |
| 92 | |
| 93 | The function @code{scm_boot_guile} arranges for the Scheme |
| 94 | @code{command-line} function to return the strings given by @var{argc} |
| 95 | and @var{argv}. If @var{main_func} modifies @var{argc} or @var{argv}, |
| 96 | it should call @code{scm_set_program_arguments} with the final list, so |
| 97 | Scheme code will know which arguments have been processed |
| 98 | (@pxref{Runtime Environment}). |
| 99 | @end deftypefn |
| 100 | |
| 101 | @deftypefn {C Function} void scm_shell (int @var{argc}, char **@var{argv}) |
| 102 | Process command-line arguments in the manner of the @code{guile} |
| 103 | executable. This includes loading the normal Guile initialization |
| 104 | files, interacting with the user or running any scripts or expressions |
| 105 | specified by @code{-s} or @code{-e} options, and then exiting. |
| 106 | @xref{Invoking Guile}, for more details. |
| 107 | |
| 108 | Since this function does not return, you must do all |
| 109 | application-specific initialization before calling this function. |
| 110 | @end deftypefn |