| 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 & 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, &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–>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> |