@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -1,15 +1,139 @@
+/**
+ * The #GThread struct represents a running thread. This struct
+ * is returned by g_thread_new() or g_thread_try_new(). You can
+ * obtain the #GThread struct representing the current thread by
+ * calling g_thread_self().
+ *
+ * GThread is refcounted, see g_thread_ref() and g_thread_unref().
+ * The thread represented by it holds a reference while it is running,
+ * and g_thread_join() consumes the reference that it is given, so
+ * it is normally not necessary to manage GThread references
+ * explicitly.
+ *
+ * The structure is opaque -- none of its fields may be directly
+ * accessed.
+ */
 export declare class Thread {
     ptr: unknown;
+    /**
+     * This function creates a new thread. The new thread starts by invoking
+     * `func` with the argument data. The thread will run until `func` returns
+     * or until g_thread_exit() is called from the new thread. The return value
+     * of `func` becomes the return value of the thread, which can be obtained
+     * with g_thread_join().
+     *
+     * The `name` can be useful for discriminating threads in a debugger.
+     * It is not used for other purposes and does not have to be unique.
+     * Some systems restrict the length of `name` to 16 bytes.
+     *
+     * If the thread can not be created the program aborts. See
+     * g_thread_try_new() if you want to attempt to deal with failures.
+     *
+     * If you are using threads to offload (potentially many) short-lived tasks,
+     * #GThreadPool may be more appropriate than manually spawning and tracking
+     * multiple #GThreads.
+     *
+     * To free the struct returned by this function, use g_thread_unref().
+     * Note that g_thread_join() implicitly unrefs the #GThread as well.
+     *
+     * New threads by default inherit their scheduler policy (POSIX) or thread
+     * priority (Windows) of the thread creating the new thread.
+     *
+     * This behaviour changed in GLib 2.64: before threads on Windows were not
+     * inheriting the thread priority but were spawned with the default priority.
+     * Starting with GLib 2.64 the behaviour is now consistent between Windows and
+     * POSIX and all threads inherit their parent thread's priority.
+     * @param name - an (optional) name for the new thread
+     * @param func - a function to execute in the new thread
+     * @param data - an argument to supply to the new thread
+     */
     constructor(func: (...args: unknown[]) => unknown, name?: string | null, data?: number | null);
     constructor(_args: unknown[]);
+    /**
+     * This function is the same as g_thread_new() except that
+     * it allows for the possibility of failure.
+     *
+     * If a thread can not be created (due to resource limits),
+     * `error` is set and %NULL is returned.
+     * @param name - an (optional) name for the new thread
+     * @param func - a function to execute in the new thread
+     * @param data - an argument to supply to the new thread
+     */
     static tryNew(func: (...args: unknown[]) => unknown, name?: string | null, data?: number | null): Thread;
     protected createPtr(_args: unknown[]): unknown;
     static errorQuark(): number;
+    /**
+     * Terminates the current thread.
+     *
+     * If another thread is waiting for us using g_thread_join() then the
+     * waiting thread will be woken up and get `retval` as the return value
+     * of g_thread_join().
+     *
+     * Calling g_thread_exit() with a parameter `retval` is equivalent to
+     * returning `retval` from the function @func, as given to g_thread_new().
+     *
+     * You must only call g_thread_exit() from a thread that you created
+     * yourself with g_thread_new() or related APIs. You must not call
+     * this function from a thread created with another threading library
+     * or or from within a #GThreadPool.
+     * @param retval - the return value of this thread
+     */
     static exit(retval?: number | null): void;
+    /**
+     * This function returns the #GThread corresponding to the
+     * current thread. Note that this function does not increase
+     * the reference count of the returned struct.
+     *
+     * This function will return a #GThread even for threads that
+     * were not created by GLib (i.e. those created by other threading
+     * APIs). This may be useful for thread identification purposes
+     * (i.e. comparisons) but you must not use GLib functions (such
+     * as g_thread_join()) on these threads.
+     */
     static self(): Thread;
+    /**
+     * Causes the calling thread to voluntarily relinquish the CPU, so
+     * that other threads can run.
+     *
+     * This function is often used as a method to make busy wait less evil.
+     */
     static _yield(): void;
+    /**
+     * Gets the name of the thread.
+     *
+     * This function is intended for debugging purposes.
+     */
     getName(): string;
+    /**
+     * Waits until `thread` finishes, i.e. the function @func, as
+     * given to g_thread_new(), returns or g_thread_exit() is called.
+     * If `thread` has already terminated, then g_thread_join()
+     * returns immediately.
+     *
+     * Any thread can wait for any other thread by calling g_thread_join(),
+     * not just its 'creator'. Calling g_thread_join() from multiple threads
+     * for the same `thread` leads to undefined behaviour.
+     *
+     * The value returned by `func` or given to g_thread_exit() is
+     * returned by this function.
+     *
+     * g_thread_join() consumes the reference to the passed-in @thread.
+     * This will usually cause the #GThread struct and associated resources
+     * to be freed. Use g_thread_ref() to obtain an extra reference if you
+     * want to keep the GThread alive beyond the g_thread_join() call.
+     */
     join(): number | null;
+    /**
+     * Increase the reference count on @thread.
+     */
     ref(): Thread;
+    /**
+     * Decrease the reference count on @thread, possibly freeing all
+     * resources associated with it.
+     *
+     * Note that each thread holds a reference to its #GThread while
+     * it is running, so it is safe to drop your own reference to it
+     * if you don't need it anymore.
+     */
     unref(): void;
 }

package/dist/generated/glib/thread.js

@@ -1,11 +1,36 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * The #GThread struct represents a running thread. This struct
+ * is returned by g_thread_new() or g_thread_try_new(). You can
+ * obtain the #GThread struct representing the current thread by
+ * calling g_thread_self().
+ *
+ * GThread is refcounted, see g_thread_ref() and g_thread_unref().
+ * The thread represented by it holds a reference while it is running,
+ * and g_thread_join() consumes the reference that it is given, so
+ * it is normally not necessary to manage GThread references
+ * explicitly.
+ *
+ * The structure is opaque -- none of its fields may be directly
+ * accessed.
+ */
 export class Thread {
     ptr;
     constructor(...args) {
         const _args = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
         this.ptr = this.createPtr(_args);
     }
+    /**
+     * This function is the same as g_thread_new() except that
+     * it allows for the possibility of failure.
+     *
+     * If a thread can not be created (due to resource limits),
+     * `error` is set and %NULL is returned.
+     * @param name - an (optional) name for the new thread
+     * @param func - a function to execute in the new thread
+     * @param data - an argument to supply to the new thread
+     */
     static tryNew(func, name, data) {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_thread_try_new", [
             {
@@ -47,6 +72,22 @@ export class Thread {
     static errorQuark() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_thread_error_quark", [], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Terminates the current thread.
+     *
+     * If another thread is waiting for us using g_thread_join() then the
+     * waiting thread will be woken up and get `retval` as the return value
+     * of g_thread_join().
+     *
+     * Calling g_thread_exit() with a parameter `retval` is equivalent to
+     * returning `retval` from the function @func, as given to g_thread_new().
+     *
+     * You must only call g_thread_exit() from a thread that you created
+     * yourself with g_thread_new() or related APIs. You must not call
+     * this function from a thread created with another threading library
+     * or or from within a #GThreadPool.
+     * @param retval - the return value of this thread
+     */
     static exit(retval) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_thread_exit", [
             {
@@ -56,6 +97,17 @@ export class Thread {
             },
         ], { type: "undefined" });
     }
+    /**
+     * This function returns the #GThread corresponding to the
+     * current thread. Note that this function does not increase
+     * the reference count of the returned struct.
+     *
+     * This function will return a #GThread even for threads that
+     * were not created by GLib (i.e. those created by other threading
+     * APIs). This may be useful for thread identification purposes
+     * (i.e. comparisons) but you must not use GLib functions (such
+     * as g_thread_join()) on these threads.
+     */
     static self() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_thread_self", [], {
             type: "boxed",
@@ -65,11 +117,22 @@ export class Thread {
         });
         return getObject(ptr, Thread);
     }
+    /**
+     * Causes the calling thread to voluntarily relinquish the CPU, so
+     * that other threads can run.
+     *
+     * This function is often used as a method to make busy wait less evil.
+     */
     static _yield() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_thread_yield", [], {
             type: "undefined",
         });
     }
+    /**
+     * Gets the name of the thread.
+     *
+     * This function is intended for debugging purposes.
+     */
     getName() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_thread_get_name", [
             {
@@ -78,6 +141,24 @@ export class Thread {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Waits until `thread` finishes, i.e. the function @func, as
+     * given to g_thread_new(), returns or g_thread_exit() is called.
+     * If `thread` has already terminated, then g_thread_join()
+     * returns immediately.
+     *
+     * Any thread can wait for any other thread by calling g_thread_join(),
+     * not just its 'creator'. Calling g_thread_join() from multiple threads
+     * for the same `thread` leads to undefined behaviour.
+     *
+     * The value returned by `func` or given to g_thread_exit() is
+     * returned by this function.
+     *
+     * g_thread_join() consumes the reference to the passed-in @thread.
+     * This will usually cause the #GThread struct and associated resources
+     * to be freed. Use g_thread_ref() to obtain an extra reference if you
+     * want to keep the GThread alive beyond the g_thread_join() call.
+     */
     join() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_thread_join", [
             {
@@ -86,6 +167,9 @@ export class Thread {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Increase the reference count on @thread.
+     */
     ref() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_thread_ref", [
             {
@@ -100,6 +184,14 @@ export class Thread {
         });
         return getObject(ptr, Thread);
     }
+    /**
+     * Decrease the reference count on @thread, possibly freeing all
+     * resources associated with it.
+     *
+     * Note that each thread holds a reference to its #GThread while
+     * it is running, so it is safe to drop your own reference to it
+     * if you don't need it anymore.
+     */
     unref() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_thread_unref", [
             {

package/dist/generated/glib/time-zone.d.ts

@@ -1,20 +1,237 @@
 import { Ref } from "@gtkx/native";
 import { TimeType } from "./enums.js";
+/**
+ * A `GTimeZone` represents a time zone, at no particular point in time.
+ *
+ * The `GTimeZone` struct is refcounted and immutable.
+ *
+ * Each time zone has an identifier (for example, ‘Europe/London’) which is
+ * platform dependent. See [ctor@GLib.TimeZone.new] for information on the
+ * identifier formats. The identifier of a time zone can be retrieved using
+ * [method@GLib.TimeZone.get_identifier].
+ *
+ * A time zone contains a number of intervals. Each interval has an abbreviation
+ * to describe it (for example, ‘PDT’), an offset to UTC and a flag indicating
+ * if the daylight savings time is in effect during that interval. A time zone
+ * always has at least one interval — interval 0. Note that interval abbreviations
+ * are not the same as time zone identifiers (apart from ‘UTC’), and cannot be
+ * passed to [ctor@GLib.TimeZone.new].
+ *
+ * Every UTC time is contained within exactly one interval, but a given
+ * local time may be contained within zero, one or two intervals (due to
+ * incontinuities associated with daylight savings time).
+ *
+ * An interval may refer to a specific period of time (eg: the duration
+ * of daylight savings time during 2010) or it may refer to many periods
+ * of time that share the same properties (eg: all periods of daylight
+ * savings time).  It is also possible (usually for political reasons)
+ * that some properties (like the abbreviation) change between intervals
+ * without other properties changing.
+ */
 export declare class TimeZone {
     ptr: unknown;
+    /**
+     * A version of g_time_zone_new_identifier() which returns the UTC time zone
+     * if `identifier` could not be parsed or loaded.
+     *
+     * If you need to check whether `identifier` was loaded successfully, use
+     * g_time_zone_new_identifier().
+     * @param identifier - a timezone identifier
+     */
     constructor(identifier?: string | null);
     constructor(_args: unknown[]);
+    /**
+     * Creates a #GTimeZone corresponding to @identifier. If `identifier` cannot be
+     * parsed or loaded, %NULL is returned.
+     *
+     * `identifier` can either be an RFC3339/ISO 8601 time offset or
+     * something that would pass as a valid value for the `TZ` environment
+     * variable (including %NULL).
+     *
+     * In Windows, `identifier` can also be the unlocalized name of a time
+     * zone for standard time, for example "Pacific Standard Time".
+     *
+     * Valid RFC3339 time offsets are `"Z"` (for UTC) or
+     * `"±hh:mm"`.  ISO 8601 additionally specifies
+     * `"±hhmm"` and `"±hh"`.  Offsets are
+     * time values to be added to Coordinated Universal Time (UTC) to get
+     * the local time.
+     *
+     * In UNIX, the `TZ` environment variable typically corresponds
+     * to the name of a file in the zoneinfo database, an absolute path to a file
+     * somewhere else, or a string in
+     * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
+     * There  are  no spaces in the specification. The name of standard
+     * and daylight savings time zone must be three or more alphabetic
+     * characters. Offsets are time values to be added to local time to
+     * get Coordinated Universal Time (UTC) and should be
+     * `"[±]hh[[:]mm[:ss]]"`.  Dates are either
+     * `"Jn"` (Julian day with n between 1 and 365, leap
+     * years not counted), `"n"` (zero-based Julian day
+     * with n between 0 and 365) or `"Mm.w.d"` (day d
+     * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
+     * 0 is a Sunday).  Times are in local wall clock time, the default is
+     * 02:00:00.
+     *
+     * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
+     * accepts POSIX format.  The Windows format uses US rules for all time
+     * zones; daylight savings time is 60 minutes behind the standard time
+     * with date and time of change taken from Pacific Standard Time.
+     * Offsets are time values to be added to the local time to get
+     * Coordinated Universal Time (UTC).
+     *
+     * g_time_zone_new_local() calls this function with the value of the
+     * `TZ` environment variable. This function itself is independent of
+     * the value of `TZ`, but if `identifier` is %NULL then `/etc/localtime`
+     * will be consulted to discover the correct time zone on UNIX and the
+     * registry will be consulted or GetTimeZoneInformation() will be used
+     * to get the local time zone on Windows.
+     *
+     * If intervals are not available, only time zone rules from `TZ`
+     * environment variable or other means, then they will be computed
+     * from year 1900 to 2037.  If the maximum year for the rules is
+     * available and it is greater than 2037, then it will followed
+     * instead.
+     *
+     * See
+     * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
+     * for a precise definition of valid RFC3339 time offsets
+     * (the `time-offset` expansion) and ISO 8601 for the
+     * full list of valid time offsets.  See
+     * The GNU C Library manual
+     * for an explanation of the possible
+     * values of the `TZ` environment variable. See
+     * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
+     * for the list of time zones on Windows.
+     *
+     * You should release the return value by calling g_time_zone_unref()
+     * when you are done with it.
+     * @param identifier - a timezone identifier
+     */
     static zoneNewIdentifier(identifier?: string | null): TimeZone;
+    /**
+     * Creates a #GTimeZone corresponding to local time.  The local time
+     * zone may change between invocations to this function; for example,
+     * if the system administrator changes it.
+     *
+     * This is equivalent to calling g_time_zone_new() with the value of
+     * the `TZ` environment variable (including the possibility of %NULL).
+     *
+     * You should release the return value by calling g_time_zone_unref()
+     * when you are done with it.
+     */
     static zoneNewLocal(): TimeZone;
+    /**
+     * Creates a #GTimeZone corresponding to the given constant offset from UTC,
+     * in seconds.
+     *
+     * This is equivalent to calling g_time_zone_new() with a string in the form
+     * `[+|-]hh[:mm[:ss]]`.
+     *
+     * It is possible for this function to fail if `seconds` is too big (greater than
+     * 24 hours), in which case this function will return the UTC timezone for
+     * backwards compatibility. To detect failures like this, use
+     * g_time_zone_new_identifier() directly.
+     * @param seconds - offset to UTC, in seconds
+     */
     static zoneNewOffset(seconds: number): TimeZone;
+    /**
+     * Creates a #GTimeZone corresponding to UTC.
+     *
+     * This is equivalent to calling g_time_zone_new() with a value like
+     * "Z", "UTC", "+00", etc.
+     *
+     * You should release the return value by calling g_time_zone_unref()
+     * when you are done with it.
+     */
     static zoneNewUtc(): TimeZone;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Finds an interval within `tz` that corresponds to the given @time_,
+     * possibly adjusting `time_` if required to fit into an interval.
+     * The meaning of `time_` depends on @type.
+     *
+     * This function is similar to g_time_zone_find_interval(), with the
+     * difference that it always succeeds (by making the adjustments
+     * described below).
+     *
+     * In any of the cases where g_time_zone_find_interval() succeeds then
+     * this function returns the same value, without modifying @time_.
+     *
+     * This function may, however, modify `time_` in order to deal with
+     * non-existent times.  If the non-existent local `time_` of 02:30 were
+     * requested on March 14th 2010 in Toronto then this function would
+     * adjust `time_` to be 03:00 and return the interval containing the
+     * adjusted time.
+     * @param type - the #GTimeType of @time_
+     * @param time_ - a pointer to a number of seconds since January 1, 1970
+     */
     adjustTime(type: TimeType, time_: Ref<number>): number;
+    /**
+     * Finds an interval within `tz` that corresponds to the given @time_.
+     * The meaning of `time_` depends on @type.
+     *
+     * If `type` is %G_TIME_TYPE_UNIVERSAL then this function will always
+     * succeed (since universal time is monotonic and continuous).
+     *
+     * Otherwise `time_` is treated as local time.  The distinction between
+     * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
+     * the case that the given `time_` is ambiguous.  In Toronto, for example,
+     * 01:30 on November 7th 2010 occurred twice (once inside of daylight
+     * savings time and the next, an hour later, outside of daylight savings
+     * time).  In this case, the different value of `type` would result in a
+     * different interval being returned.
+     *
+     * It is still possible for this function to fail.  In Toronto, for
+     * example, 02:00 on March 14th 2010 does not exist (due to the leap
+     * forward to begin daylight savings time).  -1 is returned in that
+     * case.
+     * @param type - the #GTimeType of @time_
+     * @param time_ - a number of seconds since January 1, 1970
+     */
     findInterval(type: TimeType, time_: number): number;
+    /**
+     * Determines the time zone abbreviation to be used during a particular
+     * `interval` of time in the time zone @tz.
+     *
+     * For example, in Toronto this is currently "EST" during the winter
+     * months and "EDT" during the summer months when daylight savings time
+     * is in effect.
+     * @param interval - an interval within the timezone
+     */
     getAbbreviation(interval: number): string;
+    /**
+     * Get the identifier of this #GTimeZone, as passed to g_time_zone_new().
+     * If the identifier passed at construction time was not recognised, `UTC` will
+     * be returned. If it was %NULL, the identifier of the local timezone at
+     * construction time will be returned.
+     *
+     * The identifier will be returned in the same format as provided at
+     * construction time: if provided as a time offset, that will be returned by
+     * this function.
+     */
     getIdentifier(): string;
+    /**
+     * Determines the offset to UTC in effect during a particular `interval` of time in the time zone @tz.
+     *
+     * The offset is the number of seconds that you add to UTC time to
+     * arrive at local time for `tz` (ie: negative numbers for time zones
+     * west of GMT, positive numbers for east).
+     * @param interval - an interval within the timezone
+     */
     getOffset(interval: number): number;
+    /**
+     * Determines if daylight savings time is in effect during a particular
+     * `interval` of time in the time zone @tz.
+     * @param interval - an interval within the timezone
+     */
     isDst(interval: number): boolean;
+    /**
+     * Increases the reference count on @tz.
+     */
     ref(): TimeZone;
+    /**
+     * Decreases the reference count on @tz.
+     */
     unref(): void;
 }