IsolateStartupParameters

public final class IsolateStartupParameters


Class used to set startup parameters for JavaScriptIsolate.

Summary

Constants

static final long

Special value for automatically selecting a heap size limit (which may be device-specific) when the isolate is created.

static final int

Default maximum size in bytes for evaluation returns/errors.

Public constructors

Public methods

@IntRange(from = 0) int

Gets the max size for evaluation return values and errors in the JavaScriptIsolate.

@IntRange(from = 0) long

Gets the max heap size used by the JavaScriptIsolate.

void
@RequiresFeature(name = JavaScriptSandbox.JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT, enforcement = "androidx.javascriptengine.JavaScriptSandbox#isFeatureSupported")
setMaxEvaluationReturnSizeBytes(@IntRange(from = 0) int size)

Sets the max size for evaluation return values and errors in the JavaScriptIsolate.

void
@RequiresFeature(name = JavaScriptSandbox.JS_FEATURE_ISOLATE_MAX_HEAP_SIZE, enforcement = "androidx.javascriptengine.JavaScriptSandbox#isFeatureSupported")
setMaxHeapSizeBytes(@IntRange(from = 0) long size)

Sets the max heap size used by the JavaScriptIsolate.

Constants

AUTOMATIC_MAX_HEAP_SIZE

Added in 1.0.0-beta01
public static final long AUTOMATIC_MAX_HEAP_SIZE = 0

Special value for automatically selecting a heap size limit (which may be device-specific) when the isolate is created. This is the default setting for max heap size.

DEFAULT_MAX_EVALUATION_RETURN_SIZE_BYTES

Added in 1.0.0-beta01
public static final int DEFAULT_MAX_EVALUATION_RETURN_SIZE_BYTES = 20971520

Default maximum size in bytes for evaluation returns/errors.

Public constructors

IsolateStartupParameters

Added in 1.0.0-beta01
public IsolateStartupParameters()

Public methods

getMaxEvaluationReturnSizeBytes

Added in 1.0.0-beta01
public @IntRange(from = 0) int getMaxEvaluationReturnSizeBytes()

Gets the max size for evaluation return values and errors in the JavaScriptIsolate.

If not set using setMaxEvaluationReturnSizeBytes, the default value is DEFAULT_MAX_EVALUATION_RETURN_SIZE_BYTES.

Returns
@IntRange(from = 0) int

max size in bytes

getMaxHeapSizeBytes

Added in 1.0.0-beta01
public @IntRange(from = 0) long getMaxHeapSizeBytes()

Gets the max heap size used by the JavaScriptIsolate.

The default value is AUTOMATIC_MAX_HEAP_SIZE which indicates a limit (which may be device-specific) will be chosen automatically when the isolate is created.

Returns
@IntRange(from = 0) long

AUTOMATIC_MAX_HEAP_SIZE or a heap size limit in bytes

setMaxEvaluationReturnSizeBytes

Added in 1.0.0-beta01
@RequiresFeature(name = JavaScriptSandbox.JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT, enforcement = "androidx.javascriptengine.JavaScriptSandbox#isFeatureSupported")
public void setMaxEvaluationReturnSizeBytes(@IntRange(from = 0) int size)

Sets the max size for evaluation return values and errors in the JavaScriptIsolate.

The default value is DEFAULT_MAX_EVALUATION_RETURN_SIZE_BYTES.

If an evaluation exceeds this limit, EvaluationResultSizeLimitExceededException is produced. Error messages will be truncated to adhere to this limit.

Parameters
@IntRange(from = 0) int size

max size in bytes

setMaxHeapSizeBytes

Added in 1.0.0-beta01
@RequiresFeature(name = JavaScriptSandbox.JS_FEATURE_ISOLATE_MAX_HEAP_SIZE, enforcement = "androidx.javascriptengine.JavaScriptSandbox#isFeatureSupported")
public void setMaxHeapSizeBytes(@IntRange(from = 0) long size)

Sets the max heap size used by the JavaScriptIsolate.

A setting of AUTOMATIC_MAX_HEAP_SIZE indicates to automatically chose a limit (which may be device-specific) when the isolate is created. This is the default.

If a value higher than the device-specific maximum heap size limit is supplied, the device's maximum limit will be used as the heap size limit.

The applied limit may not be exact. For example, the limit may internally be rounded up to some multiple of bytes, be increased to some minimum value, or reduced to some maximum supported value.

Exceeding this limit will usually result in all unfinished and future evaluations failing with MemoryLimitExceededException and the isolate terminating with a status of STATUS_MEMORY_LIMIT_EXCEEDED. Note that exceeding the memory limit will take down the entire sandbox - not just the responsible isolate - and all other isolates will receive generic SandboxDeadException and STATUS_SANDBOX_DEAD errors.

Not all JavaScript sandbox service implementations (particularly older ones) handle memory exhaustion equally, and may crash the sandbox without attributing the failure to memory exhaustion in a particular isolate.

Parameters
@IntRange(from = 0) long size

AUTOMATIC_MAX_HEAP_SIZE or a heap size limit in bytes