175 lines
6.9 KiB
TypeScript
175 lines
6.9 KiB
TypeScript
import { QuickJSContext } from "./context";
|
|
import { EitherModule } from "./emscripten-types";
|
|
import { JSContextPointer, JSRuntimePointer } from "./types-ffi";
|
|
import { Disposable, Lifetime, Scope } from "./lifetime";
|
|
import { ModuleMemory } from "./memory";
|
|
import { QuickJSModuleCallbacks } from "./module";
|
|
import { ContextOptions, EitherFFI, JSModuleLoader, JSModuleNormalizer, QuickJSHandle } from "./types";
|
|
import { SuccessOrFail } from "./vm-interface";
|
|
/**
|
|
* Callback called regularly while the VM executes code.
|
|
* Determines if a VM's execution should be interrupted.
|
|
*
|
|
* @returns `true` to interrupt JS execution inside the VM.
|
|
* @returns `false` or `undefined` to continue JS execution inside the VM.
|
|
*/
|
|
export type InterruptHandler = (runtime: QuickJSRuntime) => boolean | undefined;
|
|
/**
|
|
* Used as an optional for the results of executing pendingJobs.
|
|
* On success, `value` contains the number of async jobs executed
|
|
* by the runtime.
|
|
* @source
|
|
*/
|
|
export type ExecutePendingJobsResult = SuccessOrFail<
|
|
/** Number of jobs successfully executed. */
|
|
number,
|
|
/** The error that occurred. */
|
|
QuickJSHandle & {
|
|
/** The context where the error occurred. */
|
|
context: QuickJSContext;
|
|
}>;
|
|
/**
|
|
* 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 {@link 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 {@link 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]].
|
|
*/
|
|
export declare class QuickJSRuntime implements Disposable {
|
|
/**
|
|
* 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]].
|
|
*/
|
|
context: QuickJSContext | undefined;
|
|
/** @private */
|
|
protected module: EitherModule;
|
|
/** @private */
|
|
protected memory: ModuleMemory;
|
|
/** @private */
|
|
protected ffi: EitherFFI;
|
|
/** @private */
|
|
protected rt: Lifetime<JSRuntimePointer>;
|
|
/** @private */
|
|
protected callbacks: QuickJSModuleCallbacks;
|
|
/** @private */
|
|
protected scope: Scope;
|
|
/** @private */
|
|
protected contextMap: Map<JSContextPointer, QuickJSContext>;
|
|
/** @private */
|
|
protected moduleLoader: JSModuleLoader | undefined;
|
|
/** @private */
|
|
protected moduleNormalizer: JSModuleNormalizer | undefined;
|
|
/** @private */
|
|
constructor(args: {
|
|
module: EitherModule;
|
|
ffi: EitherFFI;
|
|
rt: Lifetime<JSRuntimePointer>;
|
|
callbacks: QuickJSModuleCallbacks;
|
|
ownedLifetimes?: Disposable[];
|
|
});
|
|
get alive(): boolean;
|
|
dispose(): void;
|
|
newContext(options?: ContextOptions): QuickJSContext;
|
|
/**
|
|
* Set the loader for EcmaScript modules requested by any context in this
|
|
* runtime.
|
|
*
|
|
* The loader can be removed with [[removeModuleLoader]].
|
|
*/
|
|
setModuleLoader(moduleLoader: JSModuleLoader, moduleNormalizer?: JSModuleNormalizer): void;
|
|
/**
|
|
* Remove the the loader set by [[setModuleLoader]]. This disables module loading.
|
|
*/
|
|
removeModuleLoader(): void;
|
|
/**
|
|
* In QuickJS, promises and async functions create pendingJobs. These do not execute
|
|
* immediately and need to be run by calling [[executePendingJobs]].
|
|
*
|
|
* @return true if there is at least one pendingJob queued up.
|
|
*/
|
|
hasPendingJob(): boolean;
|
|
private interruptHandler;
|
|
/**
|
|
* 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]].
|
|
*/
|
|
setInterruptHandler(cb: InterruptHandler): void;
|
|
/**
|
|
* Remove the interrupt handler, if any.
|
|
* See [[setInterruptHandler]].
|
|
*/
|
|
removeInterruptHandler(): void;
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param maxJobsToExecute - When negative, run all pending jobs. Otherwise execute
|
|
* at most `maxJobsToExecute` before returning.
|
|
*
|
|
* @return 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
|
|
* [[resolvePromise]] on the promise handle returned by the async function.
|
|
*/
|
|
executePendingJobs(maxJobsToExecute?: number | void): ExecutePendingJobsResult;
|
|
/**
|
|
* Set the max memory this runtime can allocate.
|
|
* To remove the limit, set to `-1`.
|
|
*/
|
|
setMemoryLimit(limitBytes: number): void;
|
|
/**
|
|
* 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]].
|
|
*/
|
|
computeMemoryUsage(): QuickJSHandle;
|
|
/**
|
|
* @returns a human-readable description of memory usage in this runtime.
|
|
* For programmatic access to this information, see [[computeMemoryUsage]].
|
|
*/
|
|
dumpMemoryUsage(): string;
|
|
/**
|
|
* Set the max stack size for this runtime, in bytes.
|
|
* To remove the limit, set to `0`.
|
|
*/
|
|
setMaxStackSize(stackSize: number): void;
|
|
/**
|
|
* Assert that `handle` is owned by this runtime.
|
|
* @throws QuickJSWrongOwner if owned by a different runtime.
|
|
*/
|
|
assertOwned(handle: QuickJSHandle): void;
|
|
private getSystemContext;
|
|
private cToHostCallbacks;
|
|
}
|