JsEngine Class

Initializes a new instance of the JsEngine class.

Gets the realm of the running execution context (the current realm).

Gets whether a script is running (the execution context stack is not empty).

Gets the options of the engine: a copy of the options given to the constructor. The limits can be changed on the thread of the engine; the other options cannot (see JsEngineOptions).

Gets the realms created by JsEngine.CreateRealm (the realms of the ShadowRealm objects are not included).

Call(F, V, argumentsList) (https://tc39.es/ecma262/#sec-call).

Captures the stack trace of the running code, in the format of the stack property of the errors (without the first line).

Throws a JsTerminationException when the running script must stop: the execution is canceled (JsEngineOptions.CancellationToken), a limit of JsEngineOptions or of an execution scope (JsEngine.EnterExecutionScope) is exceeded, or the running entry was already terminated. The host calls it periodically while it runs code on behalf of the script (e.g. WebAssembly code); the engine checks the limits itself while JavaScript code and the built-in functions run.

Construct(F, argumentsList, newTarget) (https://tc39.es/ecma262/#sec-construct); newTarget is the constructor when it is undefined.

Creates a realm with its intrinsics and an ordinary global object.

Releases the resources of the engine: the work posted afterwards does not run (JsEngine.Post), and the pending tasks of JsEngine.ToTask are canceled.

Enqueues a job in the promise job queue (a microtask): it runs from JsEngine.RunJobs, after the jobs already in the queue.

Makes the engine the engine of the current thread until the returned scope is disposed. The methods of the objects (JsObject.GetProperty...) need it when they are not called by the engine (a callback).

Pushes an execution context whose ScriptOrModule is scriptOrModule until the returned scope is disposed: it is the active script or module (JsEngine.GetActiveScriptOrModule) of the code it runs, until code that has its own script or module runs (e.g. HostCallJobCallback restores the active script captured by HostMakeJobCallback, so that the code compiled by an eval called by a promise job resolves its imports against it).

Starts an execution scope: the calls made until the returned scope is disposed are one entry into JavaScript, and limits apply to them as a whole, in addition to the limits of JsEngineOptions (which apply to the scope as a whole as well: the calls in the scope do not restart them). It bounds a sequence of calls (e.g. a script and the jobs it enqueues: JsEngine.RunJobs runs each job in its own entry otherwise), or one call of an engine shared by several requests, without changing the options of the engine. The scope also makes the engine the engine of the current thread (JsEngine.Enter). A scope started while JavaScript runs (from a host function) adds its limits to the running entry until it is disposed.

Makes the jobs enqueued from now on go to a new queue, which JsEngine.RunJobs runs, until the returned scope is disposed (e.g. the microtasks of a nested event loop). The jobs left in the nested queue then go to the outer queue.

GetActiveScriptOrModule(): the script or the module of the innermost running code that has one, or null.

Gets the position of the running JavaScript code (the call of the running .NET callback), or null when no script runs.

Gets the symbol of the global symbol registry of the engine whose key is key, creating it when needed: the symbol that Symbol.for(key) returns in all the realms of the engine. Another engine has its own registry, so the same key gives another symbol there.

IsArray(value) (https://tc39.es/ecma262/#sec-isarray): true for arrays and proxies of arrays; throws for a revoked proxy.

Posts work to run on the thread of the engine. It can be called from any thread (e.g. the continuation of an I/O operation). The work runs from JsEngine.RunJobs as a task of the event loop: after the promise jobs already in the queue, in the order it was posted, and followed by the promise jobs it enqueues. A JsException thrown by the work goes to JsHost.ReportJobException; another exception comes out of JsEngine.RunJobs. A host whose JsHost.EnqueueGenericJob is overridden runs the work in its own event loop.

Runs action with realm as the current realm (the realm of the objects created by the built-ins and the API).

Runs the jobs until the queue is empty: the promise jobs first (in the order they were enqueued), then the generic jobs and the timeout jobs whose delay has elapsed, each followed by the promise jobs it enqueued. The timeout jobs whose delay has not elapsed stay in the queue.

Runs the event loop of the engine until the promise settles: runs the jobs (JsEngine.RunJobs), and waits for posted work and timeout jobs (JsEngine.WaitForJobsAsync) while the promise is pending. The engine is free between two runs of the jobs: the work of the host (e.g. the continuations of its tasks) reaches it with JsEngine.Post.

SameValue(x, y) (https://tc39.es/ecma262/#sec-samevalue).

ToBigInt(value) (https://tc39.es/ecma262/#sec-tobigint).

ToBoolean(value) (https://tc39.es/ecma262/#sec-toboolean).

ToNumber(value) (https://tc39.es/ecma262/#sec-tonumber); it may run code (valueOf).

ToObject(value) (https://tc39.es/ecma262/#sec-toobject): a TypeError for undefined and null.

ToPropertyKey(value) (https://tc39.es/ecma262/#sec-topropertykey); it may run code.

ToString(value) (https://tc39.es/ecma262/#sec-tostring); it may run code, and throws a TypeError for a symbol.

Gets a task that completes when the promise settles: its result is the value of a fulfilled promise, and the JsException of the rejection reason for a rejected promise. A value that is not a promise is resolved as Promise.resolve does. The promise settles while the engine runs its jobs (JsEngine.RunJobs, or JsEngine.RunUntilSettledAsync), and the continuations of the task run on the thread pool, after the job. The task is canceled when the engine is disposed first.

Waits until a job is ready to run: a promise job, work posted by JsEngine.Post, a generic job, or a timeout job whose delay has elapsed. It completes at once when one is already queued. A host calls it between two calls to JsEngine.RunJobs, while the engine does not run, to implement its event loop.

Occurs when a handler is attached to a promise that JsEngine.UnhandledRejection reported.

Occurs when a promise is rejected and has no handler at the end of JsEngine.RunJobs (once the job queue is empty: a handler attached by a job of the same JsEngine.RunJobs call, or by the script before the call, prevents it). It is raised on the thread of the engine. A promise rejected by a script that runs without a call to JsEngine.RunJobs is reported by the next call.