Skip to content

Implement overrides for functions that accept mutable buffers

As discussed on !787 (merged), it may be possible to implement overrides for functions that accept mutable buffers, whereas this was not possible with the older custom ByteArray implementation.

An example of a function is Gio.InputStream.read_all_async(), which has a signature of:

/**
 * @param {Number} count - max bytes to read
 * @param {Number} priority - e.g. GLib.PRIORITY_DEFAULT
 * @param {Gio.Cancellable} cancellable - ...
 * @param (Gio.AsyncReadyCallback} callback - ...
 * @returns {Uint8Array}
 */

Note that our DevDocs scraper doesn't properly document the above arguments, but that's another issue.

Assuming that signature is correct, there's a couple assumptions to make:

  • count can be used to create a large enough ArrayBuffer
  • For async functions like this, the user will not attempt to use the Uint8Array while it's being used in another thread
  • The resulting Uint8Array is still usable if count is not reached, resulting in trailing NULL-bytes
  • The caller of the function knows...
    • if the result may have embedded NULL-bytes, and not be treated as a NULL-terminated string, etc
    • if it is a string, that the buffer is large enough that the result does have a trailing NULL-byte (or our conversion functions can deal with that)

If this were implemented per-function, each override could be examined for "gotchas" like the above. If this were implemented as part of the "automatic" bindings, there may be some instances where the annotations are open-ended or ambiguous about gchar * vs guint8 *, for example.

I'm generally familiar with using such APIs in C, and working around the unintrospectable functions in GJS, but I don't have much hands-on experience with GObject-Introspection itself. So comments and corrections welcome :)