Represents resource limits configuration that is used to configure contexts. Resource limit instances are created using the builder and activated by enabling them for a context. All configured limits are applied per context instance. Resource limits may be reset. If a resource limit is triggered the context that triggered the limit will automatically be closed and can no longer be used to evaluate code.

The following resource limits are supported:

Statement count limit per context. Allows to limit the amount of statements executed per context.

Statement Limit Example


ResourceLimits limits = ResourceLimits.newBuilder()
                      .statementLimit(500, null)
                  .build();
try (Context context = Context.newBuilder("js")
                           .resourceLimits(limits)
                       .build();) {
    try {
        context.eval("js", "while(true);");
        assert false;
    } catch (PolyglotException e) {
        // triggered after 500 iterations of while(true);
        // context is closed and can no longer be used
        assert e.isCancelled();
    }
}

Modifier and Type	Class and Description
public class	ResourceLimits.Builder A builder used to construct resource limits.

Modifier and Type	Field and Description
private static final ResourceLimits	EMPTY
pack-priv final Object	receiver

Access	Constructor and Description
pack-priv	ResourceLimits(Object receiver)

Modifier and Type	Method and Description
public static ResourceLimits.Builder	newBuilder() Creates a new builder to construct `ResourceLimits` instances.

EMPTY	back to summary
private static final ResourceLimits EMPTY

receiver	back to summary
pack-priv final Object receiver

ResourceLimits	back to summary
pack-priv ResourceLimits(Object receiver)

newBuilder	back to summary
public static ResourceLimits.Builder newBuilder() Creates a new builder to construct `ResourceLimits` instances. Since 19.3

org.graalvm.polyglot back to summary

public final Class ResourceLimits.Builder

Class Inheritance

extends Object

java.lang.Object
org.graalvm.polyglot.ResourceLimits.Builder

A builder used to construct resource limits. Builder instances are not thread-safe and may not be used from multiple threads at the same time.

Since: 19.3

Field Summary

Modifier and Type	Field and Description
pack-priv Consumer<?>	onLimit
pack-priv long	statementLimit
pack-priv Predicate<?>	statementLimitSourceFilter

Constructor Summary

Access	Constructor and Description
pack-priv	Builder()

Method Summary

Modifier and Type	Method and Description
public ResourceLimits	build() Builds the limit configuration object.
public ResourceLimits.Builder	onLimit(Consumer<ResourceLimitEvent> onLimit) Notified when a resource limit is reached.
public ResourceLimits.Builder	statementLimit(long limit, Predicate<Source> sourceFilter) Specifies the maximum number of statements a context may execute until the onLimit event is notified and the context will be `closed`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

onLimit	back to summary
pack-priv Consumer<?> onLimit

statementLimit	back to summary
pack-priv long statementLimit

statementLimitSourceFilter	back to summary
pack-priv Predicate<?> statementLimitSourceFilter

Constructor Detail

Builder	back to summary
pack-priv Builder()

Method Detail

build back to summary

build	back to summary
public ResourceLimits build() Builds the limit configuration object. Annotations @SuppressWarnings:unchecked Since 19.3 See Also `Example Usage`

public ResourceLimits build()

Builds the limit configuration object.

Annotations

@SuppressWarnings:unchecked

Since

19.3

See Also

Example Usage

onLimit back to summary

onLimit	back to summary
public ResourceLimits.Builder onLimit(Consumer<ResourceLimitEvent> onLimit) Notified when a resource limit is reached. Default is `null`. May be set to `null` to disable events. Since 19.3

public ResourceLimits.Builder onLimit(Consumer<ResourceLimitEvent> onLimit)

Notified when a resource limit is reached. Default is null. May be set to null to disable events.

Since: 19.3

statementLimit back to summary

statementLimit	back to summary
public ResourceLimits.Builder statementLimit(long limit, Predicate<Source> sourceFilter) Specifies the maximum number of statements a context may execute until the onLimit event is notified and the context will be `closed`. After the statement limit was triggered for a context, it is no longer usable and every use of the context will throw a `PolyglotException` that returns `true` for `PolyglotException#isCancelled()`. The statement limit is independent of the number of threads executing and is applied per context. Invoking this method multiple times overwrites previous statement limit configurations. If the statement limit is exceeded then the `onLimit` listener is notified. By default there is no statement limit applied. The limit may be set to 0 to disable it. In addition to the limit a source filter may be set to indicate for which sources the limit should be applied. If the source filter is `null` then it will be applied to all `internal` and public sources. The provided limit must not be negative otherwise an `IllegalArgumentException` is thrown. If a `shared engine` is used then the same source filter instance must be used for all contexts of an engine. Otherwise an `IllegalArgumentException` is thrown when the context is `built`. The limit itself may vary between contexts. The statement limit is applied to the context and all inner contexts it spawns. Therefore, new inner contexts cannot be used to exceed the statement limit. Note that attaching a statement limit to a context reduces the throughput of all guest applications with the same engine. The statement counter needs to be updated with every statement that is executed. It is recommended to benchmark the use of the statement limit before it is used in production. Note that the complexity of a single statement may not be constant time depending on the guest language. For example, statements that execute JavaScript builtins, like `Array.sort`, may account for a single statement, but its execution time is dependent on the size of the array. The statement count limit is therefore not suitable to perform time boxing and must be combined with other more reliable measures. Annotations @SuppressWarnings:hiding Since 19.3 See Also `Example Usage`

public ResourceLimits.Builder statementLimit(long limit, Predicate<Source> sourceFilter)

Specifies the maximum number of statements a context may execute until the onLimit event is notified and the context will be closed. After the statement limit was triggered for a context, it is no longer usable and every use of the context will throw a PolyglotException that returns true for PolyglotException#isCancelled(). The statement limit is independent of the number of threads executing and is applied per context. Invoking this method multiple times overwrites previous statement limit configurations. If the statement limit is exceeded then the onLimit listener is notified.

By default there is no statement limit applied. The limit may be set to 0 to disable it. In addition to the limit a source filter may be set to indicate for which sources the limit should be applied. If the source filter is null then it will be applied to all internal and public sources. The provided limit must not be negative otherwise an IllegalArgumentException is thrown. If a shared engine is used then the same source filter instance must be used for all contexts of an engine. Otherwise an IllegalArgumentException is thrown when the context is built. The limit itself may vary between contexts.

The statement limit is applied to the context and all inner contexts it spawns. Therefore, new inner contexts cannot be used to exceed the statement limit.

Note that attaching a statement limit to a context reduces the throughput of all guest applications with the same engine. The statement counter needs to be updated with every statement that is executed. It is recommended to benchmark the use of the statement limit before it is used in production.

Note that the complexity of a single statement may not be constant time depending on the guest language. For example, statements that execute JavaScript builtins, like Array.sort, may account for a single statement, but its execution time is dependent on the size of the array. The statement count limit is therefore not suitable to perform time boxing and must be combined with other more reliable measures.

Annotations

@SuppressWarnings:hiding

Since

19.3

See Also

Example Usage

public final Class ResourceLimits

Statement Limit Example

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Class ResourceLimits.Builder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail