Debian Codegraph @

ipl/packs/loadfuncpp/doc/icall.txt

raw
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