Skip to content

Latest commit

 

History

History
476 lines (269 loc) · 12.8 KB

QuickJSRuntime.md

File metadata and controls

476 lines (269 loc) · 12.8 KB

quickjs-emscripten • quickjs-emscripten-core • Readme | Exports

quickjs-emscripten / quickjs-emscripten-core / QuickJSRuntime

Class: QuickJSRuntime

A runtime represents a Javascript runtime corresponding to an object heap. Several runtimes can exist at the same time but they cannot exchange objects. Inside a given runtime, no multi-threading is supported.

You can think of separate runtimes like different domains in a browser, and the contexts within a runtime like the different windows open to the same domain.

Create a runtime via QuickJSWASMModule.newRuntime.

You should create separate runtime instances for untrusted code from different sources for isolation. However, stronger isolation is also available (at the cost of memory usage), by creating separate WebAssembly modules to further isolate untrusted code. See newQuickJSWASMModule.

Implement memory and CPU constraints with setInterruptHandler (called regularly while the interpreter runs), setMemoryLimit, and setMaxStackSize. Use computeMemoryUsage or dumpMemoryUsage to guide memory limit tuning.

Configure ES module loading with setModuleLoader.

Contents

Extends

Implements

Properties

context

context: undefined | QuickJSContext

If this runtime was created as as part of a context, points to the context associated with the runtime.

If this runtime was created stand-alone, this may or may not contain a context. A context here may be allocated if one is needed by the runtime, eg for computeMemoryUsage.

Source

packages/quickjs-emscripten-core/src/runtime.ts:78

Accessors

alive

get alive(): boolean

Returns

boolean

true if the object is alive

false after the object has been disposed

Source

packages/quickjs-emscripten-core/src/runtime.ts:125

Methods

[dispose]()

[dispose](): void

Just calls the standard .dispose() method of this class.

Returns

void

Implementation of

quickjs-emscripten-core.Disposable.[dispose]

Inherited from

quickjs-emscripten-core.UsingDisposable.[dispose]

Source

packages/quickjs-emscripten-core/src/lifetime.ts:47

assertOwned()

assertOwned(handle): void

Assert that handle is owned by this runtime.

Parameters

• handle: QuickJSHandle

Returns

void

Throws

QuickJSWrongOwner if owned by a different runtime.

Source

packages/quickjs-emscripten-core/src/runtime.ts:327

computeMemoryUsage()

computeMemoryUsage(): QuickJSHandle

Compute memory usage for this runtime. Returns the result as a handle to a JSValue object. Use QuickJSContext#dump to convert to a native object. Calling this method will allocate more memory inside the runtime. The information is accurate as of just before the call to computeMemoryUsage. For a human-digestible representation, see dumpMemoryUsage.

Returns

QuickJSHandle

Source

packages/quickjs-emscripten-core/src/runtime.ts:296

debugLog()

debugLog(...msg): void

In debug mode, log the result of calling msg().

We take a function instead of a log message to avoid expensive string manipulation if debug logging is disabled.

Parameters

• ...msg: unknown[]

Returns

void

Source

packages/quickjs-emscripten-core/src/runtime.ts:363

dispose()

dispose(): void

Dispose of the underlying resources used by this object.

Returns

void

Implementation of

quickjs-emscripten-core.Disposable.dispose

Overrides

quickjs-emscripten-core.UsingDisposable.dispose

Source

packages/quickjs-emscripten-core/src/runtime.ts:129

dumpMemoryUsage()

dumpMemoryUsage(): string

Returns

string

a human-readable description of memory usage in this runtime. For programmatic access to this information, see computeMemoryUsage.

Source

packages/quickjs-emscripten-core/src/runtime.ts:307

executePendingJobs()

executePendingJobs(maxJobsToExecute): ExecutePendingJobsResult

Execute pendingJobs on the runtime until maxJobsToExecute jobs are executed (default all pendingJobs), the queue is exhausted, or the runtime encounters an exception.

In QuickJS, promises and async functions inside the runtime create pendingJobs. These do not execute immediately and need to triggered to run.

Parameters

• maxJobsToExecute: number | void= -1

When negative, run all pending jobs. Otherwise execute at most maxJobsToExecute before returning.

Returns

ExecutePendingJobsResult

On success, the number of executed jobs. On error, the exception that stopped execution, and the context it occurred in. Note that executePendingJobs will not normally return errors thrown inside async functions or rejected promises. Those errors are available by calling QuickJSContext#resolvePromise on the promise handle returned by the async function.

Source

packages/quickjs-emscripten-core/src/runtime.ts:243

hasPendingJob()

hasPendingJob(): boolean

In QuickJS, promises and async functions create pendingJobs. These do not execute immediately and need to be run by calling executePendingJobs.

Returns

boolean

true if there is at least one pendingJob queued up.

Source

packages/quickjs-emscripten-core/src/runtime.ts:194

isDebugMode()

isDebugMode(): boolean

Returns

boolean

true if debug logging is enabled

Source

packages/quickjs-emscripten-core/src/runtime.ts:353

newContext()

newContext(options): QuickJSContext

Create a new context within this runtime. Contexts have isolated globals, but you can explicitly share objects between contexts with the same runtime.

You should dispose a created context before disposing this runtime.

Parameters

• options: ContextOptions= {}

Returns

QuickJSContext

Source

packages/quickjs-emscripten-core/src/runtime.ts:140

removeInterruptHandler()

removeInterruptHandler(): void

Remove the interrupt handler, if any. See setInterruptHandler.

Returns

void

Source

packages/quickjs-emscripten-core/src/runtime.ts:219

removeModuleLoader()

removeModuleLoader(): void

Remove the the loader set by setModuleLoader. This disables module loading.

Returns

void

Source

packages/quickjs-emscripten-core/src/runtime.ts:181

setDebugMode()

setDebugMode(enabled): void

Enable or disable debug logging.

If this module is a DEBUG variant, more logs will be printed from the C code.

Parameters

• enabled: boolean

Returns

void

Source

packages/quickjs-emscripten-core/src/runtime.ts:343

setInterruptHandler()

setInterruptHandler(cb): void

Set a callback which is regularly called by the QuickJS engine when it is executing code. This callback can be used to implement an execution timeout.

The interrupt handler can be removed with removeInterruptHandler.

Parameters

• cb: InterruptHandler

Returns

void

Source

packages/quickjs-emscripten-core/src/runtime.ts:207

setMaxStackSize()

setMaxStackSize(stackSize): void

Set the max stack size for this runtime, in bytes. To remove the limit, set to 0.

Parameters

• stackSize: number

Returns

void

Source

packages/quickjs-emscripten-core/src/runtime.ts:315

setMemoryLimit()

setMemoryLimit(limitBytes): void

Set the max memory this runtime can allocate. To remove the limit, set to -1.

Parameters

• limitBytes: number

Returns

void

Source

packages/quickjs-emscripten-core/src/runtime.ts:281

setModuleLoader()

setModuleLoader(moduleLoader, moduleNormalizer?): void

Set the loader for EcmaScript modules requested by any context in this runtime.

The loader can be removed with removeModuleLoader.

Parameters

• moduleLoader: JSModuleLoader

• moduleNormalizer?: JSModuleNormalizer

Returns

void

Source

packages/quickjs-emscripten-core/src/runtime.ts:172

Generated using typedoc-plugin-markdown and TypeDoc