179 lines
6.6 KiB
TypeScript
179 lines
6.6 KiB
TypeScript
/// <reference path="./gobject-2.0.d.ts" />
|
|
|
|
declare module 'system' {
|
|
import type GObject from 'gi://GObject?version=2.0';
|
|
|
|
/**
|
|
* This property contains the name of the script as it was invoked from the command
|
|
* line. In C and other languages, this information is contained in the first element of
|
|
* the platform's equivalent of argv, but GJS's ARGV only contains the
|
|
* subsequent command-line arguments. In other words, `ARGV[0]` in GJS is the same as `argv[1]` in C.
|
|
* @version Gjs 1.68
|
|
*/
|
|
export const programInvocationName: string;
|
|
|
|
/**
|
|
* This property contains version information about GJS.
|
|
*/
|
|
export const version: number;
|
|
|
|
/**
|
|
* The full path of the executed program.
|
|
* @version Gjs 1.68
|
|
*/
|
|
export const programPath: string | null;
|
|
|
|
/**
|
|
* A list of arguments passed to the current process.
|
|
* This is effectively an alias for the global `ARGV`, which is misleading in that
|
|
* it is not equivalent to the platform'`s` argv.
|
|
* @version Gjs 1.68
|
|
*/
|
|
export const programArgs: string[];
|
|
|
|
/**
|
|
* Return the memory address of any object as a string.
|
|
* This is the address of memory being managed by the JavaScript engine, which may
|
|
* represent a wrapper around memory elsewhere.
|
|
* **Caution**, don't use this as a unique identifier!
|
|
* JavaScript's garbage collector can move objects around in memory, or
|
|
* deduplicate identical objects, so this value may change during the execution
|
|
* of a program.
|
|
* @param o Any Object
|
|
* @returns A hexadecimal string (e.g. `0xb4f170f0`)
|
|
*/
|
|
export function addressOf(o: object): string;
|
|
|
|
/**
|
|
* Return the memory address of any GObject as a string.
|
|
* See also {@link addressOf}
|
|
* @param o Any {@link GObject.Object}-derived instance
|
|
* @returns A hexadecimal string (e.g. `0xb4f170f0`)
|
|
* @version Gjs 1.58
|
|
*/
|
|
export function addressOfGObject(o: GObject.Object): string;
|
|
|
|
/**
|
|
* Inserts a breakpoint instruction into the code.
|
|
* **Warning**: Using this function in code run outside of GDB will abort the process.
|
|
* With `System.breakpoint()` calls in your code, a GJS program can be debugged by
|
|
* running it in GDB:
|
|
* ```bash
|
|
* gdb --args gjs script.js
|
|
* ```
|
|
* Once GDB has started, you can start the program with run. When the debugger
|
|
* hits a breakpoint it will pause execution of the process and return to the
|
|
* prompt. You can then use the standard `backtrace` command to print a C++ stack
|
|
* trace, or use `call gjs_dumpstack()` to print a JavaScript stack trace:
|
|
* ```bash
|
|
* (gdb) run
|
|
* tarting program: /usr/bin/gjs -m script.js
|
|
* ...
|
|
* Thread 1 "gjs" received signal SIGTRAP, Trace/breakpoint trap.
|
|
* (gdb) call gjs_dumpstack()
|
|
* == Stack trace for context 0x5555555b7180 ==
|
|
* #0 555555640548 i file:///path/to/script.js:4 (394b8c3cc060 @ 12)
|
|
* #1 5555556404c8 i file:///path/to/script.js:7 (394b8c3cc0b0 @ 6)
|
|
* #2 7fffffffd3a0 b self-hosted:2408 (394b8c3a9650 @ 753)
|
|
* #3 5555556403e8 i self-hosted:2355 (394b8c3a9600 @ 375)
|
|
* (gdb)
|
|
* ```
|
|
* To continue executing the program, you can use the `continue` (or `cont`) to
|
|
* resume the process and debug further.
|
|
* Remember that if you run the program outside of GDB, it will abort at the
|
|
* breakpoint, so make sure to remove any calls to `System.breakpoint()` when
|
|
* you're done debugging.
|
|
*/
|
|
export function breakpoint(): void;
|
|
|
|
/**
|
|
* Clears the timezone cache.
|
|
* This is a workaround for SpiderMonkey Bug [#1004706](https://bugzilla.mozilla.org/show_bug.cgi?id=1004706).
|
|
*/
|
|
export function clearDateCaches(): void;
|
|
|
|
/** Runs the garbage collector */
|
|
export function gc(): void;
|
|
|
|
/**
|
|
* Return the reference count of any GObject-derived type. When an object's
|
|
* reference count is zero, it is cleaned up and erased from memory.
|
|
* @param o A {@link GObject.Object}
|
|
*/
|
|
export function refcount(o: GObject.Object): number;
|
|
/**
|
|
* See also: The [heapgraph](https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/tools/heapgraph.md) utility in the GJS repository.
|
|
* Dump a representation of internal heap memory. If `path` is not given, GJS will
|
|
* write the contents to `stdout`.
|
|
* @param path Optional file path
|
|
*/
|
|
export function dumpHeap(path?: string): void;
|
|
|
|
/**
|
|
* Dump internal garbage collector statistics. If `path` is not given, GJS will
|
|
* write the contents to `stdout`.
|
|
* @param path Optional file path
|
|
* @version Gjs 1.70
|
|
* @example Output:
|
|
* ```json
|
|
* {
|
|
* "gcBytes": 794624,
|
|
* "gcMaxBytes": 4294967295,
|
|
* "mallocBytes": 224459,
|
|
* "gcIsHighFrequencyMode": true,
|
|
* "gcNumber": 1,
|
|
* "majorGCCount": 1,
|
|
* "minorGCCount": 1,
|
|
* "sliceCount": 1,
|
|
* "zone": {
|
|
* "gcBytes": 323584,
|
|
* "gcTriggerBytes": 42467328,
|
|
* "gcAllocTrigger": 36097228.8,
|
|
* "mallocBytes": 120432,
|
|
* "mallocTriggerBytes": 59768832,
|
|
* "gcNumber": 1
|
|
* }
|
|
* }
|
|
* ```
|
|
*
|
|
*/
|
|
export function dumpMemoryInfo(path?: string): void;
|
|
|
|
/**
|
|
* This works the same as C's exit() function; exits the program, passing a
|
|
* certain error code to the shell. The shell expects the error code to be zero if
|
|
* there was no error, or non-zero (any value you please) to indicate an error.
|
|
*
|
|
* This value is used by other tools such as `make`; if `make` calls a program that
|
|
* returns a non-zero error code, then `make` aborts the build.
|
|
* @param code An exit code
|
|
*/
|
|
export function exit(code: number): never;
|
|
|
|
/**
|
|
* The System module provides common low-level facilities such as access to
|
|
* process arguments and exit(), as well as a number of useful functions and
|
|
* properties for debugging.
|
|
*
|
|
* Note that the majority of the functions and properties in this module should not
|
|
* be used in normal operation of a GJS application.
|
|
*/
|
|
const System: {
|
|
programInvocationName: typeof programInvocationName;
|
|
version: typeof version;
|
|
programPath: typeof programPath;
|
|
programArgs: typeof programArgs;
|
|
addressOf: typeof addressOf;
|
|
addressOfGObject: typeof addressOfGObject;
|
|
breakpoint: typeof breakpoint;
|
|
clearDateCaches: typeof clearDateCaches;
|
|
gc: typeof gc;
|
|
refcount: typeof refcount;
|
|
dumpHeap: typeof dumpHeap;
|
|
dumpMemoryInfo: typeof dumpMemoryInfo;
|
|
exit: typeof exit;
|
|
};
|
|
|
|
export default System;
|
|
}
|