Jsctypes/api: Difference between revisions

 

==Callbacks==

 

 

'''Lifetimes.''' C/C++ makes it impossible to track an object pointer. Both JavaScript's GC and experience with C/C++ function pointers will tend to discourage users from caring about function lifetimes.

 

I think the best solution to this problem is to put the burden of keeping the function alive entirely on the client.

 

'''Finding the right context to use.''' If we burn the cx right into the libffi closure, it will crash when called from a different thread or after the cx is destroyed. If we take a context at random from some internal JSAPI structure, it might be thread-safe, but the context's options and global will be random, which sounds dangerous. Perhaps ctypes itself can create a context per thread, on demand, for the use of function pointers. In a typical application, that would only create one context, if any.

<code>CData</code> objects of certain pointer and array types have methods for reading and writing Unicode strings. These methods are present if the target or element type is an 8-bit character or integer type.

'''<code>''cdata''.readString(''[encoding[, length]]'')</code>''' - Read bytes from ''cdata'' and convert them to Unicode characters using the specified ''encoding'', returning a string. Specifically:

* If ''encoding'' is <code>undefined</code> or omitted, the selected encoding is UTF-8. Otherwise, if ''encoding'' is a string naming a known character encoding, that encoding is selected. Otherwise throw a <code>TypeError</code>.

* If ''length'' is a size value, ''cdata'' is an array, and <code>''length'' &gt; <code>''cdata''.length</code>, then throw a <code>TypeError</code>.

* Otherwise, if ''length'' is a size value, take exactly ''length'' bytes starting at ''p'' and convert them to Unicode characters according to the selected encoding. ''(Open issue: Error handling.)'' Return a JavaScript string containing the Unicode characters, represented in UTF-16.

* Otherwise, if ''length'' is <code>undefined</code> or omitted, convert bytes starting at ''p'' to Unicode characters according to the selected encoding. Stop when the end of the array is reached (if ''cdata'' is an array) or when a null character (U+0000) is found. ''(Open issue: Error handling.)'' Return a JavaScript string containing the Unicode characters, represented in UTF-16.

* Otherwise throw a <code>TypeError</code>.

'''<code>''cdata''.writeString(''s'', ''[encoding[, length]]'')</code>''' - Determine the starting pointer ''p'' as above. If ''s'' is not a well-formed UTF-16 string, throw a <code>TypeError</code>. ''(Open issue: Error handling.)'' Otherwise convert ''s'' to bytes in the specified ''encoding'' (default: UTF-8) and write at most ''length'' - 1 bytes, or all the converted bytes, if ''length'' is <code>undefined</code> or omitted, to memory starting at ''p''. Write a converted null character after the data. Return the number of bytes of data written, not counting the terminating null character.

''(Open issue: As proposed, these are not suitable for working with encodings where a zero byte might not indicate the end of text. For example, a string encoded in UTF-16 will typically contain a lot of zero bytes. Unfortunately, in the case of readString, the underlying library demands the length up front.)''

''(Open issue: These methods offer no error handling options, which is pretty weak. Real-world code often wants to allow a few characters to be garbled rather than fail. For now we will likely be limited to whatever the underlying codec library, <code>nsIScriptableUnicodeConverter</code>, can do.)''

''(Open issue: 16-bit versions too, for UTF-16?)''