| 1 |
|
| 2 |
A Technique to Call Icon from C under Icon Version 9 |
| 3 |
Carl Sturtivant, 2008/2/20 Confidential Draft #1 |
| 4 |
|
| 5 |
|
| 6 |
1. Summary. |
| 7 |
|
| 8 |
A new Icon function written in C with a special interface may be |
| 9 |
dynamically loaded from a shared object using the built-in function |
| 10 |
loadfunc [GT95]. We show how such a function may in turn call an Icon |
| 11 |
procedure using the technique described below, provided that the |
| 12 |
procedure call itself does not suspend, but only returns or fails. Note |
| 13 |
that this does not impose constraints of any kind upon other procedures |
| 14 |
executed as a consequence of calling the original procedure. In |
| 15 |
particular, the Icon procedure called from C may in turn lead to a call |
| 16 |
of another Icon function written in C calling Icon recursively. The |
| 17 |
technique described has been implemented and briefly tested with Icon |
| 18 |
9.51(?). |
| 19 |
|
| 20 |
|
| 21 |
2. Overview. |
| 22 |
|
| 23 |
If the body of an Icon function written in C is to call an Icon |
| 24 |
procedure that does not suspend and retrieve its return value, all |
| 25 |
without modifying iconx, then there are a number of hurdles to jump. |
| 26 |
The procedure descriptor, and those of its arguments must be pushed |
| 27 |
onto the Icon stack, and the interpreter induced to believe it needs to |
| 28 |
execute an icode instruction to invoke it, one that is not present in |
| 29 |
the icode it loaded. Once the procedure returns (or fails) the |
| 30 |
interpreter must be induced to return control to C just after the point |
| 31 |
where the attempt to call it occurred, rather than simply to go on to |
| 32 |
the next icode instruction. Then the result of the call needs to be |
| 33 |
popped off the Icon stack so that it is in the same state as before the |
| 34 |
call, since C does not normally modify the Icon stack. (Other details |
| 35 |
of the state of the interpreter will be restored by the mechanism |
| 36 |
whereby a procedure is called in Icon.) In all other respects, the main |
| 37 |
interpreter loop must continue to behave as before. |
| 38 |
|
| 39 |
These hurdles are insurmountable, so long as the code of the main |
| 40 |
interpreter loop is inviolate. The code of that loop as it is |
| 41 |
incorporated into iconx is inviolate, since a design goal is that the |
| 42 |
technique should work with the existing implementation. Therefore, we |
| 43 |
take a copy of that loop, and modify it to the ends above, and execute |
| 44 |
it only in order to call Icon. (The original interpreter continues to |
| 45 |
be used for all other purposes.) Dynamic linking allows the new |
| 46 |
interpreter loop to refer to all C globals and functions in iconx, and |
| 47 |
so nothing else need be copied, these things are merely referred to. In |
| 48 |
fact it takes very little modification of the copy to achieve these |
| 49 |
goals, and the result is a C function called icall to which the |
| 50 |
procedure and its arguments are passed to effect the call to Icoan. To |
| 51 |
simplify this interface, the arguments are passed as a single Icon |
| 52 |
list. The resulting function then has similar semantics as the binary |
| 53 |
"!" operator in Icon, (which we henceforth call 'apply' as it applies a |
| 54 |
procedure to its argument list) except that it may be called from C. |
| 55 |
|
| 56 |
|
| 57 |
3. Implementation. |
| 58 |
|
| 59 |
The main interpreter loop written in RTL resides in the file |
| 60 |
src/runtime/interp.r in the Icon distribution. This was translated into |
| 61 |
the corresponding C file xinterp.c by the RTL translator rtt with the |
| 62 |
command 'rtt -x interp.r'. Now this C file is edited into a file |
| 63 |
compiled into a single C function called icall, taking two descriptors |
| 64 |
(a procedure and a list of arguments) and returning an integer code. |
| 65 |
The effect of calling icall is to apply the procedure to its arguments, |
| 66 |
and restore the state of the interpreter, leaving the result of the |
| 67 |
call just beyond the stack pointer for retrieval. |
| 68 |
|
| 69 |
The contents of xinterp.c consist of some global variables and a |
| 70 |
function interp containing the interpreter loop. The global variable |
| 71 |
declarations are all modified by prefixing them with 'extern', so that |
| 72 |
they now simply refer to those used by the interpreter loop inside |
| 73 |
iconx. The function interp that returns an integer signal and has two |
| 74 |
parameters: an integer fsig used when the interpreter is called |
| 75 |
recursively to simulate suspension, and cargp, a pointer into the Icon |
| 76 |
stack. The function interp is renamed icall. |
| 77 |
|
| 78 |
Examination of src/runtime/init.r indicates that the signal 0 is passed |
| 79 |
to interp when it is initially called non-recursively to start up |
| 80 |
iconx. So fsig is removed from the parameter list and made a local |
| 81 |
variable initialized to 0. Similarly cargp is made a local variable, |
| 82 |
and icall is given two parameters theProc and arglist used to pass that |
| 83 |
necessary for the call to Icon. Immediately after the initial |
| 84 |
declarations inside icall, the Icon stack pointer sp is used to |
| 85 |
initialize cargp to refer to the first descriptor on the stack beyond |
| 86 |
sp, which is assigned the procedure desciptor parameter of icall. The |
| 87 |
desciptor beyond that is assigned the argument list descriptor |
| 88 |
parameter, and the stack pointer augmented to refer to its last word. A |
| 89 |
new local variable result_sp is initialized to location on the stack of |
| 90 |
the last word of the procedure descriptor. This is used by the |
| 91 |
mechanism to return to C described below. Now the details of pushing |
| 92 |
the procedure descriptor and the argument list descriptor onto the |
| 93 |
stack are complete. |
| 94 |
|
| 95 |
The body of interp consists of some straight-line code followed by the |
| 96 |
interpreter loop, which contains some code to get the next icode |
| 97 |
instruction followed by a switch to jump to the correct code to execute |
| 98 |
it, all inside and endless loop. Just before the loop starts, an |
| 99 |
unconditional goto is inserted, jumping to a newly inserted label |
| 100 |
called aptly 'apply' which is placed just after the switch label |
| 101 |
(called Op_Apply in interp.r) which precedes the code to implement the |
| 102 |
icode 'apply' instruction, that implements the apply operator (binary |
| 103 |
"!") in Icon. This instruction expects to find a procedure descriptor |
| 104 |
and a list descriptor on the stack, and then causes the icode |
| 105 |
instructions of the procedure to be accordingly invoked. Now the |
| 106 |
details of calling the procedure are complete. What is left to insert |
| 107 |
is the mechanism to return to C. |
| 108 |
|
| 109 |
When the procedure that we called returns or fails, it will execute a |
| 110 |
'pret' instruction or a 'pfail' instruction. However, these |
| 111 |
instructions may also be executed by Icon procedures called from the |
| 112 |
one we called. At the end of the code for 'pret' inside the switch in |
| 113 |
the interpreter is a 'break' to leave the switch and go round to get |
| 114 |
the next icode instruction. Just before that 'break' we can tell if our |
| 115 |
procedure call is the one returning by comparing the Icon stack pointer |
| 116 |
sp to the one we saved, result_sp, which our procedure call will have |
| 117 |
restored sp to when it overwrote the procedure descriptor with the |
| 118 |
result of the call. So if they are equal, we can clean up (decrement |
| 119 |
ilevel, move sp just before the former procedure descriptor) and |
| 120 |
return, finishing the call to icall. Now C can retrieve the result of |
| 121 |
the call just beyond the stack pointer. The 'pfail' code is similar, |
| 122 |
just before a jump to efail, which we do not execute since the context |
| 123 |
of our call is not an Icon expression. C can determine success or |
| 124 |
failure from the integer code returned. This completes the mechanism to |
| 125 |
return to C. |
| 126 |
|
| 127 |
|
| 128 |
4. Conclusions |
| 129 |
|
| 130 |
Overall this mechanism depends upon few things, mainly upon the fact |
| 131 |
that when a procedure is called, the Icon stack below the part used for |
| 132 |
the call is not modified during the call. Our copy of the interpreter |
| 133 |
loop is identical to the original with the exception of the code added |
| 134 |
for the C return mechanism, which is only exceptionally executed. And |
| 135 |
the Icon procedure call mechanism itself will save and restore the |
| 136 |
interpreter state apart from the stack pointer which we abuse at the |
| 137 |
start and restore at the end. The compiled result with gcc was about 10 |
| 138 |
Kbyte. A simple test confirmed that call and return occur in the |
| 139 |
correct order, from Icon to C to Icon returning to C returning to Icon. |
| 140 |
|