IsolateStartupParameters


class IsolateStartupParameters


Class used to set startup parameters for JavaScriptIsolate.

Summary

Constants

const Long

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

const Int

Default maximum size in bytes for evaluation returns/errors.

Public constructors

Public functions

@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.

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

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

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

Sets the max heap size used by the JavaScriptIsolate.

Constants

AUTOMATIC_MAX_HEAP_SIZE

Added in 1.0.0-beta01
const val AUTOMATIC_MAX_HEAP_SIZE = 0: Long

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
const val DEFAULT_MAX_EVALUATION_RETURN_SIZE_BYTES = 20971520: Int

Default maximum size in bytes for evaluation returns/errors.

Public constructors

IsolateStartupParameters

Added in 1.0.0-beta01
IsolateStartupParameters()

Public functions

getMaxEvaluationReturnSizeBytes

Added in 1.0.0-beta01
fun getMaxEvaluationReturnSizeBytes(): @IntRange(from = 0) Int

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
fun getMaxHeapSizeBytes(): @IntRange(from = 0) Long

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")
fun setMaxEvaluationReturnSizeBytes(size: @IntRange(from = 0) Int): Unit

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
size: @IntRange(from = 0) Int

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")
fun setMaxHeapSizeBytes(size: @IntRange(from = 0) Long): Unit

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
size: @IntRange(from = 0) Long

AUTOMATIC_MAX_HEAP_SIZE or a heap size limit in bytes