| 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. |