Jsctypes/api: Difference between revisions

=== The types provided by ctypes ===

ctypes provides the following builtin types:

:'''<code>ctypes.int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, float32_t, float64_t</code>''' - Primitive numeric types that behave the same way on all platforms (with the usual caveat that every platform has slightly different floating-point behavior, in corner cases, and there's nothing we can realistically do about it).

:The <nowiki>[[Class]]</nowiki> of a ctypes type is <code>"Function"</code>. ''(Open issue: Subject to possible implementation difficulties.)''

:Every ctypes type has a read-only, permanent <code>.prototype</code> property.  The type-constructors <code>ctypes.{Pointer,Struct,Array,}Type</code> each have a read-only, permanent <code>.prototype</code> property as well.

:Types have a hierarchy of prototype objects. The prototype of <code>ctypes.Type.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.Type.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 ctypes type ''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. Also:

:<code>ctypes.Type.prototype.constructor === ctypes.Type</code>

:<code>ctypes.ArrayType.prototype.constructor === ctypes.ArrayType</code>

:<code>ctypes.StructType.prototype.constructor === ctypes.StructType</code>

js-ctypes types are JavaScript constructors. That is, they are functions, and they can be called in various different ways.  (js-ctypes buffers and references are to be described in later sections.)

:'''<code>new ''t''</code>''' or '''<code>new ''t''()</code>''' - Without arguments, these allocate a new buffer of <code>''t''.size</code> bytes, populate it with zeroes, and return a new ctypes reference to the complete object in that buffer.

:'''<code>''t''()</code>''' - Return <code>ConvertToJS(new t)</code>. (<code>ConvertToJS</code> is defined below. The result is that <code>ctypes.bool() === false</code>, for number types <code>''t''() === 0</code>, for character types <code>''t''() === '\0'</code>, and for string and pointer types <code>''t''() === null</code> on platforms where the null pointer is all zeroes. For all other types the result is the same as <code>new ''t''</code>.)

:'''<code>new ''t''(''val'')</code>''' - Convert ''val'' to type ''t'' according to the explicit conversion rules below, throwing a <code>TypeError</code> if the conversion is impossible. Create a new buffer and reference as above, populating the new buffer with the converted value instead of zeroing it out. (When ''val'' is a reference of type ''t'', the behavior is like <code>malloc</code> followed by <code>memcpy</code>.)

:'''<code>''t''(''val'')</code>''' - Return <code>ConvertToJS(new ''t''(''val''))</code>.

 

js-ctypes references are like C++ references: they have a type, they refer to a C++ value, their address can be taken, and they can be assigned to. However, the JavaScript syntax is very different from the C++ syntax.

:'''<code>''ref''.assign(''val'')</code>''' - Convert ''val'' to the type of ''ref'' using the implicit conversion rules. Store the converted value in the buffer location referred to by ''ref''.

:'''<code>''ref''.constructor</code>''' - Read-only. The type of the reference. ''(Implementation note: The prototype of ''ref'' is an object that has a read-only <code>constructor</code> property, as detailed under "minutiae".)''

Struct references have getters and setters for each struct member:

:'''<code>''cstruct''.''member''</code>''' - Let ''R'' be a reference to the struct member. Return <code>ConvertToJS(''R'')</code>.

These getters and setters can shadow the properties and methods described above.

Likewise, array references have getters and setters for each element. Arrays additionally have a <code>length</code> property.

:'''<code>''carray''[''i'']</code>''' - Let ''R'' be a reference to the element at index ''i''. Return <code>ConvertToJS(''R'')</code>.

''(TODO: Possibly, a way to get a reference that acts like a view on a window of an array. E.g. ''carray''.slice(start, stop). Then you could <code>.assign</code> one region of memory to another, effectively memcpy-ing.)''

:The <nowiki>[[Class]]</nowiki> of a ctypes reference is <code>"Reference"</code>.

:The prototype of a reference is the same as its type's <code>.prototype</code> property.

''(Implementation notes: A ctypes reference is a JSObject; it has a reserved slot that points to its type, a reserved slot that points to the backing buffer, and a pointer to the actual referenced location within the buffer. Since the data pointer might not be aligned to 2 bytes, PRIVATE_TO_JSVAL is insufficient; a custom JSClass.trace hook will be needed. A ctypes buffer is a separate JSObject that has a pointer to a malloc'd buffer where the C++ data is stored. It doesn't have a pointer to a ctypes type. It has a finalizer that frees the buffer; references that point into the buffer keep the buffer alive, thanks to the reserved slot.)''