Debian Codegraph @

doc/extlvals.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>Icon External Values</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 <H1> Icon External Values </H1>
15
16 <P> Carl Sturtivant
17 <BR> <SMALL> Computer Science &amp; Engineering Department </SMALL>
18 <BR> <SMALL> University of Minnesota </SMALL>
19
20 <P> Gregg M. Townsend
21 <BR> <SMALL> Department of Computer Science </SMALL>
22 <BR> <SMALL> The University of Arizona </SMALL>
23
24 <P> <SMALL> www.cs.arizona.edu/icon/uguide/extlvals.htm
25 <BR>
26 Last updated March 25, 2010</SMALL>
27
28
29 <H2> Introduction </H2>
30
31
32 <P> External values provide a way for
33 <A HREF="cfuncs.htm">dynamically loaded C functions</A>
34 to create and return opaque data structures to an Icon program.
35 This allows state to be maintained across multiple calls of
36 loaded functions.
37
38 <P> The creation of an external value in C defines
39 not just the data itself but also some related attributes.
40 These control the sorting behavior, image, and other such aspects.
41 Icon provides defaults and also adds a serial number
42 similar to those of lists, sets, and tables.
43
44 <P> The specification of attributes effectively creates a number
45 of distinct types.
46 Each loadable library can define the types it needs for its own purposes.
47 From an object-oriented perspective, these can be seen as subtypes
48 of a common <CODE>external</CODE> type.
49
50
51 <H2> External Values in an Icon Program </H2>
52
53 <P> External values are opaque to Icon. They are <EM>created</EM> only by
54 dynamically
55 loaded C functions, any of which in turn may have access to their internals. In
56 this way a library of Icon functions to work with a specific kind of external
57 value is possible. However, such values can be seen and manipulated (assigned,
58 passed to procedures or functions, sorted, copied, etc.) in Icon. The
59 behavior of an external value in Icon may be modified to some extent by the
60 implementation of the dynamically loaded function that is used to create it, as
61 described below.
62
63 <P> In what follows let <CODE>E</CODE>, <CODE>E1</CODE>, and <CODE>E2</CODE>
64 be external values
65 produced by some loaded function or functions. Icon prescribes the following
66 default behavior of such values, which is exhibited if the functions that
67 created them did not override such at the time of creation. Otherwise behavior
68 in the following contexts is determined by the external values' creators.
69
70 <P> External values always sort after values of all other types.
71 Within themselves external
72 values are first sorted by type name (which is a set by the creator,
73 is returned by the Icon function <CODE>type</CODE>,
74 and specifies a subtype of the external type).
75 The default sort within such a subtype is by serial number. Only sorting
76 within a subtype (i.e., externals with a specific type name) can be overridden
77 by the creator. See the next section for a description of the relevant C
78 internals. The default behavior follows.
79
80 <BLOCKQUOTE><DL>
81 <DT><CODE>type(E)</CODE>
82 <DD>returns the string <CODE>"external"</CODE>
83 <DT><CODE>image(E)</CODE>
84 <DD>returns a string indicating the type, serial number,
85 and the number of data words,
86 <I>e.g.</I> <CODE>"external_12(3)"</CODE>
87 <DT><CODE>copy(E)</CODE>
88 <DD>returns <CODE>E</CODE> itself without copying
89 <DT><CODE>sort()</CODE>
90 <DD>external values sort first by type name and then by serial number
91 <DT><CODE>E1 === E2</CODE>
92 <DD>produces <CODE>E1</CODE> when <CODE>E1</CODE> and <CODE>E2</CODE>
93 are the same external object; otherwise fails
94 <DT><CODE>E1 ~=== E2</CODE>
95 <DD>produces <CODE>E2</CODE> when <CODE>E1</CODE> and <CODE>E2</CODE>
96 are distinct; otherwise fails
97 </DL></BLOCKQUOTE>
98
99
100 <H2> Creating and Using External Values in C </H2>
101
102 <P>These next sections describe the C interface for a reader who is
103 familiar with the use of loadable functions.
104
105 <P> An Icon external value is implemented by a descriptor that points
106 to an external block containing several components.
107 The data area and the function list are the most important of these.
108
109 <P> An integer word count indicates the size of the data area.
110 This is specified when the external block is created.
111 Often external data is a single pointer to other data (a handle)
112 and so only one word is required.
113
114 <P> The function list allows the programmer to override,
115 for all values of the same external type,
116 the default behaviors listed in the previous section.
117 The list is a callback table pointing to programmer-defined C functions
118 as described in more detail below.
119 The function list also acts as a unique type identifier, because external
120 values with different function lists behave as values of distinct type.
121
122 <P> A dynamically loaded C function allocates an external value by including
123 <CODE>ipl/cfuncs/icall.h</CODE> and calling <CODE>alcexternal</CODE>:
124
125 <BLOCKQUOTE>
126 <DL>
127 <DT>
128 <CODE>externalblock *alcexternal</CODE>(long size, funclist *funcs, void *data)
129 </DT><DD>
130 allocates and returns a pointer to an external block.
131 <BR><VAR>size</VAR> specifies the number of bytes
132 in the entire external block (and by implication
133 the size of the data block inside it).
134 <BR><VAR>funcs</VAR>, if not null, specifies a list of functions to
135 override the default behavior. See the next section.
136 <BR><VAR>data</VAR>, if not null, specifies the location of data
137 that is copied in to initialize the data block (until it is full).
138 </DD></DL>
139 </BLOCKQUOTE>
140
141 <P>
142 A typical call might be
143 <BLOCKQUOTE>
144 blk = alcexternal(sizeof(externalblock) + sizeof(mydata), funcs, &amp;mydata);
145 </BLOCKQUOTE>
146 The result is returned to Icon by the macro call
147 <CODE>RetExternal(</CODE>blk<CODE>)</CODE>.
148 The block may eventually be freed by garbage collection if it
149 is not saved or if it later becomes inaccessible to the Icon program.
150
151 <P> A loadable function that accepts an external value as an argument can call
152 <BLOCKQUOTE>
153 ArgExternal(i,f);
154 </BLOCKQUOTE>
155 to validate argv[i] as an external value of the type associated
156 with function list f, and can then call
157 <BLOCKQUOTE>
158 blk = ExternalBlock(i);
159 </BLOCKQUOTE>
160 to get the address of the associated external block;
161 the associated data is at blk&ndash;&gt;data.
162
163 <P>A more complete example is found in the file
164 <CODE>ipl/cfuncs/external.c</CODE>.
165
166
167 <H2> The Function List Passed to alcexternal </H2>
168
169 <P> The function list associated with an external value is a struct
170 containing pointers to C functions.
171 It is reminiscent of a "dispatch table" or "class pointer"
172 for dynamic method calls in an implementation of an object oriented programming
173 language. Indeed an Icon external value is very much like a traditional object
174 with its own data and methods. Typically such a function list would be static
175 and shared among many Icon external values of the same kind ("class" or "type").
176
177 <P> Every external value has a function list; a default list is supplied
178 if NULL is passed to alcexternal. A null entry within a function list
179 produces the default behavior for the associated action.
180
181 <P> Functions in the list use the same interface as loadable C functions.
182 Incoming arguments are passed beginning at argv[1].
183 A result is produced by storing it in argv[0]
184 and returning 0 as the outcome of the function.
185 When extlcmp is called, argc has a value of 2;
186 for the other functions, argc is 1.
187
188 <P> The possible custom functions are as follows:
189
190 <BLOCKQUOTE>
191 <DL>
192
193 <DT>
194 <CODE>int extlcmp</CODE>(int argc, descriptor *argv)
195 </DT><DD>
196 returns an Icon integer
197 for use in sorting two external values that both have this function list
198 and are therefore considered to be of the same external subtype.
199 The function result should be negative if the first external value is
200 deemed less than the second, zero if they are deemed equal, and positive
201 if the first is deemed greater than the second.
202 This overrides the default behavior of the <CODE>sort</CODE> function
203 which compares serial numbers.
204 </DD>
205
206 <DT>
207 <CODE>int extlcopy</CODE>(int argc, descriptor *argv)
208 </DT><DD>
209 returns an external value defined as a copy of its argument.
210 This overrides the default behavior of the <CODE>copy</CODE> function,
211 which is to return another reference to the external value without copying.
212 </DD>
213
214 <DT>
215 <CODE>int extlname</CODE>(int argc, descriptor *argv)
216 </DT><DD>
217 returns an Icon string naming the type of the external value.
218 This overrides the default behavior of the <CODE>type</CODE> function, and thus
219 also affects the ordering relative to other external values when sorting.
220 </DD>
221
222 <DT>
223 <CODE>int extlimage</CODE>(int argc, descriptor *argv)
224 </DT><DD>
225 returns an Icon string to serve as the image of the external value.
226 This overrides the default behavior of the <CODE>image</CODE> function.
227 </DD>
228
229 </DL>
230 </BLOCKQUOTE>
231
232
233 <H2> Implementation Details </H2>
234
235 <SMALL>This section supplements the Icon
236 <A HREF="http://www.cs.arizona.edu/icon/ibsale.htm">
237 implementation book</A>.</SMALL>
238
239 <P> A descriptor for an external value has a vword containing the bit pattern
240 D_External which contains the value T_External indicating the external type,
241 along with the bit F_Nqual indicating that the value is not a string and the
242 bit F_Ptr indicating to the garbage collector that the dword is a pointer that
243 needs tending. The dword contains a pointer to an external block. This block is
244 implemented as a C struct with a pointer to a function block C struct as
245 follows. The structs below, along with types word and descriptor,
246 are defined in ipl/cfuncs/icall.h.
247
248 <PRE>
249 typedef struct funclist { /* list of user defined callbacks */
250 int (*extlcmp) (int argc, descriptor *argv); /* compare */
251 int (*extlcopy) (int argc, descriptor *argv); /* copy */
252 int (*extlname) (int argc, descriptor *argv); /* type name */
253 int (*extlimage) (int argc, descriptor *argv); /* image */
254 } funclist;
255
256 typedef struct externalblock {
257 word title; /* the block header, including type */
258 word size; /* the number of bytes in the block */
259 word id; /* the serial number */
260 funclist *funcs; /* pointer to the callback list */
261 word data[]; /* arbitrary custom data */
262 } externalblock;
263 </PRE>
264
265 <P> A call of alcexternal initializes all fields of an external block.
266 Data is copied without interpretation, and the function
267 list pointer is stored. The header is assigned an appropriate constant for the
268 garbage collector, and the size is set. alcexternal maintains a static
269 count of the number of external blocks allocated, and this is incremented and
270 assigned to id.
271
272 <P> The following error code numbers are assigned for use with external values:
273 <BLOCKQUOTE><TABLE SUMMARY=layout>
274 <TR><TH>errno<TH>errtext<TH>meaning
275 <TR><TD><CODE>131</CODE><TD><CODE>external expected</CODE>
276 <TD>not an external value
277 <TR><TD><CODE>132</CODE><TD><CODE>incorrect external type</CODE>
278 <TD>external of wrong flavor
279 <TR><TD><CODE>133</CODE><TD><CODE>invalid external value</CODE>
280 <TD>right flavor in wrong context
281 <TR><TD><CODE>134</CODE><TD><CODE>malformed external value</CODE>
282 <TD>data is bogus, not just inappropriate
283 </TABLE></BLOCKQUOTE>
284
285 <HR>
286
287 </BODY>
288 </HTML>