@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/glib/source.d.ts

@@ -1,43 +1,549 @@
 import { IOCondition } from "./enums.js";
 import { MainContext } from "./main-context.js";
 import { PollFD } from "./poll-fd.js";
+/**
+ * The `GSource` struct is an opaque data type
+ * representing an event source.
+ */
 export declare class Source {
     ptr: unknown;
+    /**
+     * Creates a new [struct@GLib.Source] structure.
+     *
+     * The size is specified to
+     * allow creating structures derived from [struct@GLib.Source] that contain
+     * additional data. The size passed in must be at least
+     * `sizeof (GSource)`.
+     *
+     * The source will not initially be associated with any [struct@GLib.MainContext]
+     * and must be added to one with [method@GLib.Source.attach] before it will be
+     * executed.
+     * @param sourceFuncs - structure containing functions that implement
+     * @param structSize - size of the [struct@GLib.Source] structure to create, in bytes
+     */
     constructor(sourceFuncs: number, structSize: number);
     constructor(_args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Removes the source with the given ID from the default main context.
+     *
+     * You must
+     * use [method@GLib.Source.destroy] for sources added to a non-default main context.
+     *
+     * The ID of a [struct@GLib.Source] is given by [method@GLib.Source.get_id], or will be
+     * returned by the functions [method@GLib.Source.attach], [func@GLib.idle_add],
+     * [func@GLib.idle_add_full], [func@GLib.timeout_add],
+     * [func@GLib.timeout_add_full], [func@GLib.child_watch_add],
+     * [func@GLib.child_watch_add_full], [func@GLib.io_add_watch], and
+     * [func@GLib.io_add_watch_full].
+     *
+     * It is a programmer error to attempt to remove a non-existent source.
+     *
+     * More specifically: source IDs can be reissued after a source has been
+     * destroyed and therefore it is never valid to use this function with a
+     * source ID which may have already been removed.  An example is when
+     * scheduling an idle to run in another thread with [func@GLib.idle_add]: the
+     * idle may already have run and been removed by the time this function
+     * is called on its (now invalid) source ID.  This source ID may have
+     * been reissued, leading to the operation being performed against the
+     * wrong source.
+     * @param tag - the ID of the source to remove.
+     */
     static remove(tag: number): boolean;
+    /**
+     * Removes a source from the default main loop context given the
+     * source functions and user data.
+     *
+     * If multiple sources exist with the same source functions and user data, only
+     * one will be destroyed.
+     * @param funcs - the `source_funcs` passed to [ctor@GLib.Source.new]
+     * @param userData - the user data for the callback
+     */
     static removeByFuncsUserData(funcs: number, userData?: number | null): boolean;
+    /**
+     * Removes a source from the default main loop context given the user
+     * data for the callback.
+     *
+     * If multiple sources exist with the same user data, only one will be destroyed.
+     * @param userData - the user_data for the callback
+     */
     static removeByUserData(userData?: number | null): boolean;
+    /**
+     * Sets the name of a source using its ID.
+     *
+     * This is a convenience utility to set source names from the return
+     * value of [func@GLib.idle_add], [func@GLib.timeout_add], etc.
+     *
+     * It is a programmer error to attempt to set the name of a non-existent
+     * source.
+     *
+     * More specifically: source IDs can be reissued after a source has been
+     * destroyed and therefore it is never valid to use this function with a
+     * source ID which may have already been removed.  An example is when
+     * scheduling an idle to run in another thread with [func@GLib.idle_add]: the
+     * idle may already have run and been removed by the time this function
+     * is called on its (now invalid) source ID.  This source ID may have
+     * been reissued, leading to the operation being performed against the
+     * wrong source.
+     * @param tag - a source ID
+     * @param name - debug name for the source
+     */
     static setNameById(tag: number, name: string): void;
+    /**
+     * Adds `child_source` to `source` as a ‘polled’ source.
+     *
+     * When `source` is added to a [struct@GLib.MainContext], `child_source` will be
+     * automatically added with the same priority. When `child_source` is triggered,
+     * it will cause `source` to dispatch (in addition to calling its own callback),
+     * and when `source` is destroyed, it will destroy `child_source` as well.
+     *
+     * The `source` will also still be dispatched if its own prepare/check functions
+     * indicate that it is ready.
+     *
+     * If you don’t need `child_source` to do anything on its own when it
+     * triggers, you can call `g_source_set_dummy_callback()` on it to set a
+     * callback that does nothing (except return true if appropriate).
+     *
+     * The `source` will hold a reference on `child_source` while `child_source` is attached to it.
+     *
+     * This API is only intended to be used by implementations of [struct@GLib.Source].
+     * Do not call this API on a [struct@GLib.Source] that you did not create.
+     * @param childSource - a second source that `source` should ‘poll’
+     */
     addChildSource(childSource: Source): void;
+    /**
+     * Adds a file descriptor to the set of file descriptors polled for
+     * this source.
+     *
+     * This is usually combined with [ctor@GLib.Source.new] to add an
+     * event source. The event source’s check function will typically test
+     * the `revents` field in the [struct@GLib.PollFD] struct and return true if
+     * events need to be processed.
+     *
+     * This API is only intended to be used by implementations of [struct@GLib.Source].
+     * Do not call this API on a [struct@GLib.Source] that you did not create.
+     *
+     * Using this API forces the linear scanning of event sources on each
+     * main loop iteration.  Newly-written event sources should try to use
+     * `g_source_add_unix_fd()` instead of this API.
+     * @param fd - a [struct@GLib.PollFD] structure holding information about a file
+     */
     addPoll(fd: PollFD): void;
+    /**
+     * Monitors `fd` for the IO events in @events.
+     *
+     * The tag returned by this function can be used to remove or modify the
+     * monitoring of the `fd` using [method@GLib.Source.remove_unix_fd] or
+     * [method@GLib.Source.modify_unix_fd].
+     *
+     * It is not necessary to remove the file descriptor before destroying the
+     * source; it will be cleaned up automatically.
+     *
+     * This API is only intended to be used by implementations of [struct@GLib.Source].
+     * Do not call this API on a [struct@GLib.Source] that you did not create.
+     *
+     * As the name suggests, this function is not available on Windows.
+     * @param fd - the file descriptor to monitor
+     * @param events - an event mask
+     */
     addUnixFd(fd: number, events: IOCondition): number;
+    /**
+     * Adds a [struct@GLib.Source] to a `context` so that it will be executed within
+     * that context.
+     *
+     * Remove it by calling [method@GLib.Source.destroy].
+     *
+     * This function is safe to call from any thread, regardless of which thread
+     * the `context` is running in.
+     * @param context - a main context (if `NULL`, the global-default
+     */
     attach(context?: MainContext | null): number;
+    /**
+     * Removes a source from its [struct@GLib.MainContext], if any, and marks it as
+     * destroyed.
+     *
+     * The source cannot be subsequently added to another
+     * context. It is safe to call this on sources which have already been
+     * removed from their context.
+     *
+     * This does not unref the [struct@GLib.Source]: if you still hold a reference,
+     * use [method@GLib.Source.unref] to drop it.
+     *
+     * This function is safe to call from any thread, regardless of which thread
+     * the [struct@GLib.MainContext] is running in.
+     *
+     * If the source is currently attached to a [struct@GLib.MainContext],
+     * destroying it will effectively unset the callback similar to calling
+     * [method@GLib.Source.set_callback]. This can mean, that the data’s
+     * [callback@GLib.DestroyNotify] gets called right away.
+     */
     destroy(): void;
+    /**
+     * Gets a reference to the [struct@GLib.MainContext] with which the source is
+     * associated.
+     *
+     * You can call this on a source that has been destroyed. You can
+     * always call this function on the source returned from
+     * [func@GLib.main_current_source].
+     */
     dupContext(): MainContext | null;
+    /**
+     * Checks whether a source is allowed to be called recursively.
+     *
+     * See [method@GLib.Source.set_can_recurse].
+     */
     getCanRecurse(): boolean;
+    /**
+     * Gets the [struct@GLib.MainContext] with which the source is associated.
+     *
+     * You can call this on a source that has been destroyed, provided
+     * that the [struct@GLib.MainContext] it was attached to still exists (in which
+     * case it will return that [struct@GLib.MainContext]). In particular, you can
+     * always call this function on the source returned from
+     * [func@GLib.main_current_source]. But calling this function on a source
+     * whose [struct@GLib.MainContext] has been destroyed is an error.
+     *
+     * If the associated [struct@GLib.MainContext] could be destroy concurrently from
+     * a different thread, then this function is not safe to call and
+     * [method@GLib.Source.dup_context] should be used instead.
+     */
     getContext(): MainContext | null;
+    /**
+     * This function ignores `source` and is otherwise the same as
+     * [func@GLib.get_current_time].
+     * @param timeval - [struct@GLib.TimeVal] structure in which to store current time
+     */
     getCurrentTime(timeval: number): void;
+    /**
+     * Returns the numeric ID for a particular source.
+     *
+     * The ID of a source
+     * is a positive integer which is unique within a particular main loop
+     * context. The reverse mapping from ID to source is done by
+     * [method@GLib.MainContext.find_source_by_id].
+     *
+     * You can only call this function while the source is associated to a
+     * [struct@GLib.MainContext] instance; calling this function before
+     * [method@GLib.Source.attach] or after [method@GLib.Source.destroy] yields
+     * undefined behavior. The ID returned is unique within the
+     * [struct@GLib.MainContext] instance passed to [method@GLib.Source.attach].
+     */
     getId(): number;
+    /**
+     * Gets a name for the source, used in debugging and profiling.
+     *
+     * The
+     * name may be `NULL` if it has never been set with [method@GLib.Source.set_name].
+     */
     getName(): string | null;
+    /**
+     * Gets the priority of a source.
+     */
     getPriority(): number;
+    /**
+     * Gets the ‘ready time’ of @source, as set by
+     * [method@GLib.Source.set_ready_time].
+     *
+     * Any time before or equal to the current monotonic time (including zero)
+     * is an indication that the source will fire immediately.
+     */
     getReadyTime(): number;
+    /**
+     * Gets the time to be used when checking this source.
+     *
+     * The advantage of
+     * calling this function over calling [func@GLib.get_monotonic_time] directly is
+     * that when checking multiple sources, GLib can cache a single value
+     * instead of having to repeatedly get the system monotonic time.
+     *
+     * The time here is the system monotonic time, if available, or some
+     * other reasonable alternative otherwise.  See [func@GLib.get_monotonic_time].
+     */
     getTime(): number;
+    /**
+     * Returns whether `source` has been destroyed.
+     *
+     * This is important when you operate upon your objects
+     * from within idle handlers, but may have freed the object
+     * before the dispatch of your idle handler.
+     *
+     * ```c
+     * static gboolean
+     * idle_callback (gpointer data)
+     * {
+     * SomeWidget *self = data;
+     *
+     * g_mutex_lock (&self->idle_id_mutex);
+     * // do stuff with self
+     * self->idle_id = 0;
+     * g_mutex_unlock (&self->idle_id_mutex);
+     *
+     * return G_SOURCE_REMOVE;
+     * }
+     *
+     * static void
+     * some_widget_do_stuff_later (SomeWidget *self)
+     * {
+     * g_mutex_lock (&self->idle_id_mutex);
+     * self->idle_id = g_idle_add (idle_callback, self);
+     * g_mutex_unlock (&self->idle_id_mutex);
+     * }
+     *
+     * static void
+     * some_widget_init (SomeWidget *self)
+     * {
+     * g_mutex_init (&self->idle_id_mutex);
+     *
+     * // ...
+     * }
+     *
+     * static void
+     * some_widget_finalize (GObject *object)
+     * {
+     * SomeWidget *self = SOME_WIDGET (object);
+     *
+     * if (self->idle_id)
+     * g_source_remove (self->idle_id);
+     *
+     * g_mutex_clear (&self->idle_id_mutex);
+     *
+     * G_OBJECT_CLASS (parent_class)->finalize (object);
+     * }
+     * ```
+     *
+     * This will fail in a multi-threaded application if the
+     * widget is destroyed before the idle handler fires due
+     * to the use after free in the callback. A solution, to
+     * this particular problem, is to check to if the source
+     * has already been destroy within the callback.
+     *
+     * ```c
+     * static gboolean
+     * idle_callback (gpointer data)
+     * {
+     * SomeWidget *self = data;
+     *
+     * g_mutex_lock (&self->idle_id_mutex);
+     * if (!g_source_is_destroyed (g_main_current_source ()))
+     * {
+     * // do stuff with self
+     * }
+     * g_mutex_unlock (&self->idle_id_mutex);
+     *
+     * return FALSE;
+     * }
+     * ```
+     *
+     * Calls to this function from a thread other than the one acquired by the
+     * [struct@GLib.MainContext] the [struct@GLib.Source] is attached to are typically
+     * redundant, as the source could be destroyed immediately after this function
+     * returns. However, once a source is destroyed it cannot be un-destroyed, so
+     * this function can be used for opportunistic checks from any thread.
+     */
     isDestroyed(): boolean;
+    /**
+     * Updates the event mask to watch for the file descriptor identified by @tag.
+     *
+     * The `tag` is the tag returned from [method@GLib.Source.add_unix_fd].
+     *
+     * If you want to remove a file descriptor, don’t set its event mask to zero.
+     * Instead, call [method@GLib.Source.remove_unix_fd].
+     *
+     * This API is only intended to be used by implementations of [struct@GLib.Source].
+     * Do not call this API on a [struct@GLib.Source] that you did not create.
+     *
+     * As the name suggests, this function is not available on Windows.
+     * @param tag - the tag from [method@GLib.Source.add_unix_fd]
+     * @param newEvents - the new event mask to watch
+     */
     modifyUnixFd(tag: number, newEvents: IOCondition): void;
+    /**
+     * Queries the events reported for the file descriptor corresponding to `tag` on `source` during the last poll.
+     *
+     * The return value of this function is only defined when the function
+     * is called from the check or dispatch functions for @source.
+     *
+     * This API is only intended to be used by implementations of [struct@GLib.Source].
+     * Do not call this API on a [struct@GLib.Source] that you did not create.
+     *
+     * As the name suggests, this function is not available on Windows.
+     * @param tag - the tag from [method@GLib.Source.add_unix_fd]
+     */
     queryUnixFd(tag: number): IOCondition;
+    /**
+     * Increases the reference count on a source by one.
+     */
     ref(): Source;
+    /**
+     * Detaches `child_source` from `source` and destroys it.
+     *
+     * This API is only intended to be used by implementations of [struct@GLib.Source].
+     * Do not call this API on a [struct@GLib.Source] that you did not create.
+     * @param childSource - a source previously passed to
+     */
     removeChildSource(childSource: Source): void;
+    /**
+     * Removes a file descriptor from the set of file descriptors polled for
+     * this source.
+     *
+     * This API is only intended to be used by implementations of [struct@GLib.Source].
+     * Do not call this API on a [struct@GLib.Source] that you did not create.
+     * @param fd - a [struct@GLib.PollFD] structure previously passed to
+     */
     removePoll(fd: PollFD): void;
+    /**
+     * Reverses the effect of a previous call to [method@GLib.Source.add_unix_fd].
+     *
+     * You only need to call this if you want to remove a file descriptor from being
+     * watched while keeping the same source around.  In the normal case you
+     * will just want to destroy the source.
+     *
+     * This API is only intended to be used by implementations of [struct@GLib.Source].
+     * Do not call this API on a [struct@GLib.Source] that you did not create.
+     *
+     * As the name suggests, this function is not available on Windows.
+     * @param tag - the tag from [method@GLib.Source.add_unix_fd]
+     */
     removeUnixFd(tag: number): void;
+    /**
+     * Sets the callback function for a source. The callback for a source is
+     * called from the source’s dispatch function.
+     *
+     * The exact type of `func` depends on the type of source; ie. you
+     * should not count on `func` being called with `data` as its first
+     * parameter. Cast `func` with [func@GLib.SOURCE_FUNC] to avoid warnings about
+     * incompatible function types.
+     *
+     * See main loop memory management for details
+     * on how to handle memory management of @data.
+     *
+     * Typically, you won’t use this function. Instead use functions specific
+     * to the type of source you are using, such as [func@GLib.idle_add] or
+     * [func@GLib.timeout_add].
+     *
+     * It is safe to call this function multiple times on a source which has already
+     * been attached to a context. The changes will take effect for the next time
+     * the source is dispatched after this call returns.
+     *
+     * Note that [method@GLib.Source.destroy] for a currently attached source has the effect
+     * of also unsetting the callback.
+     * @param func - a callback function
+     * @param data - the data to pass to callback function
+     * @param notify - a function to call when `data` is no longer in use
+     */
     setCallback(func: (...args: unknown[]) => unknown, data?: number | null, notify?: (...args: unknown[]) => unknown | null): void;
+    /**
+     * Sets the callback function storing the data as a reference counted callback
+     * ‘object’.
+     *
+     * This is used internally. Note that calling
+     * [method@GLib.Source.set_callback_indirect] assumes
+     * an initial reference count on @callback_data, and thus
+     * `callback_funcs->unref` will eventually be called once more than
+     * `callback_funcs->ref`.
+     *
+     * It is safe to call this function multiple times on a source which has already
+     * been attached to a context. The changes will take effect for the next time
+     * the source is dispatched after this call returns.
+     * @param callbackData - pointer to callback data ‘object’
+     * @param callbackFuncs - functions for reference counting `callback_data`   and getting the callback and data
+     */
     setCallbackIndirect(callbackFuncs: number, callbackData?: number | null): void;
+    /**
+     * Sets whether a source can be called recursively.
+     *
+     * If `can_recurse` is true, then while the source is being dispatched then this
+     * source will be processed normally. Otherwise, all processing of this
+     * source is blocked until the dispatch function returns.
+     * @param canRecurse - whether recursion is allowed for this source
+     */
     setCanRecurse(canRecurse: boolean): void;
+    /**
+     * Sets the source functions of an unattached source.
+     *
+     * These can be used to override the default implementations for the type
+     * of @source.
+     * @param funcs - the new source functions
+     */
     setFuncs(funcs: number): void;
+    /**
+     * Sets a name for the source, used in debugging and profiling.
+     *
+     * The name defaults to `NULL`.
+     *
+     * The source name should describe in a human-readable way
+     * what the source does. For example, ‘X11 event queue’
+     * or ‘GTK repaint idle handler’.
+     *
+     * It is permitted to call this function multiple times, but is not
+     * recommended due to the potential performance impact.  For example,
+     * one could change the name in the `check` function of a
+     * [struct@GLib.SourceFuncs] to include details like the event type in the
+     * source name.
+     *
+     * Use caution if changing the name while another thread may be
+     * accessing it with [method@GLib.Source.get_name]; that function does not copy
+     * the value, and changing the value will free it while the other thread
+     * may be attempting to use it.
+     *
+     * Also see [method@GLib.Source.set_static_name].
+     * @param name - debug name for the source
+     */
     setName(name: string): void;
+    /**
+     * Sets the priority of a source.
+     *
+     * While the main loop is being run, a
+     * source will be dispatched if it is ready to be dispatched and no
+     * sources at a higher (numerically smaller) priority are ready to be
+     * dispatched.
+     *
+     * A child source always has the same priority as its parent.  It is not
+     * permitted to change the priority of a source once it has been added
+     * as a child of another source.
+     * @param priority - the new priority
+     */
     setPriority(priority: number): void;
+    /**
+     * Sets a source to be dispatched when the given monotonic time is
+     * reached (or passed).
+     *
+     * If the monotonic time is in the past (as it
+     * always will be if `ready_time` is `0`) then the source will be
+     * dispatched immediately.
+     *
+     * If `ready_time` is `-1` then the source is never woken up on the basis
+     * of the passage of time.
+     *
+     * Dispatching the source does not reset the ready time.  You should do
+     * so yourself, from the source dispatch function.
+     *
+     * Note that if you have a pair of sources where the ready time of one
+     * suggests that it will be delivered first but the priority for the
+     * other suggests that it would be delivered first, and the ready time
+     * for both sources is reached during the same main context iteration,
+     * then the order of dispatch is undefined.
+     *
+     * It is a no-op to call this function on a [struct@GLib.Source] which has
+     * already been destroyed with [method@GLib.Source.destroy].
+     *
+     * This API is only intended to be used by implementations of [struct@GLib.Source].
+     * Do not call this API on a [struct@GLib.Source] that you did not create.
+     * @param readyTime - the monotonic time at which the source will be ready;
+     */
     setReadyTime(readyTime: number): void;
+    /**
+     * A variant of [method@GLib.Source.set_name] that does not
+     * duplicate the @name, and can only be used with
+     * string literals.
+     * @param name - debug name for the source
+     */
     setStaticName(name: string): void;
+    /**
+     * Decreases the reference count of a source by one.
+     *
+     * If the resulting reference count is zero the source and associated
+     * memory will be destroyed.
+     */
     unref(): void;
 }