ionnotes/node4.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2
   3 <!--Converted with LaTeX2HTML 2002-2-1 (1.71)
   4 original version by:  Nikos Drakos, CBLU, University of Leeds
   5 * revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
   6 * with significant contributions from:
   7   Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
   8 <HTML>
   9 <HEAD>
  10 <TITLE>3 The Lua interface</TITLE>
  11 <META NAME="description" CONTENT="3 The Lua interface">
  12 <META NAME="keywords" CONTENT="ionnotes">
  13 <META NAME="resource-type" CONTENT="document">
  14 <META NAME="distribution" CONTENT="global">
  15
  16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
  17 <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
  18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
  19
  20 <LINK REL="STYLESHEET" HREF="ionnotes.css">
  21
  22 <LINK REL="next" HREF="node5.html">
  23 <LINK REL="previous" HREF="node3.html">
  24 <LINK REL="up" HREF="ionnotes.html">
  25 <LINK REL="next" HREF="node5.html">
  26 </HEAD>
  27
  28 <BODY >
  29
  30 <DIV CLASS="navigation"><!--Navigation Panel-->
  31 <A NAME="tex2html115"
  32   HREF="node5.html">
  33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
  34 <A NAME="tex2html109"
  35   HREF="ionnotes.html">
  36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
  37 <A NAME="tex2html103"
  38   HREF="node3.html">
  39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
  40 <A NAME="tex2html111"
  41   HREF="node1.html">
  42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
  43 <A NAME="tex2html113"
  44   HREF="node8.html">
  45 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
  46 <BR>
  47 <B> Next:</B> <A NAME="tex2html116"
  48   HREF="node5.html">4 Miscellaneous design notes</A>
  49 <B> Up:</B> <A NAME="tex2html110"
  50   HREF="ionnotes.html">Ion: Notes for the</A>
  51 <B> Previous:</B> <A NAME="tex2html104"
  52   HREF="node3.html">2 Object system implementation</A>
  53  &nbsp; <B>  <A NAME="tex2html112"
  54   HREF="node1.html">Contents</A></B>
  55  &nbsp; <B>  <A NAME="tex2html114"
  56   HREF="node8.html">Index</A></B>
  57 <BR>
  58 <BR></DIV>
  59 <!--End of Navigation Panel-->
  60 <!--Table of Child-Links-->
  61 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
  62
  63 <UL CLASS="ChildLinks">
  64 <LI><A NAME="tex2html117"
  65   HREF="node4.html#SECTION00041000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Supported types</A>
  66 <LI><A NAME="tex2html118"
  67   HREF="node4.html#SECTION00042000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Exporting functions</A>
  68 <LI><A NAME="tex2html119"
  69   HREF="node4.html#SECTION00043000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Calling Lua functions and code</A>
  70 <LI><A NAME="tex2html120"
  71   HREF="node4.html#SECTION00044000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Miscellaneous notes</A>
  72 </UL>
  73 <!--End of Table of Child-Links-->
  74 <HR>
  75
  76 <H1><A NAME="SECTION00040000000000000000">
  77 <SPAN CLASS="arabic">3</SPAN> The Lua interface</A>
  78 </H1>
  79
  80 <P>
  81 This section finally describes the implementation details and how modules
  82 should us the Lua interface. First, in section <A HREF="#sec:supptypes">3.1</A>
  83 we look at types supported by the interface, how objects are passed to Lua
  84 code and how Lua tables should be accessed from Ion and modules. In section
  85 <A HREF="#sec:exporting">3.2</A> the methods for exporting functions and how they
  86 are called from Lua are explained and in section <A HREF="#sec:calling">3.3</A> the
  87 method for calling Lua functions is explained.
  88
  89 <P>
  90
  91 <H2><A NAME="SECTION00041000000000000000"></A>
  92 <A NAME="sec:supptypes"></A>
  93 <BR>
  94 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Supported types
  95 </H2>
  96
  97 <P>
  98 The following types are supported in passing parameters between the
  99 C side of Ion and Lua:
 100
 101 <P>
 102 <TABLE CELLPADDING=3 BORDER="1">
 103 <TR><TD ALIGN="RIGHT">Identifier
 104  character</TD>
 105 <TD ALIGN="LEFT">C type</TD>
 106 <TD ALIGN="LEFT">Description</TD>
 107 </TR>
 108 <TR><TD ALIGN="RIGHT">i</TD>
 109 <TD ALIGN="LEFT">int</TD>
 110 <TD ALIGN="LEFT">Integer</TD>
 111 </TR>
 112 <TR><TD ALIGN="RIGHT">s</TD>
 113 <TD ALIGN="LEFT">char*</TD>
 114 <TD ALIGN="LEFT">String</TD>
 115 </TR>
 116 <TR><TD ALIGN="RIGHT">S</TD>
 117 <TD ALIGN="LEFT">const char*</TD>
 118 <TD ALIGN="LEFT">Constant string</TD>
 119 </TR>
 120 <TR><TD ALIGN="RIGHT">d</TD>
 121 <TD ALIGN="LEFT">double</TD>
 122 <TD ALIGN="LEFT">&nbsp;</TD>
 123 </TR>
 124 <TR><TD ALIGN="RIGHT">b</TD>
 125 <TD ALIGN="LEFT">bool</TD>
 126 <TD ALIGN="LEFT">&nbsp;</TD>
 127 </TR>
 128 <TR><TD ALIGN="RIGHT">t</TD>
 129 <TD ALIGN="LEFT">ExtlTab<A NAME="521"></A></TD>
 130 <TD ALIGN="LEFT">Reference to Lua table</TD>
 131 </TR>
 132 <TR><TD ALIGN="RIGHT">f</TD>
 133 <TD ALIGN="LEFT">ExltFn<A NAME="522"></A></TD>
 134 <TD ALIGN="LEFT">Reference to Lua function.</TD>
 135 </TR>
 136 <TR><TD ALIGN="RIGHT">o</TD>
 137 <TD ALIGN="LEFT">Any WObj*</TD>
 138 <TD ALIGN="LEFT">&nbsp;</TD>
 139 </TR>
 140 </TABLE>
 141
 142 <P>
 143 The difference between identifiers 's' and 'S' is that constant
 144 strings as return values are not free'd by the level 1 call handler
 145 (see below) after passing to Lua (<TT>lua_pushstring</TT> always makes a
 146 copy) unlike normal strings. String parameters are always assumed to be
 147 the property of the caller and thus implicitly const.
 148
 149 <P>
 150 Likewise, if a reference to 't' or 'f' is wished to be stored
 151 beyond the lifetime of a function receiving such as an argument, a new
 152 reference should be created with <TT>extl_ref_table</TT>/<TT>fn</TT>.
 153 References can be free'd with
 154 <TT>extl_unref_table</TT>/<TT>fn</TT>. References gotten as return values with
 155 the <TT>extl_table_get</TT> (how these work should be self-explanatory!)
 156 functions are property of the caller and should be unreferenced with the
 157 above-mentioned functions when no longer needed.
 158 The functions <TT>extl_fn</TT>/<TT>table_none()</TT>
 159 return the equivalent of NULL.
 160
 161 <P>
 162 WObjs are passed to Lua code with WWatch userdatas pointing to
 163 them so the objects can be safely deleted although Lua code might still be
 164 referencing them. (This is why SWIG or tolua would not have helped in
 165 creating the interface: extra wrappers for each function would still
 166 have been needed to nicely integrate into Ion's object system. Even in
 167 the case that Ion was written in C++ this would be so unless extra bloat
 168 adding pointer-like objects were used everywhere instead of pointers.)
 169 It may be sometimes necessary check in Lua code that a value known to
 170 be an Ion WObj is of certain type. This can be accomplished with
 171 <TT>obj_is(obj, "typename")</TT>. <TT>obj_typename(obj)</TT> returns type
 172 name for a WObj.
 173
 174 <P>
 175
 176 <H2><A NAME="SECTION00042000000000000000"></A>
 177 <A NAME="sec:exporting"></A>
 178 <BR>
 179 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Exporting functions
 180 </H2>
 181
 182 <P>
 183 Exported functions (those available to the extension language) are
 184 defined by placing <TT>EXTL_EXPORT</TT> before the function implementation
 185 in the C source. The script mkexports.pl is then used to automatically
 186 generate <SPAN  CLASS="textit">exports.c</SPAN> from the source files if
 187 <TT>MAKE_EXPORTS=modulename</TT>
 188 is specified in the Makefile. All pointers with type beginning with a 'W'
 189 are assumed to be pointers to something inheriting WObj. In
 190 addition to a table of exported functions and second level call handlers
 191 for these, <SPAN  CLASS="textit">exports.c</SPAN> will contain two functions
 192 <TT>module_register_exports()</TT> and
 193 <TT>module_unregister_exports()</TT> that should then be called in module
 194 initialisation and deinitialisation code.
 195
 196 <P>
 197 You've seen the terms level 1 and 2 call handler mentioned above.
 198 <A NAME="491"></A>
 199 The Lua support code uses two so called call handlers to convert and check
 200 the types of parameters passed from Lua to C and back to Lua. The first
 201 one of these call handlers is the same for all exported functions and
 202 indeed lua sees all exported as the same C function (the L1 call handler)
 203 but with different upvalues passing a structure describing the actual
 204 function and the second level call handler. The L1 call handler checks
 205 that the parameters received from Lua match a template given as a string
 206 of the identifier characters defined above. If everything checks out ok,
 207 the parameters are then put in an array of C unions that can contain
 208 anyof these known types and the L2 call handler is called.
 209
 210 <P>
 211 The L2 call handler (which is automatically generated by the mkexports.pl
 212 script) for each exported function checks that the passed WObjs
 213 are of the more refined type required by the function and then calls the
 214 actual function. While the WObj checking could be done in the L1 handler
 215 too, the L2 call handlers are needed because we may not know how the target
 216 platform passes each parameter type to the called function. Thefore we
 217 must let the C compiler generate the code to convert from a simple and
 218 known enough parameter passing method (the unions) to the actual
 219 parameter passing method. When the called function returns everything
 220 is done in reverse order for return values (only one return value is
 221 supported by the generated L2 call handlers).
 222
 223 <P>
 224
 225 <H2><A NAME="SECTION00043000000000000000"></A>
 226 <A NAME="sec:calling"></A>
 227 <BR>
 228 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Calling Lua functions and code
 229 </H2>
 230
 231 <P>
 232 The functions
 233 <TT>extl_call</TT><A NAME="515"></A>,
 234 <TT>extl_call_named</TT><A NAME="516"></A>,
 235 <TT>extl_dofile</TT><A NAME="517"></A> and
 236 <TT>extl_dostring</TT><A NAME="518"></A>
 237 call a referenced function (ExtlFn), named function, execute a
 238 string and a file, respectively. The rest of the parameters for all these
 239 functions are similar. The 'spec' argument is a string of identifier
 240 characters (see above) describing the parameters to be passed. These
 241 parameters follow after 'rspec'. For dofile and dostring these parameters
 242 are passed in the global table arg (same as used for program command
 243 lien parameters) and for functions as you might expect. The parameter
 244 'rspec' is a similar description of return values. Pointers to variables
 245 that should be set to the return values follow after the input values.
 246 The return value of all these functions tells if the call and parameter
 247 passing succeeded or not.
 248
 249 <P>
 250 Sometimes it is necessary to block calls to all but a limited set of
 251 Ion functions. This can be accomplished with
 252 <TT>extl_set_safelist</TT><A NAME="519"></A>.
 253 The parameter to this function is a NULL-terminated array of strings
 254 and the return value is a similar old safelist.
 255 The call <TT>extl_set_safelist(NULL)</TT> removes any safelist and allows
 256 calls to all exported functions.
 257
 258 <P>
 259
 260 <H2><A NAME="SECTION00044000000000000000">
 261 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Miscellaneous notes</A>
 262 </H2>
 263
 264 <P>
 265 Configuration files should be read as before with the function
 266 <TT>read_config_for</TT><A NAME="520"></A>
 267 except that the list of known options is no longer present.
 268
 269 <P>
 270 Winprops are now stored in Lua tables and can contain arbitrary
 271 properties. The 'proptab' entry in each WClientWin is a reference
 272 to a winprop table or <TT>extl_table_none()</TT> if such does not exist
 273 and properties may be read with the <TT>extl_table_gets</TT> functions.
 274 (It is perfectly legal to pass <TT>extl_table_none()</TT> references to
 275 <TT>extl_table_get*</TT>.)
 276
 277 <P>
 278
 279 <DIV CLASS="navigation"><HR>
 280 <!--Navigation Panel-->
 281 <A NAME="tex2html115"
 282   HREF="node5.html">
 283 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
 284 <A NAME="tex2html109"
 285   HREF="ionnotes.html">
 286 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
 287 <A NAME="tex2html103"
 288   HREF="node3.html">
 289 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
 290 <A NAME="tex2html111"
 291   HREF="node1.html">
 292 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
 293 <A NAME="tex2html113"
 294   HREF="node8.html">
 295 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
 296 <BR>
 297 <B> Next:</B> <A NAME="tex2html116"
 298   HREF="node5.html">4 Miscellaneous design notes</A>
 299 <B> Up:</B> <A NAME="tex2html110"
 300   HREF="ionnotes.html">Ion: Notes for the</A>
 301 <B> Previous:</B> <A NAME="tex2html104"
 302   HREF="node3.html">2 Object system implementation</A>
 303  &nbsp; <B>  <A NAME="tex2html112"
 304   HREF="node1.html">Contents</A></B>
 305  &nbsp; <B>  <A NAME="tex2html114"
 306   HREF="node8.html">Index</A></B> </DIV>
 307 <!--End of Navigation Panel-->
 308
 309 </BODY>
 310 </HTML>