Debugger Module

This module provides runtime debug functionality for ucode scripts.

Functions can be individually imported and directly accessed using the named import syntax:

import { memdump, traceback } from 'debug';

let stacktrace = traceback(1);

memdump("/tmp/dump.txt");

Alternatively, the module namespace can be imported using a wildcard import statement:

import * as debug from 'debug';

let stacktrace = debug.traceback(1);

debug.memdump("/tmp/dump.txt");

Additionally, the debug module namespace may also be imported by invoking the ucode interpreter with the -ldebug switch.

Upon loading, the debug module will register a SIGUSR2 signal handler which, upon receipt of the signal, will write a memory dump of the currently running program to /tmp/ucode.$timestamp.$pid.memdump. This default behavior can be inhibited by setting the UCODE_DEBUG_MEMDUMP_ENABLED environment variable to 0 when starting the process. The memory dump signal and output directory can be overridden with the UCODE_DEBUG_MEMDUMP_SIGNAL and UCODE_DEBUG_MEMDUMP_PATH environment variables respectively.

Source: lib/debug.c, line 17

Methods

getinfo(value) → {ValueInformation}nullable

Obtain information about the given value.

The getinfo() function allows querying internal information about the given ucode value, such as the current reference count, the mark bit state etc.

Returns a dictionary with value type specific details.

Returns null if a null value was provided.

Parameters:

Name	Type	Description
`value`	*	The value to query information for.

Returns: ValueInformation

Source: lib/debug.c, line 942

getlocal(levelopt, variable) → {LocalInfo}nullable

Obtain local variable.

The getlocal() function retrieves information about the specified local variable at the given call stack depth.

The call stack depth specifies the amount of levels up local variables should be queried. A value of 0 refers to this getlocal() function call itself, 1 to the function calling getlocal() and so on.

The variable to query might be either specified by name or by its index with index numbers following the source code declaration order.

Returns a dictionary holding information about the given variable.

Returns null if the stack depth exceeds the size of the current call stack.

Returns null if the invocation at the given stack depth is a C call.

Returns null if the given variable name is not found or the given variable index is invalid.

Parameters:

Name	Type	Description
`level`	number	(optional, default: `1`) The amount of call stack levels up local variables should be queried.
`variable`	string \| number	The variable index or variable name to obtain information for.

Returns: LocalInfo

Source: lib/debug.c, line 1335

getupval(target, variable) → {UpvalInfo}nullable

Obtain captured variable (upvalue).

The getupval() function retrieves information about the specified captured variable associated with the given function value or the invoked function at the given call stack depth.

The call stack depth specifies the amount of levels up the function should be selected to query associated captured variables for. A value of 0 refers to this getupval() function call itself, 1 to the function calling getupval() and so on.

The variable to query might be either specified by name or by its index with index numbers following the source code declaration order.

Returns a dictionary holding information about the given variable.

Returns null if the given function value is not a closure.

Returns null if the stack depth exceeds the size of the current call stack.

Returns null if the invocation at the given stack depth is not a closure.

Returns null if the given variable name is not found or the given variable index is invalid.

Parameters:

Name	Type	Description
`target`	function \| number	Either a function value referring to a closure to query upvalues for or a stack depth number selecting a closure that many levels up.
`variable`	string \| number	The variable index or variable name to obtain information for.

Returns: UpvalInfo

Source: lib/debug.c, line 1520

memdump(file) → {boolean}nullable

Write a memory dump report to the given file.

This function generates a human readable memory dump of ucode values currently managed by the running VM which is useful to track down logical memory leaks in scripts.

The file parameter can be either a string value containing a file path, in which case this function tries to create and write the report file at the given location, or an already open file handle this function should write to.

Returns true if the report has been written.

Returns null if the file could not be opened or if the handle was invalid.

Parameters:

Name	Type	Description
`file`	string \| module:fs.file \| module:fs.proc	The file path or open file handle to write report to.

Returns: boolean

Source: lib/debug.c, line 650

setlocal(levelopt, variable, valueopt) → {LocalInfo}nullable

Set local variable.

The setlocal() function manipulates the value of the specified local variable at the given call stack depth.

The call stack depth specifies the amount of levels up local variables should be updated. A value of 0 refers to this setlocal() function call itself, 1 to the function calling setlocal() and so on.

The variable to update might be either specified by name or by its index with index numbers following the source code declaration order.

Returns a dictionary holding information about the updated variable.

Returns null if the stack depth exceeds the size of the current call stack.

Returns null if the invocation at the given stack depth is a C call.

Returns null if the given variable name is not found or the given variable index is invalid.

Parameters:

Name	Type	Description
`level`	number	(optional, default: `1`) The amount of call stack levels up local variables should be updated.
`variable`	string \| number	The variable index or variable name to update.
`value`	*	(optional, default: `null`) The value to set the local variable to.

Returns: LocalInfo

Source: lib/debug.c, line 1376

setupval(target, variable, value) → {UpvalInfo}nullable

Set upvalue.

The setupval() function manipulates the value of the specified captured variable associated with the given function value or the invoked function at the given call stack depth.

The call stack depth specifies the amount of levels up the function should be selected to update associated captured variables for. A value of 0 refers to this setupval() function call itself, 1 to the function calling setupval() and so on.

The variable to update might be either specified by name or by its index with index numbers following the source code declaration order.

Returns a dictionary holding information about the updated variable.

Returns null if the given function value is not a closure.

Returns null if the stack depth exceeds the size of the current call stack.

Returns null if the invocation at the given stack depth is not a closure.

Returns null if the given variable name is not found or the given variable index is invalid.

Parameters:

Name	Type	Description
`target`	function \| number	Either a function value referring to a closure to update upvalues for or a stack depth number selecting a closure that many levels up.
`variable`	string \| number	The variable index or variable name to update.
`value`	*	The value to set the variable to.

Returns: UpvalInfo

Source: lib/debug.c, line 1566

sourcepos() → {SourcePosition}nullable

Obtain information about the current source position.

The sourcepos() function determines the source code position of the current instruction invoking this function.

Returns a dictionary containing the filename, line number and line byte offset of the call site.

Returns null if this function was invoked from C code.

Returns: SourcePosition

Source: lib/debug.c, line 808

traceback(levelopt) → {StackTraceEntry[]}

Capture call stack trace.

This function captures the current call stack and returns it. The optional level parameter controls how many calls up the trace should start. It defaults to 1, that is the function calling this traceback() function.

Returns an array of stack trace entries describing the function invocations up to the point where traceback() is called.

Parameters:

Name	Type	Description
`level`	number	(optional, default: `1`) The number of callframes up the call trace should start, `0` is this function itself, `1` the function calling it and so on.

Returns: StackTraceEntry[]

Source: lib/debug.c, line 696

Type Definitions

LocalInfo: Object

Properties

Name	Type	Description
`index`	number	The index of the local variable.
`name`	string	The name of the local variable.
`value`	*	The current value of the local variable.
`linefrom`	number	The source line number of the local variable declaration.
`bytefrom`	number	The source line offset of the local variable declaration.
`lineto`	number	The source line number where the local variable goes out of scope.
`byteto`	number	The source line offset where the local vatiable goes out of scope.

Source: lib/debug.c, line 1216

SourcePosition: Object

Properties

Name	Type	Description
`filename`	string	The name of the source file that called this function.
`line`	number	The source line of the function call.
`byte`	number	The source line offset of the function call.

Source: lib/debug.c, line 824

StackTraceEntry: Object

Properties

Name	Type	Attributes	Description
`callee`	function		The function that was called.
`this`	*		The `this` context the function was called with.
`mcall`	boolean		Indicates whether the function was invoked as a method.
`strict`	boolean	optional	(optional) Indicates whether the VM was running in strict mode when the function was called (only applicable to non-C, pure ucode calls).
`filename`	string	optional	(optional) The name of the source file that called the function (only applicable to non-C, pure ucode calls).
`line`	number	optional	(optional) The source line of the function call (only applicable to non-C, pure ucode calls).
`byte`	number	optional	(optional) The source line offset of the function call (only applicable to non-C, pure ucode calls).
`context`	string	optional	(optional) The surrounding source code context formatted as human-readable string, useful for generating debug messages (only applicable to non-C, pure ucode calls).

Source: lib/debug.c, line 715

UpvalInfo: Object

Properties

Name	Type	Description
`index`	number	The index of the captured variable (upvalue).
`name`	string	The name of the captured variable.
`closed`	boolean	Indicates whether the captured variable is closed or not. A closed upvalue means that the function outlived the declaration scope of the captured variable.
`value`	*	The current value of the captured variable.

Source: lib/debug.c, line 1422

UpvalRef: Object

Properties

Name	Type	Attributes	Description
`name`	string		The name of the captured variable.
`closed`	boolean		Indicates whether the captured variable (upvalue) is closed or not. A closed upvalue means that the function value outlived the declaration scope of the captured variable.
`value`	*		The current value of the captured variable.
`slot`	number	optional	(optional) The stack slot of the captured variable. Only applicable to open (non-closed) captured variables.

Source: lib/debug.c, line 889

ValueInformation: Object

Properties

Name	Type	Attributes	Description
`type`	string		The name of the value type, one of `integer`, `boolean`, `string`, `double`, `array`, `object`, `regexp`, `cfunction`, `closure`, `upvalue` or `resource`.
`value`	*		The value itself.
`tagged`	boolean		Indicates whether the given value is internally stored as tagged pointer without an additional heap allocation.
`mark`	boolean	optional	(optional) Indicates whether the value has it's mark bit set, which is used for loop detection during recursive object traversal on garbage collection cycles or complex value stringification. Only applicable to non-tagged values.
`refcount`	number	optional	(optional) The current reference count of the value. Note that the `getinfo()` function places a reference to the value into the `value` field of the resulting information dictionary, so the ref count will always be at least 2 - one reference for the function call argument and one for the value property in the result dictionary. Only applicable to non-tagged values.
`unsigned`	boolean	optional	(optional) Whether the number value is internally stored as unsigned integer. Only applicable to non-tagged integer values.
`address`	number	optional	(optional) The address of the underlying C heap memory. Only applicable to non-tagged `string`, `array`, `object`, `cfunction` or `resource` values.
`length`	number	optional	(optional) The length of the underlying string memory. Only applicable to non-tagged `string` values.
`count`	number	optional	(optional) The amount of elements in the underlying memory structure. Only applicable to `array` and `object` values.
`constant`	boolean	optional	(optional) Indicates whether the value is constant (immutable). Only applicable to `array` and `object` values.
`prototype`	*	optional	(optional) The associated prototype value, if any. Only applicable to `array`, `object` and `prototype` values.
`source`	string	optional	(optional) The original regex source pattern. Only applicable to `regexp` values.
`icase`	boolean	optional	(optional) Whether the compiled regex has the `i` (ignore case) flag set. Only applicable to `regexp` values.
`global`	boolean	optional	(optional) Whether the compiled regex has the `g` (global) flag set. Only applicable to `regexp` values.
`newline`	boolean	optional	(optional) Whether the compiled regex has the `s` (single line) flag set. Only applicable to `regexp` values.
`nsub`	number	optional	(optional) The amount of capture groups within the regular expression. Only applicable to `regexp` values.
`name`	string	optional	(optional) The name of the non-anonymous function. Only applicable to `cfunction` and `closure` values. Set to `null` for anonymous function values.
`arrow`	boolean	optional	(optional) Indicates whether the ucode function value is an arrow function. Only applicable to `closure` values.
`module`	boolean	optional	(optional) Indicates whether the ucode function value is a module entry point. Only applicable to `closure` values.
`strict`	boolean	optional	(optional) Indicates whether the function body will be executed in strict mode. Only applicable to `closure` values.
`vararg`	boolean	optional	(optional) Indicates whether the ucode function takes a variable number of arguments. Only applicable to `closure` values.
`nargs`	number	optional	(optional) The number of arguments expected by the ucode function, excluding a potential final variable argument ellipsis. Only applicable to `closure` values.
`argnames`	string[]	optional	(optional) The names of the function arguments in their declaration order. Only applicable to `closure` values.
`nupvals`	number	optional	(optional) The number of upvalues associated with the ucode function. Only applicable to `closure` values.
`upvals`	UpvalRef[]	optional	(optional) An array of upvalue information objects. Only applicable to `closure` values.
`filename`	string	optional	(optional) The path of the source file the function was declared in. Only applicable to `closure` values.
`line`	number	optional	(optional) The source line number the function was declared at. Only applicable to `closure` values.
`byte`	number	optional	(optional) The source line offset the function was declared at. Only applicable to `closure` values.
`type`	string	optional	(optional) The resource type name. Only applicable to `resource` values.

Source: lib/debug.c, line 961