Skip to content

V8

Jump to bottom
Taritsyn edited this page Mar 25, 2024 · 44 revisions

JavaScriptEngineSwitcher.V8 contains a V8JsEngine adapter (wrapper for the Microsoft ClearScript.V8 version 7.4.5 with support of the V8 version 12.3.219.12).

This package does not contain the native ClearScript.V8 assemblies. Therefore, you need to choose and install the most appropriate package(s) for your platform. The following packages are available:

Engine settings

You can specify a settings of JS engine during its registration:

engineSwitcher.EngineFactories
    .AddV8(new V8Settings
    {
        MaxNewSpaceSize = 4,
        MaxOldSpaceSize = 8
    })
    ;

If you manually create an instance of JS engine, then you can pass settings via the constructor:

IJsEngine engine = new V8JsEngine(
    new V8Settings
    {
        MaxNewSpaceSize = 4,
        MaxOldSpaceSize = 8
    }
);

Consider in detail properties of the V8Settings class:

Property name Data type Default value Description
AddPerformanceObject Boolean false

Flag for whether to add the Performance object to the script engine's global namespace.

This object provides a set of low-level native facilities for performance-sensitive scripts.
AllowReflection Boolean false

Flag for whether to allow the usage of reflection API in the script code.

This affects Object.GetType, Exception.GetType, Exception.TargetSite and Delegate.Method. By default, any attempt to access these members from the script code will throw an exception.
AwaitDebuggerAndPauseOnStart Boolean false

Flag for whether to the script engine is to wait for a debugger connection and schedule a pause before executing the first line of application script code.

This property is ignored if value of the EnableDebugging property is false.
DebugPort UInt16 9222 TCP port on which to listen for a debugger connection.
DisableDynamicBinding Boolean false

Flag for whether to disable dynamic method binding.

When this property is set to true, the script engine bypasses the default method binding algorithm and uses reflection-based method binding instead. This approach abandons support for generic type inference and other features, but it avoids engaging the dynamic infrastructure.
DisableGlobalMembers Boolean false Flag for whether to disable global members.
EnableDebugging Boolean false Flag for whether to enable script debugging features (allows a TCP-based debugging).
EnableRemoteDebugging Boolean false

Flag for whether to enable remote script debugging.

This property is ignored if value of the EnableDebugging property is false.
HeapExpansionMultiplier Double 0

Heap expansion multiplier.

When set to a value greater than 1, this property enables on-demand heap expansion, which automatically increases the maximum heap size by the specified multiplier whenever the script engine is close to exceeding the current limit. Note that a buggy or malicious script can still cause an application to fail by exhausting its address space or total available memory. On-demand heap expansion is recommended for use in conjunction with heap size monitoring (see MaxHeapSize property to help contain runaway scripts).
HeapSizeSampleInterval TimeSpan TimeSpan.Zero

Minimum time interval between consecutive heap size samples.

This property is effective only when heap size monitoring is enabled (see MaxHeapSize property)
MaxArrayBufferAllocation UInt64 UInt64.MaxValue

Maximum amount of ArrayBuffer memory the runtime may allocate.

This property is specified in bytes. ArrayBuffer memory is allocated outside the runtime's heap and released when its garbage collector reclaims the corresponding JavaScript ArrayBuffer object. Leave this property at its default value to enforce no limit.
MaxHeapSize UIntPtr UIntPtr.Zero

Soft limit for the size of the V8 runtime's heap in bytes.

When it is set to the default value, heap size monitoring is disabled, and scripts with memory leaks or excessive memory usage can cause unrecoverable errors and process termination.

A V8 runtime unconditionally terminates the process when it exceeds its resource constraints. This property enables external heap size monitoring that can prevent termination in some scenarios. To be effective, it should be set to a value that is significantly lower than MaxOldSpaceSize property. Note that enabling heap size monitoring results in slower script execution.

Exceeding this limit causes the V8 runtime to interrupt script execution and throw an exception.

Note that ArrayBuffer memory is allocated outside the runtime's heap and is therefore not tracked by heap size monitoring. See MaxArrayBufferAllocation property for additional information.
MaxNewSpaceSize Int32 0 Maximum size of the new object heap in mebibytes.
MaxOldSpaceSize Int32 0 Maximum size of the old object heap in mebibytes.
MaxStackUsage UIntPtr UIntPtr.Zero

Maximum amount by which the V8 runtime is permitted to grow the stack during script execution in bytes.

When it is set to the default value, no stack usage limit is enforced, and scripts with unchecked recursion or other excessive stack usage can cause unrecoverable errors and process termination.

Note that the V8 runtime does not monitor stack usage while a host call is in progress. Monitoring is resumed when control returns to the runtime.
SetTimerResolution Boolean false

Flag for whether to set native timers to the highest available resolution while the current script engine's instance is active.

This property is ignored if value of the AddPerformanceObject property is false. It is only a hint and may be ignored on some systems. On platforms that support it, this property can degrade overall system performance or power efficiency, so caution is recommended.
Clone this wiki locally