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