Debian Codegraph @

doc/cfuncs.htm

raw
1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <HTML>
3 <HEAD>
4 <META NAME=viewport CONTENT="width=device-width, initial-scale=1">
5 <TITLE>Loading C Functions in Icon</TITLE>
6 <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css">
7 <LINK REL="SHORTCUT ICON" HREF="shortcut.gif">
8 </HEAD>
9 <BODY>
10
11 <P> <A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif"
12 ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A>
13
14
15 <H1> Loading C Functions in Icon</H1>
16
17 <P> Gregg M. Townsend
18 <BR> <SMALL> Department of Computer Science </SMALL>
19 <BR> <SMALL> The University of Arizona </SMALL>
20
21 <P> <SMALL> www.cs.arizona.edu/icon/uguide/cfuncs.htm
22 <BR> Adapted from
23 <A HREF="http://www.cs.arizona.edu/icon/analyst/backiss/IA36.pdf">
24 <CITE>Icon Analyst 36</CITE></A>
25 <BR> Last updated October 27, 2009 </SMALL>
26
27
28 <P> Dynamic loading allows Icon programs to use functions coded in C
29 without modifying the Icon system itself. The C code is
30 compiled and placed in a library, then loaded
31 from the library when the Icon program runs.
32 Here is a discussion of the use and construction of such functions.
33
34
35 <H2> Program library functions </H2>
36
37 <P> The
38 <A HREF="http://www.cs.arizona.edu/icon/library/ipl.htm">Icon
39 program library</A>
40 includes an assortment of loadable Unix
41 interfaces and special-purpose functions.
42 Some are there for their general utility,
43 some for illustration, and some to fill specialized needs.
44 Here is a sampling:
45 <BLOCKQUOTE>
46 <CODE>bitcount(i)</CODE> &mdash; count the bits set in an integer
47 <BR><CODE>chmod(s, i)</CODE> &mdash; change the permissions of a file
48 <BR><CODE>fpoll(f, i)</CODE> &mdash; poll a file for input, with timeout
49 <BR><CODE>getpid()</CODE> &mdash; return the process identification number
50 <BR><CODE>kill(i1, i2)</CODE> &mdash; send a signal to a process
51 <BR><CODE>lgconv(i)</CODE> &mdash; convert a large integer to a string
52 <BR><CODE>tconnect(s, i)</CODE> &mdash; connect a file to a TCP port
53 <BR><CODE>umask(i)</CODE> &mdash; change the process permission mask
54 </BLOCKQUOTE>
55
56 <P> The full set of functions can be found in the
57 library's <CODE>cfuncs</CODE> directory.
58 Documentation and code are also
59 <A HREF="http://www.cs.arizona.edu/icon/library/fcfuncs.htm">available
60 on line</A>.
61 These functions are available automatically to an Icon program
62 that includes <CODE>link cfunc</CODE>.
63 The <CODE>bitcount()</CODE> function
64 is a good example for detailed examination.
65
66
67 <H2> Loading a function </H2>
68
69 <P> The built-in Icon function <CODE>loadfunc(libname, funcname)</CODE>
70 loads the C function <CODE>funcname()</CODE> from
71 the library file <CODE>libname</CODE> and returns a procedure
72 value. If the function cannot be loaded, the program is terminated.
73
74 <P> If <CODE>loadfunc(libname, "myfunc")</CODE> produces <CODE>p</CODE>,
75 then
76 <UL>
77 <LI><CODE>p(</CODE>arguments<CODE>)</CODE> calls <CODE>myfunc()</CODE>
78 with a list of arguments
79 <LI><CODE>type(p)</CODE> returns <CODE>"procedure"</CODE>
80 <LI><CODE>image(p)</CODE> returns <CODE>"function myfunc"</CODE>
81 <LI><CODE>proc("myfunc")</CODE> returns <CODE>p</CODE>
82 <LI><CODE>proc("myfunc", 0)</CODE> fails
83 </UL>
84
85 <P> The following program loads the function
86 <CODE>bitcount()</CODE> and assigns it to a global variable of the
87 same name. Assigning it to a global variable makes
88 it available to other procedures, although that's not
89 needed here. The <CODE>bitcount()</CODE> function returns the
90 number of bits that are set in the binary representation of an integer.
91 <BLOCKQUOTE><PRE>
92 $define Library "/icon/bin/libcfunc.so"
93 global bitcount
94
95 procedure main()
96 local i
97 bitcount := loadfunc(Library, "bitcount")
98 every i := 250 to 260 do
99 write(i, " ", bitcount(i))
100 end
101 </PRE></BLOCKQUOTE>
102
103 <P> When this program is run, it lists the integers
104 from 250 to 260 along with their bit counts:
105 <BLOCKQUOTE><PRE>
106 250 6
107 251 7
108 252 6
109 253 7
110 254 7
111 255 8
112 256 1
113 257 2
114 258 2
115 259 3
116 260 2
117 </PRE></BLOCKQUOTE>
118
119
120 <H2> Loading from a path </H2>
121
122 <P> Embedding a file name such as <CODE>/icon/bin/libcfunc.so</CODE>
123 in the program is undesirable. An alternative is for the
124 program to find the library file
125 using information from the program environment.
126
127 <P> The Icon library procedure
128 <CODE>pathload(libname, funcname)</CODE>
129 searches the set of directories given by
130 the <CODE>FPATH</CODE> environment variable to find <CODE>libname</CODE>
131 and load <CODE>funcname</CODE>.
132 As is usual in Icon path searching, the current
133 directory is searched first. If the
134 function cannot be loaded, the program is terminated.
135
136 <P> The <CODE>pathload()</CODE> procedure is included
137 by linking <CODE>pathfind</CODE> from the Icon program library. Using
138 <CODE>pathload()</CODE>, the example program becomes:
139 <BLOCKQUOTE><PRE>
140 $define Library "libcfunc.so"
141 link pathfind
142 global bitcount
143
144 procedure main()
145 local i
146 bitcount := pathload(Library, "bitcount")
147 every i := 250 to 260 do
148 write(i, " ", bitcount(i))
149 end
150 </PRE></BLOCKQUOTE>
151
152 <P> The default <CODE>FPATH</CODE> includes the current directory
153 and the installed Icon program library directory.
154 To find a library located elsewhere,
155 <CODE>FPATH</CODE> must be set explicitly before the program is run.
156
157
158 <H2> Implicit function loading </H2>
159
160 <P> It is possible to encapsulate the loading process so that the body of
161 an Icon program is unaware
162 that it is calling a C function. Consider this example:
163 <BLOCKQUOTE><PRE>
164 $define Library "libcfunc.so"
165 link pathfind
166
167 procedure main()
168 local i
169 every i := 250 to 260 do
170 write(i, " ", bitcount(i))
171 end
172
173 procedure bitcount(n)
174 bitcount := pathload(Library, "bitcount")
175 return bitcount(n)
176 end
177 </PRE></BLOCKQUOTE>
178
179 <P> First of all, notice that there is no longer a
180 global declaration for <CODE>bitcount</CODE>, and that the main
181 procedure no longer calls <CODE>pathload()</CODE>. As far as the
182 main procedure is concerned, <CODE>bitcount()</CODE> is just
183 another procedure to call, with no special requirements. This is a nice
184 simplification.
185
186 <P> The new <CODE>bitcount()</CODE> procedure is a bit tricky,
187 though. To understand it, you must know that an
188 Icon procedure declaration creates a global variable with an initial
189 value of that procedure. A
190 global variable is subject to assignment.
191
192 <P> When <CODE>main()</CODE> calls <CODE>bitcount()</CODE> for the first time,
193 the <CODE>bitcount()</CODE> procedure loads the <CODE>bitcount()</CODE>
194 C function from the library. The result is assigned to the
195 global variable <CODE>bitcount</CODE>, replacing the current procedure value.
196 Consequently, all subsequent calls
197 to <CODE>bitcount()</CODE> use the loaded function.
198
199 <P> The first call to <CODE>bitcount()</CODE> remains incomplete
200 after loading the function; the bits of <CODE>n</CODE> still must be
201 counted. So, following loading, the procedure calls
202 <CODE>bitcount(n)</CODE>. Although this looks like a recursive
203 call, it isn't &mdash; the call uses the current value of the
204 global variable <CODE>bitcount</CODE>, and so it calls the loaded C
205 function. The bits of <CODE>n</CODE> are counted and returned,
206 completing the first call.
207
208 <P> After the first time, calls to <CODE>bitcount()</CODE>
209 go directly to the loaded code. The Icon procedure
210 <CODE>bitcount()</CODE> is no longer accessible.
211
212
213 <H2> Implicit library loading </H2>
214
215 <P> The Icon program library provides an implicit loading procedure for
216 each of the C functions
217 in the library. Small procedures like the <CODE>bitcount()</CODE>
218 procedure shown above are included by linking
219 <CODE>cfunc</CODE>. Using the library interface procedure, our
220 example now can be simplified to this:
221 <BLOCKQUOTE><PRE>
222 link cfunc
223
224 procedure main()
225 local i
226 every i := 250 to 260 do
227 write(i, " ", bitcount(i))
228 end
229 </PRE></BLOCKQUOTE>
230
231 <P> The <CODE>link cfunc</CODE> declaration is the only hint that
232 <CODE>bitcount()</CODE> is written in C.
233
234
235 <H2> Making connections </H2>
236
237 <P> The bit counting example doesn't really illustrate the full potential
238 of using C functions in an
239 Icon program. Bit counting, after all, can be done in
240 Icon. Here's something that can't.
241
242 <P> The library function
243 <CODE>tconnect(host, port)</CODE> establishes a TCP connection
244 to a specified port
245 number on an Internet host. TCP is a communication protocol used by
246 telnet programs, news servers, web servers, and many other network
247 services.
248
249 <P> The following program makes a connection
250 to the Icon web server and writes the contents of
251 the Icon home page &mdash; in its original HTML markup
252 language, of course.
253 <BLOCKQUOTE><PRE>
254 link cfunc
255
256 procedure main()
257 local f
258 f := tconnect("www.cs.arizona.edu", 80)
259 writes(f, "GET /icon/ HTTP/1.0\n\n")
260 flush(f)
261 seek(f, 1)
262 while write(read(f))
263 end
264 </PRE></BLOCKQUOTE>
265
266 <P> The <CODE>tconnect()</CODE> call establishes the connection
267 and returns a file that is open for both input and
268 output. The internet host <CODE>www.cs.arizona.edu</CODE> is
269 the web server for the University of Arizona's
270 Department of Computer Science.
271 (Port 80 is the standard web server port number.)
272 The program then transmits a request for the
273 <CODE>/icon/</CODE> web page. The details of the request string
274 are specified by the
275 <A HREF="http://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext
276 Transfer Protocol</A>, not discussed here.
277
278 <P> The <CODE>flush()</CODE> call ensures that all the data is
279 actually sent, and then the <CODE>seek()</CODE> call resets the file
280 in preparation for a switch from output to input. In
281 this situation <CODE>seek()</CODE> does not actually reposition
282 the file, but it's required when switching modes.
283
284 <P> Finally, lines are read and echoed until an
285 end-of-file is received.
286
287
288 <H2> Writing loadable C functions </H2>
289
290 <P> Now consider the construction of library functions.
291 Because the Icon system expects C functions
292 to implement a certain interface, dynamic loading
293 usually requires specially written C functions. In
294 general, it is not possible to use an existing C
295 function without writing an intermediate "glue"
296 function.
297
298 <P> C functions must deal with the data types
299 used by the Icon run-time system, notably the
300 "descriptors" that represent all Icon values. While
301 an understanding of
302 <A HREF="http://www.cs.arizona.edu/icon/ibsale.htm">the
303 Icon run-time system</A> is helpful,
304 it is possible to create useful functions by
305 modeling them after existing library functions.
306 Integer and string values are most easily handled.
307
308 <P> A loadable C function has the prototype
309 <BLOCKQUOTE><CODE>int funcname(int argc, descriptor *argv)</CODE></BLOCKQUOTE>
310 where <CODE>argc</CODE> is the number of arguments and <CODE>argv</CODE> is
311 an array of argument descriptors.
312 The first element, <CODE>argv[0]</CODE>, is used to return an Icon value, and
313 is initialized to a descriptor for the null value. This
314 element is not included in the count <CODE>argc</CODE>. The
315 actual arguments begin with <CODE>argv[1]</CODE>.
316
317 <P> If the C function returns zero, the call from
318 Icon succeeds. A negative value indicates failure. If
319 a positive value is returned, it is interpreted as an
320 error number and a fatal error with that number is
321 signalled. In this case, if <CODE>argv[0]</CODE> is non-null, it is
322 reported as the "offending value". There is no way
323 for a C function to suspend, and no way to indicate
324 a null value as an offending value in the case of an
325 error.
326
327
328 <H2> Interface macros </H2>
329
330 <P> The C file <CODE>icall.h</CODE> contains a set of macros for
331 use in writing loadable functions. Documentation
332 is included as comments. This file can be found in the
333 <CODE>cfuncs</CODE> directory in the source code of the Icon
334 program library. Alternatively, it can be loaded
335 <A HREF="http://www.cs.arizona.edu/icon/library/src/cfuncs/icall.h">from
336 the web</A>. Macros are provided for:
337 <UL>
338 <LI>inspecting the type of an Icon value
339 <LI>validating the type of an argument
340 <LI>converting an Icon value into a C value
341 <LI>returning a C value in Icon form
342 <LI>failing or signaling an error
343 </UL>
344
345 <P> Most macros deal with integers or strings.
346 Some support also is provided for handling real
347 and file values.
348 The macros expect the C arguments to be declared with the
349 names of <CODE>argc</CODE> and <CODE>argv</CODE>.
350
351
352 <H2> Counting bits, again </H2>
353
354 <P> For a concrete example of a C function, consider the source code
355 of the <CODE>bitcount()</CODE> function used earlier:
356 <BLOCKQUOTE><PRE>
357 #include "icall.h"
358
359 int bitcount(int argc, descriptor *argv)
360 {
361 unsigned long v;
362 int n;
363 ArgInteger(1);
364 v = IntegerVal(argv[1]);
365 n = 0;
366 while (v != 0) {
367 n += v &amp; 1;
368 v &gt;&gt;= 1;
369 }
370 RetInteger(n);
371 }
372 </PRE></BLOCKQUOTE>
373
374 <P> Like all loadable functions, <CODE>bitcount()</CODE> is an
375 integer function with two parameters, <CODE>argc</CODE> and
376 <CODE>argv</CODE>.
377
378 <P> The <CODE>ArgInteger</CODE> macro call verifies that argument 1 is a simple
379 integer. (Large integers are
380 typically rejected by C functions because of the
381 extra work involved.) If argument 1 is missing or
382 has the wrong type, <CODE>ArgInteger</CODE> makes the function
383 return error code 101 (integer expected or out of
384 range).
385
386 <P> The <CODE>IntegerVal</CODE> macro call extracts the value
387 of the first argument.
388
389 <P> In each pass through the <CODE>while</CODE> loop, the low order bit of
390 <CODE>v</CODE> is
391 extracted (<CODE>v &amp; 1</CODE>), added to <CODE>n</CODE>, and
392 shifted off (<CODE>v &gt;&gt;= 1</CODE>). When no more nonzero bits
393 are left, the loop exits. Note that <CODE>v</CODE> is declared
394 unsigned to ensure that only zero bits are inserted
395 by the shift operation.
396
397 <P> The <CODE>RetInteger</CODE> macro call returns the value
398 of <CODE>n</CODE> as an Icon integer.
399
400
401 <H2> External data values </H2>
402
403 <P> Loadable functions can create and return data structures
404 that are treated as an opaque <CODE>external</CODE> type by Icon.
405 The use of external types is described <A HREF="extlvals.htm">separately</A>.
406
407
408 <H2> Preparing a library </H2>
409
410 <P> To be used in an Icon program, a C function
411 must be built and installed in a library. Compilation comes first,
412 usually involving a command such as
413 <BLOCKQUOTE><CODE>cc &ndash;c bitcount.c</CODE></BLOCKQUOTE>
414 to produce an object file <CODE>bitcount.o</CODE>.
415 The <CODE>&ndash;c</CODE> option causes a relocatable object file
416 to be produced instead of a stand-alone executable program.
417 If <CODE>icall.h</CODE> is not in the current directory,
418 an additional option may be needed to specify its location.
419 Other options, such as optimization options, also could be specified.
420
421 <P> A C function can be loaded only from a "shared library".
422 Even if there is just one function, it must be placed in a library.
423 Library names conventionally end with a <CODE>.so</CODE> suffix.
424
425 <P> It seems that every system has a different
426 way to create libraries, usually involving special
427 flags to <CODE>cc</CODE> or <CODE>ld</CODE>.
428 The shell script <CODE>mklib.sh</CODE>
429 embodies our understanding of shared library creation.
430 It takes one argument naming the library to be created and one or more
431 additional arguments listing object file names.
432 For example, the command
433 <BLOCKQUOTE><CODE>mklib.sh mylib.so bitcount.o</CODE></BLOCKQUOTE>
434 creates a file <CODE>mylib.so</CODE> containing the functions read
435 from <CODE>bitcount.o</CODE>.
436 Like <CODE>icall.h</CODE>, <CODE>mklib.sh</CODE> is available in
437 the program library source code or
438 <A HREF="http://www.cs.arizona.edu/icon/library/src/cfuncs/mklib.sh">from
439 the web</A>.
440
441
442 <H2> Summary </H2>
443
444 <UL>
445 <LI> Icon programs can load and call functions written in C.
446 <LI> The C functions must be tailored to Icon's requirements.
447 <LI> Each function must be loaded before it can be called.
448 <LI> A simple Icon procedure can be used to hide the loading details.
449 <LI> <CODE>pathload()</CODE> searches <CODE>FPATH</CODE>
450 to find a function library.
451 <LI> C functions can embed data in opaque <CODE>external</CODE> values.
452 <LI> Some useful functions are provided in the Icon program library.
453 </UL>
454
455 <HR>
456
457 </BODY>
458 </HTML>