From 2e98c3d0644fc0c265844908f43b7e4526dd819c Mon Sep 17 00:00:00 2001 From: Mike Pall Date: Thu, 23 Jun 2022 09:10:09 +0200 Subject: Grammar and spell check. --- doc/ext_ffi_semantics.html | 58 +++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 29 deletions(-) (limited to 'doc/ext_ffi_semantics.html') diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html index 4909fedd..6c6f8ad7 100644 --- a/doc/ext_ffi_semantics.html +++ b/doc/ext_ffi_semantics.html @@ -84,7 +84,7 @@ footprint. It's used by the ffi.* library functions to declare C types or external symbols.

-It's only purpose is to parse C declarations, as found e.g. in +Its only purpose is to parse C declarations, as found e.g. in C header files. Although it does evaluate constant expressions, it's not a C compiler. The body of inline C function definitions is simply ignored. @@ -161,7 +161,7 @@ function declarations.

-The following C types are pre-defined by the C parser (like +The following C types are predefined by the C parser (like a typedef, except re-declarations will be ignored):

A ctype object can be indexed with a string key, too. The only -pre-defined operation is reading scoped constants of +predefined operation is reading scoped constants of struct/union types. All other accesses defer to the corresponding metamethods or index tables (if any).

@@ -650,7 +650,7 @@ certain optimizations.

As a consequence, the elements of complex numbers and vectors are immutable. But the elements of an aggregate holding these -types may be modified of course. I.e. you cannot assign to +types may be modified, of course. I.e. you cannot assign to foo.c.im, but you can assign a (newly created) complex number to foo.c.

@@ -669,8 +669,8 @@ through unions is explicitly detected and allowed. to ffi.new(ct, ...), unless a __new metamethod is defined. The __new metamethod is called with the ctype object plus any other arguments passed to the constructor. Note that you have to -use ffi.new inside of it, since calling ct(...) would -cause infinite recursion. +use ffi.new inside the metamethod, since calling ct(...) +would cause infinite recursion.
  • C function call: a cdata function or cdata function pointer can be called. The passed arguments are @@ -681,7 +681,7 @@ variable argument part of vararg C function use C function is called and the return value (if any) is converted to a Lua object.
    On Windows/x86 systems, __stdcall functions are automatically -detected and a function declared as __cdecl (the default) is +detected, and a function declared as __cdecl (the default) is silently fixed up after the first call.
    • @@ -691,7 +691,7 @@ silently fixed up after the first call.
  • Pointer arithmetic: a cdata pointer/array and a cdata number or a Lua number can be added or subtracted. The number must be -on the right hand side for a subtraction. The result is a pointer of +on the right-hand side for a subtraction. The result is a pointer of the same type with an address plus or minus the number value multiplied by the element size in bytes. An error is raised if the element size is undefined.
    • @@ -706,7 +706,7 @@ operators (+ - * / % ^ and unary minus) can be applied to two cdata numbers, or a cdata number and a Lua number. If one of them is an uint64_t, the other side is converted to an uint64_t and an unsigned arithmetic operation -is performed. Otherwise both sides are converted to an +is performed. Otherwise, both sides are converted to an int64_t and a signed arithmetic operation is performed. The result is a boxed 64 bit cdata object.
    @@ -737,7 +737,7 @@ which is compatible with any other pointer type.
  • 64 bit integer comparison: two cdata numbers, or a cdata number and a Lua number can be compared with each other. If one of them is an uint64_t, the other side is converted to an -uint64_t and an unsigned comparison is performed. Otherwise +uint64_t and an unsigned comparison is performed. Otherwise, both sides are converted to an int64_t and a signed comparison is performed.
    @@ -762,9 +762,9 @@ keys! A cdata object is treated like any other garbage-collected object and is hashed and compared by its address for table indexing. Since there's no interning for cdata value types, the same value may be -boxed in different cdata objects with different addresses. Thus +boxed in different cdata objects with different addresses. Thus, t[1LL+1LL] and t[2LL] usually do not point to -the same hash slot and they certainly do not point to the same +the same hash slot, and they certainly do not point to the same hash slot as t[2].

    @@ -786,7 +786,7 @@ the resulting Lua number as a key when indexing tables.
    One obvious benefit: t[tonumber(2LL)] does point to the same slot as t[2].

    • -
  • Otherwise use either tostring() on 64 bit integers +
  • Otherwise, use either tostring() on 64 bit integers or complex numbers or combine multiple fields of a cdata aggregate to a Lua string (e.g. with ffi.string()). Then @@ -794,7 +794,7 @@ use the resulting Lua string as a key when indexing tables.
  • Create your own specialized hash table implementation using the C types provided by the FFI library, just like you would in -C code. Ultimately this may give much better performance than the +C code. Ultimately, this may give much better performance than the other alternatives or what a generic by-value hash table could possibly provide.
    • @@ -860,7 +860,7 @@ garbage collector will automatically free the memory used by it (at the end of the next GC cycle).

    -Please note that pointers themselves are cdata objects, however they +Please note, that pointers themselves are cdata objects, however they are not followed by the garbage collector. So e.g. if you assign a cdata array to a pointer, you must keep the cdata object holding the array alive as long as the pointer is still in use: @@ -909,18 +909,18 @@ of the function pointer and the Lua function object (closure).

    This can happen implicitly due to the usual conversions, e.g. when -passing a Lua function to a function pointer argument. Or you can use +passing a Lua function to a function pointer argument. Or, you can use ffi.cast() to explicitly cast a Lua function to a C function pointer.

    -Currently only certain C function types can be used as callback +Currently, only certain C function types can be used as callback functions. Neither C vararg functions nor functions with pass-by-value aggregate argument or result types are supported. There -are no restrictions for the kind of Lua functions that can be called +are no restrictions on the kind of Lua functions that can be called from the callback — no checks for the proper number of arguments are made. The return value of the Lua function will be converted to the -result type and an error will be thrown for invalid conversions. +result type, and an error will be thrown for invalid conversions.

    It's allowed to throw errors across a callback invocation, but it's not @@ -981,7 +981,7 @@ convention cannot be automatically detected, unlike for __stdcall calls to Windows functions.

    -For some use cases it's necessary to free up the resources or to +For some use cases, it's necessary to free up the resources or to dynamically redirect callbacks. Use an explicit cast to a C function pointer and keep the resulting cdata object. Then use the cb:free() @@ -1034,7 +1034,7 @@ GUI application, which waits for user input most of the time, anyway.

    For new designs avoid push-style APIs: a C function repeatedly -calling a callback for each result. Instead use pull-style APIs: +calling a callback for each result. Instead, use pull-style APIs: call a C function repeatedly to get a new result. Calls from Lua to C via the FFI are much faster than the other way round. Most well-designed libraries already use pull-style APIs (read/write, get/put). @@ -1053,7 +1053,7 @@ function.

    Indexing a C library namespace object with a symbol name (a Lua -string) automatically binds it to the library. First the symbol type +string) automatically binds it to the library. First, the symbol type is resolved — it must have been declared with ffi.cdef. Then the symbol address is resolved by searching for the symbol name in the @@ -1108,7 +1108,7 @@ Performance notice: the JIT compiler specializes to the identity of namespace objects and to the strings used to index it. This effectively turns function cdata objects into constants. It's not useful and actually counter-productive to explicitly cache these -function objects, e.g. local strlen = ffi.C.strlen. OTOH it +function objects, e.g. local strlen = ffi.C.strlen. OTOH, it is useful to cache the namespace itself, e.g. local C = ffi.C.

    @@ -1133,14 +1133,14 @@ This behavior is inevitable, since the goal is to provide full interoperability with C code. Adding extra safety measures, like bounds checks, would be futile. There's no way to detect misdeclarations of C functions, since shared libraries only -provide symbol names, but no type information. Likewise there's no way +provide symbol names, but no type information. Likewise, there's no way to infer the valid range of indexes for a returned pointer.

    Again: the FFI library is a low-level library. This implies it needs to be used with care, but it's flexibility and performance often outweigh this concern. If you're a C or C++ developer, it'll be easy -to apply your existing knowledge. OTOH writing code for the FFI +to apply your existing knowledge. OTOH, writing code for the FFI library is not for the faint of heart and probably shouldn't be the first exercise for someone with little experience in Lua, C or C++.

    @@ -1168,7 +1168,7 @@ currently incomplete:
  • C declarations are not passed through a C pre-processor, yet.
  • The C parser is able to evaluate most constant expressions -commonly found in C header files. However it doesn't handle the +commonly found in C header files. However, it doesn't handle the full range of C expression semantics and may fail for some obscure constructs.
  • static const declarations only work for integer types -- cgit v1.2.3-55-g6feb