Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
9a18d8d4 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007 |
07d83abe MV |
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 | |
9a18d8d4 | 10 | @cindex Initializing Guile |
07d83abe | 11 | |
b4fddbbe MV |
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 | ||
54428bb8 MV |
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}. | |
b4fddbbe MV |
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 | ||
c2110081 | 25 | @deftypefn {C Function} {void *} scm_with_guile (void *(*func)(void *), void *data) |
b4fddbbe MV |
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 | |
54428bb8 MV |
55 | left guile mode via @code{scm_without_guile}. It will then simply |
56 | temporarily enter guile mode again. | |
07d83abe MV |
57 | @end deftypefn |
58 | ||
59 | @deftypefn {C Function} void scm_init_guile () | |
b4fddbbe MV |
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 | |
877f06c3 | 64 | thread has explicitly left guile mode, of course). |
b4fddbbe MV |
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 | |
9a18d8d4 KR |
97 | Scheme code will know which arguments have been processed |
98 | (@pxref{Runtime Environment}). | |
07d83abe MV |
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 |