aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMike Pall <mike>2011-02-11 13:50:01 +0100
committerMike Pall <mike>2011-02-11 14:51:20 +0100
commit1f0006ac71fd4eb308ab900b0b9917e1dd046680 (patch)
tree93a6e6435ef45c776c28da2d3f4c8330e0e72968
parenta5aade2fa9ff89f9f3c4a91261071299de0d0fa4 (diff)
downloadluajit-1f0006ac71fd4eb308ab900b0b9917e1dd046680.tar.gz
luajit-1f0006ac71fd4eb308ab900b0b9917e1dd046680.tar.bz2
luajit-1f0006ac71fd4eb308ab900b0b9917e1dd046680.zip
Cleanup of docs.
-rw-r--r--doc/changes.html2
-rw-r--r--doc/ext_ffi.html79
-rw-r--r--doc/ext_ffi_api.html4
-rw-r--r--doc/ext_ffi_semantics.html23
-rw-r--r--doc/ext_ffi_tutorial.html111
-rw-r--r--doc/install.html4
-rw-r--r--doc/luajit.html2
-rw-r--r--doc/status.html7
8 files changed, 157 insertions, 75 deletions
diff --git a/doc/changes.html b/doc/changes.html
index 04e26e40..88d54cc2 100644
--- a/doc/changes.html
+++ b/doc/changes.html
@@ -256,7 +256,7 @@ to avoid joining by the compiler/linker.</li>
256<li>Merged with Lua 5.1.1. Fixes all 256<li>Merged with Lua 5.1.1. Fixes all
257<a href="http://www.lua.org/bugs.html#5.1"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1</a>.</li> 257<a href="http://www.lua.org/bugs.html#5.1"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1</a>.</li>
258<li>Enforce (dynamic) linker error for EXE/DLL version mismatches.</li> 258<li>Enforce (dynamic) linker error for EXE/DLL version mismatches.</li>
259<li>Minor changes to DynASM: faster preprocessing, smaller encoding 259<li>Minor changes to DynASM: faster pre-processing, smaller encoding
260for some immediates.</li> 260for some immediates.</li>
261</ul> 261</ul>
262<p> 262<p>
diff --git a/doc/ext_ffi.html b/doc/ext_ffi.html
index 1fd276dc..0bbf7606 100644
--- a/doc/ext_ffi.html
+++ b/doc/ext_ffi.html
@@ -8,6 +8,12 @@
8<meta name="Language" content="en"> 8<meta name="Language" content="en">
9<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 9<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
10<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> 10<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
11<style type="text/css">
12span.codemark { position:absolute; left: 16em; color: #4040c0; }
13span.mark { color: #4040c0; font-family: Courier New, Courier, monospace;
14 line-height: 1.1; }
15pre.mark { padding-left: 2em; }
16</style>
11</head> 17</head>
12<body> 18<body>
13<div id="site"> 19<div id="site">
@@ -55,16 +61,20 @@
55</div> 61</div>
56<div id="main"> 62<div id="main">
57<p> 63<p>
58The FFI library allows calling external C&nbsp;functions and the use 64
59of C&nbsp;data structures from pure Lua code. 65The FFI library allows <b>calling external C&nbsp;functions</b> and
66<b>using C&nbsp;data structures</b> from pure Lua code.
67
60</p> 68</p>
61<p> 69<p>
70
62The FFI library largely obviates the need to write tedious manual 71The FFI library largely obviates the need to write tedious manual
63Lua/C bindings in C. It doesn't require learning a separate binding 72Lua/C bindings in C. No need to learn a separate binding language
64language &mdash; it parses plain C&nbsp;declarations, which can be 73&mdash; <b>it parses plain C&nbsp;declarations!</b> These can be
65cut-n-pasted from C&nbsp;header files or reference manuals. It's up to 74cut-n-pasted from C&nbsp;header files or reference manuals. It's up to
66the task of binding large libraries without the need for dealing with 75the task of binding large libraries without the need for dealing with
67fragile binding generators. 76fragile binding generators.
77
68</p> 78</p>
69<p> 79<p>
70The FFI library is tightly integrated into LuaJIT (it's not available 80The FFI library is tightly integrated into LuaJIT (it's not available
@@ -83,26 +93,30 @@ Please use the FFI sub-topics in the navigation bar to learn more.
83<p> 93<p>
84It's really easy to call an external C&nbsp;library function: 94It's really easy to call an external C&nbsp;library function:
85</p> 95</p>
86<pre class="code"> 96<pre class="code mark">
87local ffi = require("ffi") <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9312;</span> 97<span class="codemark">&#9312;
88ffi.cdef[[ <span style="color:#f0f4ff;">//</span><span style="color:#4040c0;">&#9313;</span> 98&#9313;
99
100
101&#9314;</span>local ffi = require("ffi")
102ffi.cdef[[
89<span style="color:#00a000;">int printf(const char *fmt, ...);</span> 103<span style="color:#00a000;">int printf(const char *fmt, ...);</span>
90]] 104]]
91ffi.C.printf("Hello %s!", "world") <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9314;</span> 105ffi.C.printf("Hello %s!", "world")
92</pre> 106</pre>
93<p> 107<p>
94So, let's pick that apart: 108So, let's pick that apart:
95</p> 109</p>
96<p> 110<p>
97<span style="color:#4040c0;">&#9312;</span> Load the FFI library. 111<span class="mark">&#9312;</span> Load the FFI library.
98</p> 112</p>
99<p> 113<p>
100<span style="color:#4040c0;">&#9313;</span> Add a C&nbsp;declaration 114<span class="mark">&#9313;</span> Add a C&nbsp;declaration
101for the function. The part inside the double-brackets (in green) is 115for the function. The part inside the double-brackets (in green) is
102just standard C&nbsp;syntax. 116just standard C&nbsp;syntax.
103</p> 117</p>
104<p> 118<p>
105<span style="color:#4040c0;">&#9314;</span> Call the named 119<span class="mark">&#9314;</span> Call the named
106C&nbsp;function &mdash; Yes, it's that simple! 120C&nbsp;function &mdash; Yes, it's that simple!
107</p> 121</p>
108<p style="font-size: 8pt;"> 122<p style="font-size: 8pt;">
@@ -198,25 +212,42 @@ need of a simple example ...
198And here's the FFI version. The modified parts have been marked in 212And here's the FFI version. The modified parts have been marked in
199bold: 213bold:
200</p> 214</p>
201<pre class="code"> 215<pre class="code mark">
202<b>local ffi = require("ffi")</b> <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9312;</span> 216<span class="codemark">&#9312;
203<b>ffi.cdef[[ 217
218
219
220
221
222&#9313;
223
224&#9314;
225&#9315;
226
227
228
229
230
231
232&#9314;
233&#9316;</span><b>local ffi = require("ffi")
234ffi.cdef[[
204</b><span style="color:#00a000;">typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel;</span><b> 235</b><span style="color:#00a000;">typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel;</span><b>
205]]</b> 236]]</b>
206 237
207local function image_ramp_green(n) 238local function image_ramp_green(n)
208 <b>local img = ffi.new("rgba_pixel[?]", n)</b> <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9313;</span> 239 <b>local img = ffi.new("rgba_pixel[?]", n)</b>
209 local f = 255/(n-1) 240 local f = 255/(n-1)
210 for i=<b>0,n-1</b> do <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9314;</span> 241 for i=<b>0,n-1</b> do
211 <b>img[i].green = i*f</b> <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9315;</span> 242 <b>img[i].green = i*f</b>
212 <b>img[i].alpha = 255</b> 243 <b>img[i].alpha = 255</b>
213 end 244 end
214 return img 245 return img
215end 246end
216 247
217local function image_to_grey(img, n) 248local function image_to_grey(img, n)
218 for i=<b>0,n-1</b> do <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9314;</span> 249 for i=<b>0,n-1</b> do
219 local y = <b>0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue</b> <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9316;</span> 250 local y = <b>0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue</b>
220 img[i].red = y; img[i].green = y; img[i].blue = y 251 img[i].red = y; img[i].green = y; img[i].blue = y
221 end 252 end
222end 253end
@@ -231,30 +262,30 @@ end
231Ok, so that wasn't too difficult: 262Ok, so that wasn't too difficult:
232</p> 263</p>
233<p> 264<p>
234<span style="color:#4040c0;">&#9312;</span> First, load the FFI 265<span class="mark">&#9312;</span> First, load the FFI
235library and declare the low-level data type. Here we choose a 266library and declare the low-level data type. Here we choose a
236<tt>struct</tt> which holds four byte fields, one for each component 267<tt>struct</tt> which holds four byte fields, one for each component
237of a 4x8&nbsp;bit RGBA pixel. 268of a 4x8&nbsp;bit RGBA pixel.
238</p> 269</p>
239<p> 270<p>
240<span style="color:#4040c0;">&#9313;</span> Creating the data 271<span class="mark">&#9313;</span> Creating the data
241structure with <tt>ffi.new()</tt> is straightforward &mdash; the 272structure with <tt>ffi.new()</tt> is straightforward &mdash; the
242<tt>'?'</tt> is a placeholder for the number of elements of a 273<tt>'?'</tt> is a placeholder for the number of elements of a
243variable-length array. 274variable-length array.
244</p> 275</p>
245<p> 276<p>
246<span style="color:#4040c0;">&#9314;</span> C&nbsp;arrays are 277<span class="mark">&#9314;</span> C&nbsp;arrays are
247zero-based, so the indexes have to run from <tt>0</tt> to 278zero-based, so the indexes have to run from <tt>0</tt> to
248<tt>n-1</tt>. One might want to allocate one more element instead to 279<tt>n-1</tt>. One might want to allocate one more element instead to
249simplify converting legacy code. 280simplify converting legacy code.
250</p> 281</p>
251<p> 282<p>
252<span style="color:#4040c0;">&#9315;</span> Since <tt>ffi.new()</tt> 283<span class="mark">&#9315;</span> Since <tt>ffi.new()</tt>
253zero-fills the array by default, we only need to set the green and the 284zero-fills the array by default, we only need to set the green and the
254alpha fields. 285alpha fields.
255</p> 286</p>
256<p> 287<p>
257<span style="color:#4040c0;">&#9316;</span> The calls to 288<span class="mark">&#9316;</span> The calls to
258<tt>math.floor()</tt> can be omitted here, because floating-point 289<tt>math.floor()</tt> can be omitted here, because floating-point
259numbers are already truncated towards zero when converting them to an 290numbers are already truncated towards zero when converting them to an
260integer. This happens implicitly when the number is stored in the 291integer. This happens implicitly when the number is stored in the
diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html
index 9bedd52e..b8c52fb6 100644
--- a/doc/ext_ffi_api.html
+++ b/doc/ext_ffi_api.html
@@ -316,7 +316,7 @@ bytes of the string <em>plus a zero-terminator</em> are copied to
316</p> 316</p>
317<p> 317<p>
318Performance notice: <tt>ffi.copy()</tt> may be used as a faster 318Performance notice: <tt>ffi.copy()</tt> may be used as a faster
319(inlineable) replacement for the C&nbsp;library functions 319(inlinable) replacement for the C&nbsp;library functions
320<tt>memcpy()</tt>, <tt>strcpy()</tt> and <tt>strncpy()</tt>. 320<tt>memcpy()</tt>, <tt>strcpy()</tt> and <tt>strncpy()</tt>.
321</p> 321</p>
322 322
@@ -328,7 +328,7 @@ zero-filled.
328</p> 328</p>
329<p> 329<p>
330Performance notice: <tt>ffi.fill()</tt> may be used as a faster 330Performance notice: <tt>ffi.fill()</tt> may be used as a faster
331(inlineable) replacement for the C&nbsp;library function 331(inlinable) replacement for the C&nbsp;library function
332<tt>memset(dst,&nbsp;c,&nbsp;len)</tt>. Please note the different 332<tt>memset(dst,&nbsp;c,&nbsp;len)</tt>. Please note the different
333order of arguments! 333order of arguments!
334</p> 334</p>
diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
index 69dfc2ca..8c7bd478 100644
--- a/doc/ext_ffi_semantics.html
+++ b/doc/ext_ffi_semantics.html
@@ -66,9 +66,9 @@ and its interaction with both Lua and C&nbsp;code.
66</p> 66</p>
67<p> 67<p>
68Given that the FFI library is designed to interface with C&nbsp;code 68Given that the FFI library is designed to interface with C&nbsp;code
69and that declarations can be written in plain C&nbsp;syntax, it 69and that declarations can be written in plain C&nbsp;syntax, <b>it
70closely follows the C&nbsp;language semantics, wherever possible. Some 70closely follows the C&nbsp;language semantics</b>, wherever possible.
71minor concessions are needed for smoother interoperation with Lua 71Some minor concessions are needed for smoother interoperation with Lua
72language semantics. 72language semantics.
73</p> 73</p>
74<p> 74<p>
@@ -83,9 +83,8 @@ background.
83Please note: this is the first public release of the FFI library. This 83Please note: this is the first public release of the FFI library. This
84does not comprise the final specification for the FFI semantics, yet. 84does not comprise the final specification for the FFI semantics, yet.
85Some of the semantics may need to be changed, based on feedback from 85Some of the semantics may need to be changed, based on feedback from
86developers. Please <a href="contact.html">report</a> any problems 86developers. Please <a href="contact.html">report</a> any problems you
87you've encountered or any improvements you'd like to see &mdash; thank 87may encounter or any improvements you'd like to see &mdash; thank you!
88you!
89</p> 88</p>
90 89
91<h2 id="clang">C Language Support</h2> 90<h2 id="clang">C Language Support</h2>
@@ -204,7 +203,7 @@ The following C&nbsp;features are <b>not</b> supported:
204default to an <tt>int</tt> type.</li> 203default to an <tt>int</tt> type.</li>
205 204
206<li>Old-style empty function declarations (K&amp;R) are not allowed. 205<li>Old-style empty function declarations (K&amp;R) are not allowed.
207All C&nbsp;functions must have a proper protype declaration. A 206All C&nbsp;functions must have a proper prototype declaration. A
208function declared without parameters (<tt>int&nbsp;foo();</tt>) is 207function declared without parameters (<tt>int&nbsp;foo();</tt>) is
209treated as a function taking zero arguments, like in C++.</li> 208treated as a function taking zero arguments, like in C++.</li>
210 209
@@ -312,7 +311,7 @@ C&nbsp;type of the destination, the
312are applied. 311are applied.
313</p> 312</p>
314<p> 313<p>
315Reference types are immutable after initialization ("no reseating of 314Reference types are immutable after initialization ("no re-seating of
316references"). For initialization purposes or when passing values to 315references"). For initialization purposes or when passing values to
317reference parameters, they are treated like pointers. Note that unlike 316reference parameters, they are treated like pointers. Note that unlike
318in C++, there's no way to implement automatic reference generation of 317in C++, there's no way to implement automatic reference generation of
@@ -652,8 +651,8 @@ variable argument part of vararg C&nbsp;function use
652<a href="#convert_vararg">special conversion rules</a>. This 651<a href="#convert_vararg">special conversion rules</a>. This
653C&nbsp;function is called and the return value (if any) is 652C&nbsp;function is called and the return value (if any) is
654<a href="#convert_tolua">converted to a Lua object</a>.<br> 653<a href="#convert_tolua">converted to a Lua object</a>.<br>
655On Windows/x86 systems, <tt>stdcall</tt> functions are automatically 654On Windows/x86 systems, <tt>__stdcall</tt> functions are automatically
656detected and a function declared as <tt>cdecl</tt> (the default) is 655detected and a function declared as <tt>__cdecl</tt> (the default) is
657silently fixed up after the first call.</li> 656silently fixed up after the first call.</li>
658 657
659</ul> 658</ul>
@@ -790,7 +789,7 @@ local s = ffi.new("foo_t", a)
790Similar rules apply for Lua strings which are implicitly converted to 789Similar rules apply for Lua strings which are implicitly converted to
791<tt>"const&nbsp;char&nbsp;*"</tt>: the string object itself must be 790<tt>"const&nbsp;char&nbsp;*"</tt>: the string object itself must be
792referenced somewhere or it'll be garbage collected eventually. The 791referenced somewhere or it'll be garbage collected eventually. The
793pointer will then point to stale data, which may have already beeen 792pointer will then point to stale data, which may have already been
794overwritten. Note that <em>string literals</em> are automatically kept 793overwritten. Note that <em>string literals</em> are automatically kept
795alive as long as the function containing it (actually its prototype) 794alive as long as the function containing it (actually its prototype)
796is not garbage collected. 795is not garbage collected.
@@ -951,7 +950,7 @@ storing and initializing them are supported, yet.</li>
951<li>The <tt>volatile</tt> type qualifier is currently ignored by 950<li>The <tt>volatile</tt> type qualifier is currently ignored by
952compiled code.</li> 951compiled code.</li>
953<li><a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> silently 952<li><a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> silently
954ignores all redeclarations.</li> 953ignores all re-declarations.</li>
955</ul> 954</ul>
956<p> 955<p>
957The JIT compiler already handles a large subset of all FFI operations. 956The JIT compiler already handles a large subset of all FFI operations.
diff --git a/doc/ext_ffi_tutorial.html b/doc/ext_ffi_tutorial.html
index c43b223b..38126865 100644
--- a/doc/ext_ffi_tutorial.html
+++ b/doc/ext_ffi_tutorial.html
@@ -9,7 +9,12 @@
9<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 9<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
10<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> 10<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
11<style type="text/css"> 11<style type="text/css">
12span.codemark { position:absolute; left: 16em; color: #4040c0; }
13span.mark { color: #4040c0; font-family: Courier New, Courier, monospace;
14 line-height: 1.1; }
15pre.mark { padding-left: 2em; }
12table.idiomtable { line-height: 1.2; } 16table.idiomtable { line-height: 1.2; }
17table.idiomtable tt { font-size: 100%; }
13tr.idiomhead td { font-weight: bold; } 18tr.idiomhead td { font-weight: bold; }
14td.idiomc { width: 12em; } 19td.idiomc { width: 12em; }
15td.idiomlua { width: 14em; } 20td.idiomlua { width: 14em; }
@@ -94,27 +99,46 @@ The following code explains how to access standard system functions.
94We slowly print two lines of dots by sleeping for 10&nbsp;milliseconds 99We slowly print two lines of dots by sleeping for 10&nbsp;milliseconds
95after each dot: 100after each dot:
96</p> 101</p>
97<pre class="code"> 102<pre class="code mark">
98local ffi = require("ffi") 103<span class="codemark">&nbsp;
99ffi.cdef[[ <span style="color:#f0f4ff;">//</span><span style="color:#4040c0;">&#9312;</span> 104&#9312;
105
106
107
108
109
110&#9313;
111&#9314;
112&#9315;
113
114
115
116&#9316;
117
118
119
120
121
122&#9317;</span>local ffi = require("ffi")
123ffi.cdef[[
100<span style="color:#00a000;">void Sleep(int ms); 124<span style="color:#00a000;">void Sleep(int ms);
101int poll(struct pollfd *fds, unsigned long nfds, int timeout);</span> 125int poll(struct pollfd *fds, unsigned long nfds, int timeout);</span>
102]] 126]]
103 127
104local sleep 128local sleep
105if ffi.os == "Windows" then <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9313;</span> 129if ffi.os == "Windows" then
106 function sleep(s) <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9314;</span> 130 function sleep(s)
107 ffi.C.Sleep(s*1000) <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9315;</span> 131 ffi.C.Sleep(s*1000)
108 end 132 end
109else 133else
110 function sleep(s) 134 function sleep(s)
111 ffi.C.poll(nil, 0, s*1000) <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9316;</span> 135 ffi.C.poll(nil, 0, s*1000)
112 end 136 end
113end 137end
114 138
115for i=1,160 do 139for i=1,160 do
116 io.write("."); io.flush() 140 io.write("."); io.flush()
117 sleep(0.01) <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9317;</span> 141 sleep(0.01)
118end 142end
119io.write("\n") 143io.write("\n")
120</pre> 144</pre>
@@ -122,14 +146,14 @@ io.write("\n")
122Here's the step-by-step explanation: 146Here's the step-by-step explanation:
123</p> 147</p>
124<p> 148<p>
125<span style="color:#4040c0;">&#9312;</span> This defines the 149<span class="mark">&#9312;</span> This defines the
126C&nbsp;library functions we're going to use. The part inside the 150C&nbsp;library functions we're going to use. The part inside the
127double-brackets (in green) is just standard C&nbsp;syntax. You can 151double-brackets (in green) is just standard C&nbsp;syntax. You can
128usually get this info from the C&nbsp;header files or the 152usually get this info from the C&nbsp;header files or the
129documentation provided by each C&nbsp;library or C&nbsp;compiler. 153documentation provided by each C&nbsp;library or C&nbsp;compiler.
130</p> 154</p>
131<p> 155<p>
132<span style="color:#4040c0;">&#9313;</span> The difficulty we're 156<span class="mark">&#9313;</span> The difficulty we're
133facing here, is that there are different standards to choose from. 157facing here, is that there are different standards to choose from.
134Windows has a simple <tt>Sleep()</tt> function. On other systems there 158Windows has a simple <tt>Sleep()</tt> function. On other systems there
135are a variety of functions available to achieve sub-second sleeps, but 159are a variety of functions available to achieve sub-second sleeps, but
@@ -139,14 +163,14 @@ check for <tt>ffi.os</tt> makes sure we use the Windows-specific
139function only on Windows systems. 163function only on Windows systems.
140</p> 164</p>
141<p> 165<p>
142<span style="color:#4040c0;">&#9314;</span> Here we're wrapping the 166<span class="mark">&#9314;</span> Here we're wrapping the
143call to the C&nbsp;function in a Lua function. This isn't strictly 167call to the C&nbsp;function in a Lua function. This isn't strictly
144necessary, but it's helpful to deal with system-specific issues only 168necessary, but it's helpful to deal with system-specific issues only
145in one part of the code. The way we're wrapping it ensures the check 169in one part of the code. The way we're wrapping it ensures the check
146for the OS is only done during initialization and not for every call. 170for the OS is only done during initialization and not for every call.
147</p> 171</p>
148<p> 172<p>
149<span style="color:#4040c0;">&#9315;</span> A more subtle point is 173<span class="mark">&#9315;</span> A more subtle point is
150that we defined our <tt>sleep()</tt> function (for the sake of this 174that we defined our <tt>sleep()</tt> function (for the sake of this
151example) as taking the number of seconds, but accepting fractional 175example) as taking the number of seconds, but accepting fractional
152seconds. Multiplying this by 1000 gets us milliseconds, but that still 176seconds. Multiplying this by 1000 gets us milliseconds, but that still
@@ -165,7 +189,7 @@ FFI library automatically detects <tt>stdcall</tt> functions, so you
165don't need to declare them as such. 189don't need to declare them as such.
166</p> 190</p>
167<p> 191<p>
168<span style="color:#4040c0;">&#9316;</span> The <tt>poll()</tt> 192<span class="mark">&#9316;</span> The <tt>poll()</tt>
169function takes a couple more arguments we're not going to use. You can 193function takes a couple more arguments we're not going to use. You can
170simply use <tt>nil</tt> to pass a <tt>NULL</tt> pointer and <tt>0</tt> 194simply use <tt>nil</tt> to pass a <tt>NULL</tt> pointer and <tt>0</tt>
171for the <tt>nfds</tt> parameter. Please note that the 195for the <tt>nfds</tt> parameter. Please note that the
@@ -182,7 +206,7 @@ with this, as it's performed automatically and it's carefully designed
182to bridge the semantic differences between Lua and C. 206to bridge the semantic differences between Lua and C.
183</p> 207</p>
184<p> 208<p>
185<span style="color:#4040c0;">&#9317;</span> Now that we have defined 209<span class="mark">&#9317;</span> Now that we have defined
186our own <tt>sleep()</tt> function, we can just call it from plain Lua 210our own <tt>sleep()</tt> function, we can just call it from plain Lua
187code. That wasn't so bad, huh? Turning these boring animated dots into 211code. That wasn't so bad, huh? Turning these boring animated dots into
188a fascinating best-selling game is left as an exercise for the reader. 212a fascinating best-selling game is left as an exercise for the reader.
@@ -196,27 +220,54 @@ href="http://zlib.net/">zlib</a> compression library from Lua code.
196We'll define two convenience wrapper functions that take a string and 220We'll define two convenience wrapper functions that take a string and
197compress or uncompress it to another string: 221compress or uncompress it to another string:
198</p> 222</p>
199<pre class="code"> 223<pre class="code mark">
200local ffi = require("ffi") 224<span class="codemark">&nbsp;
201ffi.cdef[[ <span style="color:#f0f4ff;">//</span><span style="color:#4040c0;">&#9312;</span> 225&#9312;
226
227
228
229
230
231
232&#9313;
233
234
235&#9314;
236
237&#9315;
238
239
240&#9316;
241
242
243&#9317;
244
245
246
247
248
249
250
251&#9318;</span>local ffi = require("ffi")
252ffi.cdef[[
202<span style="color:#00a000;">unsigned long compressBound(unsigned long sourceLen); 253<span style="color:#00a000;">unsigned long compressBound(unsigned long sourceLen);
203int compress2(uint8_t *dest, unsigned long *destLen, 254int compress2(uint8_t *dest, unsigned long *destLen,
204 const uint8_t *source, unsigned long sourceLen, int level); 255 const uint8_t *source, unsigned long sourceLen, int level);
205int uncompress(uint8_t *dest, unsigned long *destLen, 256int uncompress(uint8_t *dest, unsigned long *destLen,
206 const uint8_t *source, unsigned long sourceLen);</span> 257 const uint8_t *source, unsigned long sourceLen);</span>
207]] 258]]
208local zlib = ffi.load(ffi.os == "Windows" and "zlib1" or "z") <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9313;</span> 259local zlib = ffi.load(ffi.os == "Windows" and "zlib1" or "z")
209 260
210local function compress(txt) 261local function compress(txt)
211 local n = zlib.compressBound(#txt) <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9314;</span> 262 local n = zlib.compressBound(#txt)
212 local buf = ffi.new("uint8_t[?]", n) 263 local buf = ffi.new("uint8_t[?]", n)
213 local buflen = ffi.new("unsigned long[1]", n) <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9315;</span> 264 local buflen = ffi.new("unsigned long[1]", n)
214 local res = zlib.compress2(buf, buflen, txt, #txt, 9) 265 local res = zlib.compress2(buf, buflen, txt, #txt, 9)
215 assert(res == 0) 266 assert(res == 0)
216 return ffi.string(buf, buflen[0]) <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9316;</span> 267 return ffi.string(buf, buflen[0])
217end 268end
218 269
219local function uncompress(comp, n) <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9317;</span> 270local function uncompress(comp, n)
220 local buf = ffi.new("uint8_t[?]", n) 271 local buf = ffi.new("uint8_t[?]", n)
221 local buflen = ffi.new("unsigned long[1]", n) 272 local buflen = ffi.new("unsigned long[1]", n)
222 local res = zlib.uncompress(buf, buflen, comp, #comp) 273 local res = zlib.uncompress(buf, buflen, comp, #comp)
@@ -224,7 +275,7 @@ local function uncompress(comp, n) <span style="color:#f0f4ff;">--</span><span s
224 return ffi.string(buf, buflen[0]) 275 return ffi.string(buf, buflen[0])
225end 276end
226 277
227-- Simple test code. <span style="color:#f0f4ff;">--</span><span style="color:#4040c0;">&#9318;</span> 278-- Simple test code.
228local txt = string.rep("abcd", 1000) 279local txt = string.rep("abcd", 1000)
229print("Uncompressed size: ", #txt) 280print("Uncompressed size: ", #txt)
230local c = compress(txt) 281local c = compress(txt)
@@ -236,13 +287,13 @@ assert(txt2 == txt)
236Here's the step-by-step explanation: 287Here's the step-by-step explanation:
237</p> 288</p>
238<p> 289<p>
239<span style="color:#4040c0;">&#9312;</span> This defines some of the 290<span class="mark">&#9312;</span> This defines some of the
240C&nbsp;functions provided by zlib. For the sake of this example, some 291C&nbsp;functions provided by zlib. For the sake of this example, some
241type indirections have been reduced and it uses the pre-defined 292type indirections have been reduced and it uses the pre-defined
242fixed-size integer types, while still adhering to the zlib API/ABI. 293fixed-size integer types, while still adhering to the zlib API/ABI.
243</p> 294</p>
244<p> 295<p>
245<span style="color:#4040c0;">&#9313;</span> This loads the zlib shared 296<span class="mark">&#9313;</span> This loads the zlib shared
246library. On POSIX systems it's named <tt>libz.so</tt> and usually 297library. On POSIX systems it's named <tt>libz.so</tt> and usually
247comes pre-installed. Since <tt>ffi.load()</tt> automatically adds any 298comes pre-installed. Since <tt>ffi.load()</tt> automatically adds any
248missing standard prefixes/suffixes, we can simply load the 299missing standard prefixes/suffixes, we can simply load the
@@ -253,7 +304,7 @@ you'll have to download it first from the
253<tt>ffi.load()</tt>. 304<tt>ffi.load()</tt>.
254</p> 305</p>
255<p> 306<p>
256<span style="color:#4040c0;">&#9314;</span> First, the maximum size of 307<span class="mark">&#9314;</span> First, the maximum size of
257the compression buffer is obtained by calling the 308the compression buffer is obtained by calling the
258<tt>zlib.compressBound</tt> function with the length of the 309<tt>zlib.compressBound</tt> function with the length of the
259uncompressed string. The next line allocates a byte buffer of this 310uncompressed string. The next line allocates a byte buffer of this
@@ -262,7 +313,7 @@ variable-length array (VLA). The actual number of elements of this
262array is given as the 2nd argument to <tt>ffi.new()</tt>. 313array is given as the 2nd argument to <tt>ffi.new()</tt>.
263</p> 314</p>
264<p> 315<p>
265<span style="color:#4040c0;">&#9315;</span> This may look strange at 316<span class="mark">&#9315;</span> This may look strange at
266first, but have a look at the declaration of the <tt>compress2</tt> 317first, but have a look at the declaration of the <tt>compress2</tt>
267function from zlib: the destination length is defined as a pointer! 318function from zlib: the destination length is defined as a pointer!
268This is because you pass in the maximum buffer size and get back the 319This is because you pass in the maximum buffer size and get back the
@@ -276,7 +327,7 @@ initialized with the maximum buffer size in one step. Calling the
276actual <tt>zlib.compress2</tt> function is then straightforward. 327actual <tt>zlib.compress2</tt> function is then straightforward.
277</p> 328</p>
278<p> 329<p>
279<span style="color:#4040c0;">&#9316;</span> We want to return the 330<span class="mark">&#9316;</span> We want to return the
280compressed data as a Lua string, so we'll use <tt>ffi.string()</tt>. 331compressed data as a Lua string, so we'll use <tt>ffi.string()</tt>.
281It needs a pointer to the start of the data and the actual length. The 332It needs a pointer to the start of the data and the actual length. The
282length has been returned in the <tt>buflen</tt> array, so we'll just 333length has been returned in the <tt>buflen</tt> array, so we'll just
@@ -292,13 +343,13 @@ results in buffers instead of strings. This will reduce the overhead
292for garbage collection and string interning. 343for garbage collection and string interning.
293</p> 344</p>
294<p> 345<p>
295<span style="color:#4040c0;">&#9317;</span> The <tt>uncompress</tt> 346<span class="mark">&#9317;</span> The <tt>uncompress</tt>
296functions does the exact opposite of the <tt>compress</tt> function. 347functions does the exact opposite of the <tt>compress</tt> function.
297The compressed data doesn't include the size of the original string, 348The compressed data doesn't include the size of the original string,
298so this needs to be passed in. Otherwise no surprises here. 349so this needs to be passed in. Otherwise no surprises here.
299</p> 350</p>
300<p> 351<p>
301<span style="color:#4040c0;">&#9318;</span> The code, that makes use 352<span class="mark">&#9318;</span> The code, that makes use
302of the functions we just defined, is just plain Lua code. It doesn't 353of the functions we just defined, is just plain Lua code. It doesn't
303need to know anything about the LuaJIT FFI &mdash; the convenience 354need to know anything about the LuaJIT FFI &mdash; the convenience
304wrapper functions completely hide it. 355wrapper functions completely hide it.
diff --git a/doc/install.html b/doc/install.html
index 220c326f..cdb9075d 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -417,7 +417,7 @@ simply use whatever <tt>make install</tt> creates. There's a reason
417for all of the files <em>and</em> directories it creates. 417for all of the files <em>and</em> directories it creates.
418</p> 418</p>
419<p> 419<p>
420The build system uses GNU make and autodetects most settings based on 420The build system uses GNU make and auto-detects most settings based on
421the host you're building it on. This should work fine for native builds, 421the host you're building it on. This should work fine for native builds,
422even when sandboxed. You may need to pass some of the following flags to 422even when sandboxed. You may need to pass some of the following flags to
423<em>both</em> the <tt>make</tt> and the <tt>make install</tt> command lines 423<em>both</em> the <tt>make</tt> and the <tt>make install</tt> command lines
@@ -431,7 +431,7 @@ the <tt>-rpath</tt> of the shared library.</li>
431to a shadow tree instead of the root tree of the build system.</li> 431to a shadow tree instead of the root tree of the build system.</li>
432<li>Have a look at the top-level <tt>Makefile</tt> and <tt>src/Makefile</tt> 432<li>Have a look at the top-level <tt>Makefile</tt> and <tt>src/Makefile</tt>
433for additional variables to tweak. The following variables <em>may</em> be 433for additional variables to tweak. The following variables <em>may</em> be
434overriden, but it's <em>not</em> recommended, except for special needs 434overridden, but it's <em>not</em> recommended, except for special needs
435like cross-builds: 435like cross-builds:
436<tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS, 436<tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS,
437TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS, 437TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS,
diff --git a/doc/luajit.html b/doc/luajit.html
index 108ca18e..afd8616b 100644
--- a/doc/luajit.html
+++ b/doc/luajit.html
@@ -96,7 +96,7 @@ performance and an unmatched <b>low memory footprint</b>: less than
96<p> 96<p>
97LuaJIT has been in continuous development since 2005. It's widely 97LuaJIT has been in continuous development since 2005. It's widely
98considered to be <b>one of the fastest dynamic language 98considered to be <b>one of the fastest dynamic language
99implementations</b>. It has outperfomed other dynamic languages on many 99implementations</b>. It has outperformed other dynamic languages on many
100cross-language benchmarks since its first release &mdash; often by a 100cross-language benchmarks since its first release &mdash; often by a
101substantial margin. In 2009 other dynamic language VMs started to catch up 101substantial margin. In 2009 other dynamic language VMs started to catch up
102with the performance of LuaJIT 1.x. Well, I couldn't let that slide. ;-) 102with the performance of LuaJIT 1.x. Well, I couldn't let that slide. ;-)
diff --git a/doc/status.html b/doc/status.html
index eddbfb24..1048adc4 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -182,9 +182,10 @@ handled correctly. The error may fall through an on-trace
182 182
183<h2>Roadmap</h2> 183<h2>Roadmap</h2>
184<p> 184<p>
185Rather than stating exact release dates (I'm well known for making 185Please refer to the
186spectacularly wrong guesses), this roadmap lists the general project 186<a href="http://lua-users.org/lists/lua-l/2011-01/msg01238.html"><span class="ext">&raquo;</span>&nbsp;LuaJIT
187plan, sorted by priority, as well as ideas for the future: 187Roadmap 2011</a> for the latest release plan. Here's the general
188project plan for LuaJIT 2.0:
188</p> 189</p>
189<ul> 190<ul>
190<li> 191<li>