Jsctypes/api: Difference between revisions

:'''<code>''lib''.declare(''name'', ''abi'', ''rtype'', ''<nowiki>[argtype1, ...]</nowiki>'')</code>''' - Declare a function. ''(TODO: all the details)'' This always returns a new function object or throws an exception.

:'''<code>ctypes.size_t, ssize_t, intptr_t, uintptr_t</code>''' - Primitive types whose size depends on the platform. These types do not autoconvert to JavaScript numbers because on some platforms, there are values of these types that cannot be precisely represented as a JS number. Instead they convert to wrapper objects (on all platforms). See "64-bit integer objects" below.

:<code>ctypes.long</code> and <code>ctypes.unsigned_long</code> autoconvert to 64-bit integer objects (on all platforms). ''(Rationale: Some platforms have 64-bit <code>long</code> and some do not.)'' The rest autoconvert to JavaScript numbers.

 

:'''<code>ctypes.jschar</code>''' - A 16-bit unsigned character type. (This is distinct from <code>uint8_t</code> in details of conversion behavior. js-ctypes autoconverts C <code>jschar</code>s to JavaScript strings of length 1.)

:'''<code>ctypes.string, ustring</code>''' - String types. The C/C++ type for <code>ctypes.string</code> is <code>const char *</code>. C/C++ values of this type must be either <code>null</code> or pointers to null-terminated strings. <code>ctypes.ustring</code> is the same, but for <code>const jschar *</code>; that is, the code units of the string are <code>uint16_t</code>.

:'''<code>new ctypes.StructType(''name'', ''fields'')</code>''' - Create a new struct type with the given ''name'' and ''fields''. ''fields'' is an array of field descriptors. js-ctypes calculates the offsets of the fields from its encyclopedic knowledge of the architecture's struct layout rules. If ''name'' is not a string, or ''fields'' contains a field descriptor with a type ''t'' such that <code>''t''.size</code> is <code>undefined</code>, throw a <code>TypeError</code>. If the size of the struct, in bytes, would not be exactly representable both as a <code>size_t</code> and as a JavaScript number, throw a <code>RangeError</code>.

  const FILE = new ctypes.PointerType("FILE *");

  const struct_tm = new ctypes.StructType('tm', [[ctypes.int, 'tm_sec'], ...]);

:For primitive types this is just the name of the corresponding C/C++ type. Note that some of the builtin types are aliases for other types, so it might be that <code>ctypes.unsigned_long.name == "uint32_t"</code> (or something else). ''(Open issue: Is that too astonishing? Python ctypes does the same thing.)''

:For struct types and opaque pointer types, this is simply the string that was passed to the constructor. For other pointer types and array types this should try to generate valid C/C++ type expressions, which isn't exactly trivial.

  ctypes.ustring.name

   ===> "const jschar *"

  const FILE = new ctypes.PointerType("FILE *");

   ===> "FILE *"

  const struct_tm = new ctypes.StructType("tm", {tm_sec: ctypes.int, ...});

         new ctypes.ArrayType(ctypes.string, 4)));

   ===> "const char *(**)[4]"

  const ptrTo_ptrsTo_arrayOf4_strings = ctypes.string.array(4).ptr.ptr;

   ===> "ctypes.PointerType(ctypes.char)"

     "Point", {x: ctypes.int32_t, y: ctypes.int32_t});

   ===> "ctypes.StructType("Point", {x: ctypes.int32_t, y: ctypes.int23_t})"

:Types have a hierarchy of prototype objects. The prototype of <code>ctypes.CType.prototype</code> is <code>Function.prototype</code>. The prototype of <code>ctypes.{Array,Struct,Pointer}Type.prototype</code> and of all the builtin types except for the string types and <code>ctypes.voidptr_t</code> is <code>ctypes.CType.prototype</code>. The prototype of an array type is <code>ctypes.ArrayType.prototype</code>. The prototype of a struct type is <code>ctypes.StructType.prototype</code>. The prototype of a string type or pointer type is <code>ctypes.PointerType.prototype</code>.

:Every <code>CType</code> ''t'' has <code>''t''.prototype.constructor === ''t''</code>; that is, its <code>.prototype</code> has a read-only, permanent, own <code>.constructor</code> property that refers to the type. The same is true of the four type constructors <code>ctypes.{C,Array,Struct,Pointer}Type</code>.

:'''<code>new ''t''(''val'')</code>''' or '''<code>''t''(''val'')</code>''' - If <code>''t''.size</code> is not <code>undefined</code>: Convert ''val'' to type ''t'' by calling <code>ExplicitConvert(''val'', ''t'')</code>, throwing a <code>TypeError</code> if the conversion is impossible. Allocate a new buffer of <code>''t''.size</code> bytes, populated with the converted value. Return a new <code>CData</code> object of type ''t'' referring to the complete object in that buffer. (When ''val'' is a <code>CData</code> object of type ''t'', the behavior is like <code>malloc</code> followed by <code>memcpy</code>.)

:If ''t'' is an array type of unspecified length and ''val'' is a size value (defined above): Let ''u'' = <code>ArrayType(''t''.elementType, ''val'')</code> and return <code>new ''u''</code>.

:If ''t'' is an array type of unspecified length and ''val'' is not a size value: If ''val'' is not an object, or it does not have a <code>.length</code> property whose value is a nonnegative integer, throw a <code>TypeError</code>. Otherwise, let ''u'' = <code>ArrayType(''t''.elementType, ''val''.length)</code> and return <code>new ''u''(''val'')</code>.

:''(Array <code>CData</code> objects created in this way have <code>''cdata''.constructor === ''u''</code>, not ''t''. Rationale: For all <code>CData</code> objects, <code>cdata.constructor.size</code> gives the size in bytes, unless a struct field shadows <code>cdata.constructor</code>.)''

:Otherwise, ''t'' is <code>void_t</code>. Throw a <code>TypeError</code>.

:'''<code>ctypes.cast(''cdata'', ''t'')</code>''' - Return a new <code>CData</code> object which points to the same memory block as ''cdata'', but with type ''t''. If <code>''t''.size</code> is undefined or less than <code>''cdata''.constructor.size</code>, throw a <code>TypeError</code>. This is like a C cast or a C++ <code>reinterpret_cast</code>.

:'''<code>ctypes.Int64(''n'')</code>''' or '''<code>new ctypes.Int64(''n'')</code>''' - If ''n'' is an integer-valued number such that -2⁶³ &le; ''n'' &lt; 2⁶³, return a sealed <code>Int64</code> object with that value. Otherwise throw a <code>TypeError</code>.

'''<code>ConvertToJS(''x'')</code>''' - This function is used to convert a <code>CData</code> object or a C/C++ return value to a JavaScript value. The intent is to return a simple JavaScript value whenever possible, and a <code>CData</code> object otherwise. The precise rules are:

* If ''x'' is of a number type other than <code>long</code>, <code>unsigned long</code>, the pointer-sized types, and the 64-bit types, return the corresponding JavaScript number.

* If ''x'' is of type <code>long</code> or a signed pointer-sized or 64-bit numeric type (such as <code>int64_t</code>, <code>ssize_t</code>, or <code>intptr_t</code>), return a <code>ctypes.Int64</code> object with value ''x''.

* If ''x'' is of type <code>unsigned long</code> or an unsigned pointer-sized or 64-bit numeric type (such as <code>uint64_t</code>, <code>size_t</code>, or <code>uintptr_t</code>), return a <code>ctypes.UInt64</code> object with value ''x''.

* If ''x'' is of type <code>jschar</code>, return a JavaScript string of length 1 containing the value of ''x'' (like <code>String.fromCharCode(x)</code>).

* If ''x'' is of any other character type, select the corresponding Unicode character. ''(Open issue: Unicode conversions.)'' Convert the character to UTF-16. Return a JavaScript string containing the UTF-16 code units. (If the character type is 1 or 2 bytes, as it is on all platforms we care about, the result is a one-character JavaScript string.)

* If ''x'' is of a string type and is <code>NULL</code>, return <code>null</code>.

* If ''x'' is of type <code>cstring</code> and is non-null, transcode it to UTF-16 and return a JavaScript string containing the UTF-16 code units.  ''(Open issue: Unicode conversions.)''

* If ''x'' is of type <code>ustring</code> and is non-null, return a JavaScript string containing the same sequence of 16-bit characters.

* Otherwise ''x'' is of an array, struct, or pointer type. If the argument ''x'' is already a <code>CData</code> object, return it. Otherwise allocate a buffer containing a copy of the C/C++ value ''x'', and return a <code>CData</code> object of the appropriate type referring to the object in the new buffer.

Note that we do not autoconvert null C/C++ pointers to the JavaScript <code>null</code> value.

<code>'''ImplicitConvert(''val'', ''t'')'''</code> - Convert the JavaScript value ''val'' to a C/C++ value of type ''t''. This is called whenever a JavaScript value of any kind is passed to a parameter of a ctypes-declared function, passed to <code>''cdata''.value = ''val''</code>, or assigned to an array element or struct member, as in <code>''carray''[''i''] = ''val''</code> or <code>''cstruct''.''member'' = ''val''</code>. This function is intended to lose precision only when there is no reasonable alternative. It generally does not coerce values of one type to another type.

* If ''t'' is <code>ctypes.jschar</code>:

:* If ''val'' is a number that can be exactly represented as a value of type <code>jschar</code> (that is, an integer in the range 0 &le; ''val'' &lt; 2¹⁶), the result is that value.

::* If the 16-bit elements of ''val'' are not the UTF-16 encoding of a single Unicode character, fail.

:* Otherwise fail.  ''(Rationale: We don't convert strings to pointers yet partly because we're lazy and partly because it would implicitly cast away const. We don't convert JavaScript arrays to pointers because this would have to allocate a C array implicitly, raising issues about who should deallocate it, and when, and how they know it's their responsibility.)''

:* If ''val'' is not a JavaScript object, fail. ''(We could reasonably convert JS strings to arrays of char types, but let's skip it for now.)''

:* If <code>''val''.length</code> is not a nonnegative integer, fail.

:* If <code>''val''.length !== ''t''.length</code>, fail.

:* Otherwise, the result is a C/C++ array of <code>''val''.length</code> elements of type <code>''t''.elementType</code>. Element ''i'' of the result is <code>ImplicitConvert(''val''[''i''], ''t''.elementType)</code>.

* If ''t'' is a pointer type, pointer-sized type, or 64-bit type, and ''val'' is a string consisting entirely of an optional minus sign, followed by the characters "0x" or "0X", followed by one or more hexadecimal digits, then the result is the same as casting the number named by ''val'' to type ''t'' with a C-style cast.

*If they are both array types, return <code>SameType(''t''.elementType, ''u''.targetType) &amp;&amp; ''t''.length === ''u''.length</code>.

Note that for simple types (integers and strings), we will autoconvert the argument at call time - there's no need to pass in a <code>ctypes.int32_t</code> object. The consumer should never need to instantiate such an object explicitly, unless they're using it to back a pointer - in which case we require explicit, strong typing. See later for examples.

(Of course you don't normally need to do this, as js-ctypes will autoconvert JS numbers to various C/C++ types for you.)

This kind of object is called a <code>CData</code> object, and they are described in detail in the "<code>CData</code> objects" section above.

  FILE_ptr = new ctypes.PointerType("FILE *");

     FILE_ptr, ctypes.string, ctypes.string);

  let q = ctypes.cast(ctypes.uint8_t.ptr, p);

     ctypes.uint64_t, ctypes.string);

=Implementation notes=

'''The ctypes instance.''' Currently, via ctypes.jsm, we instantiate a fresh ctypes instance each time the module is imported - the global 'ctypes' property will be a different object each time. This doesn't matter right now, because ctypes doesn't have any prototype objects of its own - just object constants and functions. With the API proposal above, it will have a CType object that serves as prototype for the other types. With this in mind, do we want to have 1) a single ctypes instance, which we stash in a C++ static global and hand out on demand; or 2) a separate ctypes instance per import?

* With 1), I'm not sure if there would be issues with having a single ctypes object span multiple JSRuntimes or somesuch. If so, we might be stuck. If not, we will need to carefully seal the ctypes object and its children, and it won't be able to have a __parent__. Threadsafety should be trivial; at most we will need to make the ctypes init function safe against reentrance.

* With 2), we will have different CType proto objects per ctypes instance. Will this be an issue for code wanting to pass ctypes objects between module instances? ctypes does not internally depend on prototype object equality, only on JSClass equality, so it will work. Consumers will have trouble if they want to compare prototype objects, however. I'm not sure if this is a big deal. Also, doing this means that we need to stash the CType proto object somewhere, so it's accessible from C++. I don't think we can depend on having the 'ctypes' object hanging off the global object - unless we make it readonly - in which case we need to have the CType proto object hanging off each object we create. (Which we should get for free, as long as all the type object __proto__'s are readonly!) So, either we make the 'ctypes' property readonly, or we make {every type object}.__proto__ readonly, or both.