Debian Codegraph @

doc/HOWTO-callback-scheme.adoc

raw
1 = Calling Scheme procedure from C code
2
3 == A quick starter
4
5 A typical code to call a Scheme procedure from C looks like the following.
6 (We assume you want to call a Scheme procedure `my-procedure` in
7 a module `my-module`):
8
9 [source,c]
10 ----
11 {
12 ...
13 static ScmObj x_proc = SCM_UNDEFINED;
14 SCM_BIND_PROC(x_proc, "my-procedure",
15 Scm_FindModule(SCM_SYMBOL(SCM_INTERN("my-module")), 0));
16 ...
17
18 ScmObj result = Scm_ApplyRec(x_proc, args);
19 ...
20
21 }
22 ----
23
24 The macro `SCM_BIND_PROC` checks whether `x_proc` is `SCM_UNDEFINED`, and
25 if so, fetches the value of `my-procedure` in `my-module` and stores
26 it in `x_proc`. You don't need a lock, for the result is idempotent.
27
28 The module `my-module` must be loaded before this code. If you're not
29 sure it's the case, you want to call `Scm_Require` before the above code;
30 it loads the library if it hasn't been loaded, and it's thread-safe.
31
32 Once you obtain the Scheme procedure in `x_proc`, there's a few
33 ways to call it.
34
35 The easiest way is to use `Scm_ApplyRec`. It takes the Scheme procedure
36 and a list of arguments, and receives a single result. For the zero to
37 five arguments case, we have `Scm_ApplyRec0` to `Scm_ApplyRec5`,
38 for your convenience.
39
40 The `Scm_ApplyRec` family won't trap Scheme errors; that is, if a Scheme
41 procedure throws an error, it `longjmp`s to somewhere outside of your
42 routine. If you allocate some resource in the above scope, it will leak.
43 Furthermore, the above code assumes there's **someone** outside of this
44 frame that are waiting to catch the error. If your code is
45 called from Gauche runtime, there's a Scheme VM running outside of
46 your routine that calls you---so the Scheme VM will handle the error.
47
48 == Capturing error
49
50 If you need to stop the error (either for resource handling or
51 there's no VM running outside of your routine), or you need to receive
52 more than one results, you have to use `Scm_Apply`:
53
54
55 [source,c]
56 ----
57 ...
58 static ScmObj x_proc = SCM_UNDEFINED;
59 SCM_BIND_PROC(x_proc, "my-procedure",
60 Scm_FindModule(SCM_SYMBOL(SCM_INTERN("my-module")), 0));
61 ...
62 ScmEvalPacket packet;
63 int nresults = Scm_Apply(x_proc, args, &packet);
64 ----
65
66 `Scm_Apply` always returns even the Scheme routine throws an error.
67 The return value is the number of results, or -1 if there's an error.
68 The `packet` structure contains the result(s) or the error thrown:
69
70 [source,c]
71 ----
72 typedef struct ScmEvalPacketRec {
73 ScmObj results[SCM_VM_MAX_VALUES];
74 int numResults;
75 ScmObj exception;
76 ScmModule *module; /* 'Current module' after evaluation */
77 } ScmEvalPacket;
78 ----
79
80 If the return value is nonnegative, `results[]` contains the return
81 value(s) of the procedure call. If the return value is negative,
82 `exception` contains the exception thrown during the procedure call.
83
84 == Continuation-safety
85
86 Scheme procedures can return more than once, but C doesn't expect
87 its functions to return one than once. So we have a checkpoint
88 at the Scheme-C boundary, and if a Scheme function tries to return
89 to C function in second time and later, it throws an error. Typically,
90 when such error occurs, we already finished executing the caller function
91 (in C), so even `Scm_Apply` can't capture it. Such error is generally
92 handled by the Gauche VM.
93
94 If you're implementing a C function to be called from Scheme program,
95 which in turn needs to call back to Scheme (think, for example,
96 you're writing `map`-like function in C), this limitation is too restricting.
97
98 Suppose you have a C function which is callable from Scheme, and it
99 takes a callback argument you need to call within the C function:
100
101 [source,c]
102 ----
103 ScmObj func(ScmObj callback)
104 {
105 ....
106 ScmObj args = ...
107
108 ScmObj r = Scm_ApplyRec(callback, args);
109 ....
110
111 return something;
112 }
113 ----
114
115 If a continuation is captured during calling `callback`, and it is
116 re-invoked after `Scm_ApplyRec` returns, _and_ `callback` tries
117 to return to the C world the second time, an error is thrown.
118 (Note that it is ok that the continuation is re-invoked after
119 `Scm_ApplyRec` returns, as far as the control transfers out before
120 returning from `callback` again.)
121
122 To allow `callback` to return more than once, you need to split
123 `func` into two parts.
124
125 [source,c]
126 ----
127 static ScmObj func_cc(ScmObj result, void **data);
128
129 /* The first half */
130 ScmObj func(ScmObj callback)
131 {
132 ScmObj args = ...
133 ....
134 Scm_VMPushCC(func_cc, NULL, 0);
135 return Scm_VMApply(callback, args);
136 }
137
138
139 /* The latter half. The result argument holds the return value
140 of callback. */
141 ScmObj func_cc(ScmObj result, void **data)
142 {
143 ...
144 return something;
145 }
146 ----
147
148 You see the C function `func` is split to two parts, one
149 before calling `callback` and another after calling `callback`.
150 The call `Scm_VMPushCC` arranges that the latter half `func_cc` to
151 be called after `callback` returns. `Scm_VMApply` arranges
152 `callback` to be called after `func` returns to VM.
153
154 You should treat what `Scm_VMApply` returns as an opaque object.
155 It is important that the value will be returned to the Gauche VM.
156 What `Scm_VMApply` and `Scm_VMPushCC` do is to set up the VM state
157 so that `callback` and `func_cc` will be called. If you do something
158 to change the VM state between returning `Scm_VMApply` and the VM takes back
159 control, unexpected things can occur.
160
161 If you call `callback` in this way, and a continuation is captured
162 within `callback`, it does not involve C calling stack, so that the
163 `callback` can return as many times as it wish. It's simply that
164 `func_cc` will be called more than once.
165
166 What if you need to retain a local variable across the call of
167 `callback`?
168
169 [source,c]
170 ----
171 ScmObj func(ScmObj callback)
172 {
173 ....
174 ScmObj args = ...
175 ScmObj some_var = ...
176 ....
177 ScmObj r = Scm_ApplyRec(callback, args);
178 ....
179 do_something_with(some_var);
180 ....
181 return something;
182 }
183 ----
184
185 You can pass a small number of variables via `void **data` array.
186
187 [source,c]
188 ----
189 static ScmObj func_cc(ScmObj result, void **data);
190
191 /* The first half */
192 ScmObj func(ScmObj callback)
193 {
194 ScmObj args = ...
195 ScmObj some_var = ...
196 ....
197 void *data[1];
198 data[0] = some_var;
199 Scm_VMPushCC(func_cc, data, 1);
200 return Scm_VMApply(callback, args);
201 }
202
203
204 /* The latter half. The result argument holds the return value
205 of callback. */
206 ScmObj func_cc(ScmObj result, void **data)
207 {
208 ScmObj some_var = SCM_OBJ(data[0]);
209 ....
210 do_something_with(some_var);
211 ...
212 return something;
213 }
214 ----
215
216 Here, the content of data array passed to `Scm_VMPushCC` is carried
217 over to the `data` argument of `func_cc`. The array itself is copied
218 into the area managed by Gauche VM, so the `data` variable in `func` can
219 be local. The `data` variable in `func_cc` is valid only until Gauche
220 VM state changes, so it is better to extract its content before calling
221 any Gauche API.
222
223 The maximum size of the data array is `SCM_CCONT_DATA_SIZE`, which is
224 at least 6. If you need to retain more local state, you should allocate
225 a struct by `SCM_NEW` and pass its pointer via `data`.
226 Be aware that `func_cc` can be called more than once You shouldn't
227 deallocate resources explicitly in `func_cc`, but leave that work
228 to the garbage collector.