@gtkx/ffi 0.1.45 → 0.1.47

package/dist/generated/gio/async-initable.d.ts

@@ -1,11 +1,166 @@
 import { AsyncResult } from "./async-result.js";
 import { Cancellable } from "./cancellable.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GAsyncInitable` is an interface for asynchronously initializable objects.
+ *
+ * This is the asynchronous version of [iface@Gio.Initable]; it behaves the same
+ * in all ways except that initialization is asynchronous. For more details
+ * see the descriptions on `GInitable`.
+ *
+ * A class may implement both the `GInitable` and `GAsyncInitable` interfaces.
+ *
+ * Users of objects implementing this are not intended to use the interface
+ * method directly; instead it will be used automatically in various ways.
+ * For C applications you generally just call [func@Gio.AsyncInitable.new_async]
+ * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
+ * [method@Gio.AsyncInitable.init_async] under the covers, calling back with `NULL`
+ * and a set `GError` on failure.
+ *
+ * A typical implementation might look something like this:
+ *
+ * ```c
+ * enum {
+ * NOT_INITIALIZED,
+ * INITIALIZING,
+ * INITIALIZED
+ * };
+ *
+ * static void
+ * _foo_ready_cb (Foo *self)
+ * {
+ * GList *l;
+ *
+ * self->priv->state = INITIALIZED;
+ *
+ * for (l = self->priv->init_results; l != NULL; l = l->next)
+ * {
+ * GTask *task = l->data;
+ *
+ * if (self->priv->success)
+ * g_task_return_boolean (task, TRUE);
+ * else
+ * g_task_return_new_error (task, ...);
+ * g_object_unref (task);
+ * }
+ *
+ * g_list_free (self->priv->init_results);
+ * self->priv->init_results = NULL;
+ * }
+ *
+ * static void
+ * foo_init_async (GAsyncInitable       *initable,
+ * int                   io_priority,
+ * GCancellable         *cancellable,
+ * GAsyncReadyCallback   callback,
+ * gpointer              user_data)
+ * {
+ * Foo *self = FOO (initable);
+ * GTask *task;
+ *
+ * task = g_task_new (initable, cancellable, callback, user_data);
+ * g_task_set_name (task, G_STRFUNC);
+ *
+ * switch (self->priv->state)
+ * {
+ * case NOT_INITIALIZED:
+ * _foo_get_ready (self);
+ * self->priv->init_results = g_list_append (self->priv->init_results,
+ * task);
+ * self->priv->state = INITIALIZING;
+ * break;
+ * case INITIALIZING:
+ * self->priv->init_results = g_list_append (self->priv->init_results,
+ * task);
+ * break;
+ * case INITIALIZED:
+ * if (!self->priv->success)
+ * g_task_return_new_error (task, ...);
+ * else
+ * g_task_return_boolean (task, TRUE);
+ * g_object_unref (task);
+ * break;
+ * }
+ * }
+ *
+ * static gboolean
+ * foo_init_finish (GAsyncInitable       *initable,
+ * GAsyncResult         *result,
+ * GError              **error)
+ * {
+ * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
+ *
+ * return g_task_propagate_boolean (G_TASK (result), error);
+ * }
+ *
+ * static void
+ * foo_async_initable_iface_init (gpointer g_iface,
+ * gpointer data)
+ * {
+ * GAsyncInitableIface *iface = g_iface;
+ *
+ * iface->init_async = foo_init_async;
+ * iface->init_finish = foo_init_finish;
+ * }
+ * ```
+ */
 export declare class AsyncInitable {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): AsyncInitable;
+    /**
+     * Starts asynchronous initialization of the object implementing the
+     * interface. This must be done before any real use of the object after
+     * initial construction. If the object also implements #GInitable you can
+     * optionally call g_initable_init() instead.
+     *
+     * This method is intended for language bindings. If writing in C,
+     * g_async_initable_new_async() should typically be used instead.
+     *
+     * When the initialization is finished, `callback` will be called. You can
+     * then call g_async_initable_init_finish() to get the result of the
+     * initialization.
+     *
+     * Implementations may also support cancellation. If `cancellable` is not
+     * %NULL, then initialization can be cancelled by triggering the cancellable
+     * object from another thread. If the operation was cancelled, the error
+     * %G_IO_ERROR_CANCELLED will be returned. If `cancellable` is not %NULL, and
+     * the object doesn't support cancellable initialization, the error
+     * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+     *
+     * As with #GInitable, if the object is not initialized, or initialization
+     * returns with an error, then all operations on the object except
+     * g_object_ref() and g_object_unref() are considered to be invalid, and
+     * have undefined behaviour. They will often fail with g_critical() or
+     * g_warning(), but this must not be relied on.
+     *
+     * Callers should not assume that a class which implements #GAsyncInitable can
+     * be initialized multiple times; for more information, see g_initable_init().
+     * If a class explicitly supports being initialized multiple times,
+     * implementation requires yielding all subsequent calls to init_async() on the
+     * results of the first call.
+     *
+     * For classes that also support the #GInitable interface, the default
+     * implementation of this method will run the g_initable_init() function
+     * in a thread, so if you want to support asynchronous initialization via
+     * threads, just implement the #GAsyncInitable interface without overriding
+     * any interface methods.
+     * @param ioPriority - the I/O priority of the operation
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback to call when the request is satisfied
+     * @param userData - the data to pass to callback function
+     */
     initAsync(ioPriority: number, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finishes asynchronous initialization and returns the result.
+     * See g_async_initable_init_async().
+     * @param res - a #GAsyncResult.
+     */
     initFinish(res: AsyncResult): boolean;
+    /**
+     * Finishes the async construction for the various g_async_initable_new
+     * calls, returning the created object or %NULL on error.
+     * @param res - the #GAsyncResult from the callback
+     */
     newFinish(res: AsyncResult): GObject.GObject;
 }

package/dist/generated/gio/async-initable.js

@@ -1,6 +1,109 @@
 import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GAsyncInitable` is an interface for asynchronously initializable objects.
+ *
+ * This is the asynchronous version of [iface@Gio.Initable]; it behaves the same
+ * in all ways except that initialization is asynchronous. For more details
+ * see the descriptions on `GInitable`.
+ *
+ * A class may implement both the `GInitable` and `GAsyncInitable` interfaces.
+ *
+ * Users of objects implementing this are not intended to use the interface
+ * method directly; instead it will be used automatically in various ways.
+ * For C applications you generally just call [func@Gio.AsyncInitable.new_async]
+ * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
+ * [method@Gio.AsyncInitable.init_async] under the covers, calling back with `NULL`
+ * and a set `GError` on failure.
+ *
+ * A typical implementation might look something like this:
+ *
+ * ```c
+ * enum {
+ * NOT_INITIALIZED,
+ * INITIALIZING,
+ * INITIALIZED
+ * };
+ *
+ * static void
+ * _foo_ready_cb (Foo *self)
+ * {
+ * GList *l;
+ *
+ * self->priv->state = INITIALIZED;
+ *
+ * for (l = self->priv->init_results; l != NULL; l = l->next)
+ * {
+ * GTask *task = l->data;
+ *
+ * if (self->priv->success)
+ * g_task_return_boolean (task, TRUE);
+ * else
+ * g_task_return_new_error (task, ...);
+ * g_object_unref (task);
+ * }
+ *
+ * g_list_free (self->priv->init_results);
+ * self->priv->init_results = NULL;
+ * }
+ *
+ * static void
+ * foo_init_async (GAsyncInitable       *initable,
+ * int                   io_priority,
+ * GCancellable         *cancellable,
+ * GAsyncReadyCallback   callback,
+ * gpointer              user_data)
+ * {
+ * Foo *self = FOO (initable);
+ * GTask *task;
+ *
+ * task = g_task_new (initable, cancellable, callback, user_data);
+ * g_task_set_name (task, G_STRFUNC);
+ *
+ * switch (self->priv->state)
+ * {
+ * case NOT_INITIALIZED:
+ * _foo_get_ready (self);
+ * self->priv->init_results = g_list_append (self->priv->init_results,
+ * task);
+ * self->priv->state = INITIALIZING;
+ * break;
+ * case INITIALIZING:
+ * self->priv->init_results = g_list_append (self->priv->init_results,
+ * task);
+ * break;
+ * case INITIALIZED:
+ * if (!self->priv->success)
+ * g_task_return_new_error (task, ...);
+ * else
+ * g_task_return_boolean (task, TRUE);
+ * g_object_unref (task);
+ * break;
+ * }
+ * }
+ *
+ * static gboolean
+ * foo_init_finish (GAsyncInitable       *initable,
+ * GAsyncResult         *result,
+ * GError              **error)
+ * {
+ * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
+ *
+ * return g_task_propagate_boolean (G_TASK (result), error);
+ * }
+ *
+ * static void
+ * foo_async_initable_iface_init (gpointer g_iface,
+ * gpointer data)
+ * {
+ * GAsyncInitableIface *iface = g_iface;
+ *
+ * iface->init_async = foo_init_async;
+ * iface->init_finish = foo_init_finish;
+ * }
+ * ```
+ */
 export class AsyncInitable {
     ptr;
     constructor(ptr) {
@@ -9,6 +112,48 @@ export class AsyncInitable {
     static fromPtr(ptr) {
         return new AsyncInitable(ptr);
     }
+    /**
+     * Starts asynchronous initialization of the object implementing the
+     * interface. This must be done before any real use of the object after
+     * initial construction. If the object also implements #GInitable you can
+     * optionally call g_initable_init() instead.
+     *
+     * This method is intended for language bindings. If writing in C,
+     * g_async_initable_new_async() should typically be used instead.
+     *
+     * When the initialization is finished, `callback` will be called. You can
+     * then call g_async_initable_init_finish() to get the result of the
+     * initialization.
+     *
+     * Implementations may also support cancellation. If `cancellable` is not
+     * %NULL, then initialization can be cancelled by triggering the cancellable
+     * object from another thread. If the operation was cancelled, the error
+     * %G_IO_ERROR_CANCELLED will be returned. If `cancellable` is not %NULL, and
+     * the object doesn't support cancellable initialization, the error
+     * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+     *
+     * As with #GInitable, if the object is not initialized, or initialization
+     * returns with an error, then all operations on the object except
+     * g_object_ref() and g_object_unref() are considered to be invalid, and
+     * have undefined behaviour. They will often fail with g_critical() or
+     * g_warning(), but this must not be relied on.
+     *
+     * Callers should not assume that a class which implements #GAsyncInitable can
+     * be initialized multiple times; for more information, see g_initable_init().
+     * If a class explicitly supports being initialized multiple times,
+     * implementation requires yielding all subsequent calls to init_async() on the
+     * results of the first call.
+     *
+     * For classes that also support the #GInitable interface, the default
+     * implementation of this method will run the g_initable_init() function
+     * in a thread, so if you want to support asynchronous initialization via
+     * threads, just implement the #GAsyncInitable interface without overriding
+     * any interface methods.
+     * @param ioPriority - the I/O priority of the operation
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback to call when the request is satisfied
+     * @param userData - the data to pass to callback function
+     */
     initAsync(ioPriority, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_async_initable_init_async", [
             {
@@ -36,6 +181,11 @@ export class AsyncInitable {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes asynchronous initialization and returns the result.
+     * See g_async_initable_init_async().
+     * @param res - a #GAsyncResult.
+     */
     initFinish(res) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_async_initable_init_finish", [
@@ -64,6 +214,11 @@ export class AsyncInitable {
         }
         return result;
     }
+    /**
+     * Finishes the async construction for the various g_async_initable_new
+     * calls, returning the created object or %NULL on error.
+     * @param res - the #GAsyncResult from the callback
+     */
     newFinish(res) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_async_initable_new_finish", [

package/dist/generated/gio/async-result.d.ts

@@ -1,10 +1,120 @@
 import * as GObject from "../gobject/index.js";
+/**
+ * `GAsyncResult` provides a base class for implementing asynchronous function results.
+ *
+ * Asynchronous operations are broken up into two separate operations
+ * which are chained together by a `GAsyncReadyCallback`. To begin
+ * an asynchronous operation, provide a `GAsyncReadyCallback` to the
+ * asynchronous function. This callback will be triggered when the
+ * operation has completed, and must be run in a later iteration of
+ * the thread-default main context (see
+ * [method@GLib.MainContext.push_thread_default]) from where the operation was
+ * initiated. It will be passed a `GAsyncResult` instance filled with the
+ * details of the operation's success or failure, the object the asynchronous
+ * function was started for and any error codes returned. The asynchronous
+ * callback function is then expected to call the corresponding `_finish()`
+ * function, passing the object the function was called for, the
+ * `GAsyncResult` instance, and (optionally) an `error` to grab any
+ * error conditions that may have occurred.
+ *
+ * The `_finish()` function for an operation takes the generic result
+ * (of type `GAsyncResult`) and returns the specific result that the
+ * operation in question yields (e.g. a [class@Gio.FileEnumerator] for a
+ * "enumerate children" operation). If the result or error status of the
+ * operation is not needed, there is no need to call the `_finish()`
+ * function; GIO will take care of cleaning up the result and error
+ * information after the `GAsyncReadyCallback` returns. You can pass
+ * `NULL` for the `GAsyncReadyCallback` if you don't need to take any
+ * action at all after the operation completes. Applications may also
+ * take a reference to the `GAsyncResult` and call `_finish()` later;
+ * however, the `_finish()` function may be called at most once.
+ *
+ * Example of a typical asynchronous operation flow:
+ *
+ * ```c
+ * void _theoretical_frobnitz_async (Theoretical         *t,
+ * GCancellable        *c,
+ * GAsyncReadyCallback  cb,
+ * gpointer             u);
+ *
+ * gboolean _theoretical_frobnitz_finish (Theoretical   *t,
+ * GAsyncResult  *res,
+ * GError       **e);
+ *
+ * static void
+ * frobnitz_result_func (GObject      *source_object,
+ * GAsyncResult *res,
+ * gpointer      user_data)
+ * {
+ * gboolean success = FALSE;
+ *
+ * success = _theoretical_frobnitz_finish (source_object, res, NULL);
+ *
+ * if (success)
+ * g_printf ("Hurray!\n");
+ * else
+ * g_printf ("Uh oh!\n");
+ *
+ * ...
+ *
+ * }
+ *
+ * int main (int argc, void *argv[])
+ * {
+ * ...
+ *
+ * _theoretical_frobnitz_async (theoretical_data,
+ * NULL,
+ * frobnitz_result_func,
+ * NULL);
+ *
+ * ...
+ * }
+ * ```
+ *
+ * The callback for an asynchronous operation is called only once, and is
+ * always called, even in the case of a cancelled operation. On cancellation
+ * the result is a `G_IO_ERROR_CANCELLED` error.
+ *
+ * ## I/O Priority
+ *
+ * Many I/O-related asynchronous operations have a priority parameter,
+ * which is used in certain cases to determine the order in which
+ * operations are executed. They are not used to determine system-wide
+ * I/O scheduling. Priorities are integers, with lower numbers indicating
+ * higher priority. It is recommended to choose priorities between
+ * `G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT`
+ * as a default.
+ */
 export declare class AsyncResult {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): AsyncResult;
+    /**
+     * Gets the source object from a [iface@Gio.AsyncResult].
+     */
     getSourceObject(): GObject.GObject | null;
+    /**
+     * Gets the user data from a [iface@Gio.AsyncResult].
+     */
     getUserData(): number | null;
+    /**
+     * Checks if `res` has the given `source_tag` (generally a function
+     * pointer indicating the function `res` was created by).
+     * @param sourceTag - an application-defined tag
+     */
     isTagged(sourceTag?: number | null): boolean;
+    /**
+     * If `res` is a [class@Gio.SimpleAsyncResult], this is equivalent to
+     * [method@Gio.SimpleAsyncResult.propagate_error]. Otherwise it returns
+     * `FALSE`.
+     *
+     * This can be used for legacy error handling in async `*_finish()`
+     * wrapper functions that traditionally handled [class@Gio.SimpleAsyncResult]
+     * error returns themselves rather than calling into the virtual method.
+     * This should not be used in new code; [iface@Gio.AsyncResult] errors that are
+     * set by virtual methods should also be extracted by virtual methods,
+     * to enable subclasses to chain up correctly.
+     */
     legacyPropagateError(): boolean;
 }

package/dist/generated/gio/async-result.js

@@ -1,6 +1,93 @@
 import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GAsyncResult` provides a base class for implementing asynchronous function results.
+ *
+ * Asynchronous operations are broken up into two separate operations
+ * which are chained together by a `GAsyncReadyCallback`. To begin
+ * an asynchronous operation, provide a `GAsyncReadyCallback` to the
+ * asynchronous function. This callback will be triggered when the
+ * operation has completed, and must be run in a later iteration of
+ * the thread-default main context (see
+ * [method@GLib.MainContext.push_thread_default]) from where the operation was
+ * initiated. It will be passed a `GAsyncResult` instance filled with the
+ * details of the operation's success or failure, the object the asynchronous
+ * function was started for and any error codes returned. The asynchronous
+ * callback function is then expected to call the corresponding `_finish()`
+ * function, passing the object the function was called for, the
+ * `GAsyncResult` instance, and (optionally) an `error` to grab any
+ * error conditions that may have occurred.
+ *
+ * The `_finish()` function for an operation takes the generic result
+ * (of type `GAsyncResult`) and returns the specific result that the
+ * operation in question yields (e.g. a [class@Gio.FileEnumerator] for a
+ * "enumerate children" operation). If the result or error status of the
+ * operation is not needed, there is no need to call the `_finish()`
+ * function; GIO will take care of cleaning up the result and error
+ * information after the `GAsyncReadyCallback` returns. You can pass
+ * `NULL` for the `GAsyncReadyCallback` if you don't need to take any
+ * action at all after the operation completes. Applications may also
+ * take a reference to the `GAsyncResult` and call `_finish()` later;
+ * however, the `_finish()` function may be called at most once.
+ *
+ * Example of a typical asynchronous operation flow:
+ *
+ * ```c
+ * void _theoretical_frobnitz_async (Theoretical         *t,
+ * GCancellable        *c,
+ * GAsyncReadyCallback  cb,
+ * gpointer             u);
+ *
+ * gboolean _theoretical_frobnitz_finish (Theoretical   *t,
+ * GAsyncResult  *res,
+ * GError       **e);
+ *
+ * static void
+ * frobnitz_result_func (GObject      *source_object,
+ * GAsyncResult *res,
+ * gpointer      user_data)
+ * {
+ * gboolean success = FALSE;
+ *
+ * success = _theoretical_frobnitz_finish (source_object, res, NULL);
+ *
+ * if (success)
+ * g_printf ("Hurray!\n");
+ * else
+ * g_printf ("Uh oh!\n");
+ *
+ * ...
+ *
+ * }
+ *
+ * int main (int argc, void *argv[])
+ * {
+ * ...
+ *
+ * _theoretical_frobnitz_async (theoretical_data,
+ * NULL,
+ * frobnitz_result_func,
+ * NULL);
+ *
+ * ...
+ * }
+ * ```
+ *
+ * The callback for an asynchronous operation is called only once, and is
+ * always called, even in the case of a cancelled operation. On cancellation
+ * the result is a `G_IO_ERROR_CANCELLED` error.
+ *
+ * ## I/O Priority
+ *
+ * Many I/O-related asynchronous operations have a priority parameter,
+ * which is used in certain cases to determine the order in which
+ * operations are executed. They are not used to determine system-wide
+ * I/O scheduling. Priorities are integers, with lower numbers indicating
+ * higher priority. It is recommended to choose priorities between
+ * `G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT`
+ * as a default.
+ */
 export class AsyncResult {
     ptr;
     constructor(ptr) {
@@ -9,6 +96,9 @@ export class AsyncResult {
     static fromPtr(ptr) {
         return new AsyncResult(ptr);
     }
+    /**
+     * Gets the source object from a [iface@Gio.AsyncResult].
+     */
     getSourceObject() {
         const ptr = call("libgio-2.0.so.0", "g_async_result_get_source_object", [
             {
@@ -20,6 +110,9 @@ export class AsyncResult {
             return null;
         return getObject(ptr, GObject.GObject);
     }
+    /**
+     * Gets the user data from a [iface@Gio.AsyncResult].
+     */
     getUserData() {
         return call("libgio-2.0.so.0", "g_async_result_get_user_data", [
             {
@@ -28,6 +121,11 @@ export class AsyncResult {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Checks if `res` has the given `source_tag` (generally a function
+     * pointer indicating the function `res` was created by).
+     * @param sourceTag - an application-defined tag
+     */
     isTagged(sourceTag) {
         return call("libgio-2.0.so.0", "g_async_result_is_tagged", [
             {
@@ -41,6 +139,18 @@ export class AsyncResult {
             },
         ], { type: "boolean" });
     }
+    /**
+     * If `res` is a [class@Gio.SimpleAsyncResult], this is equivalent to
+     * [method@Gio.SimpleAsyncResult.propagate_error]. Otherwise it returns
+     * `FALSE`.
+     *
+     * This can be used for legacy error handling in async `*_finish()`
+     * wrapper functions that traditionally handled [class@Gio.SimpleAsyncResult]
+     * error returns themselves rather than calling into the virtual method.
+     * This should not be used in new code; [iface@Gio.AsyncResult] errors that are
+     * set by virtual methods should also be extracted by virtual methods,
+     * to enable subclasses to chain up correctly.
+     */
     legacyPropagateError() {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_async_result_legacy_propagate_error", [