public final class TruffleContext.Builder extends Object
TruffleContext
instances.Modifier and Type | Method and Description |
---|---|
TruffleContext.Builder |
allowCreateProcess(boolean b)
Allows or denies creating processes in this context.
|
TruffleContext.Builder |
allowCreateThread(boolean b)
Allows or denies creating threads for this context.
|
TruffleContext.Builder |
allowHostClassLoading(boolean b)
Allows or denies loading new host classes in this context.
|
TruffleContext.Builder |
allowHostClassLookup(boolean b)
Allows or denies loading new host classes in this context.
|
TruffleContext.Builder |
allowInheritEnvironmentAccess(boolean b)
Allows or denies access to the parent context's environment in this context.
|
TruffleContext.Builder |
allowInnerContextOptions(boolean b)
Allows or denies options for inner contexts created by this context.
|
TruffleContext.Builder |
allowIO(boolean b)
Allows or denies using IO in this context.
|
TruffleContext.Builder |
allowNativeAccess(boolean b)
Allows or denies using native access in this context.
|
TruffleContext.Builder |
allowPolyglotAccess(boolean b)
Allows or denies access to polyglot languages in this context.
|
TruffleContext.Builder |
arguments(String language,
String[] args)
Sets the guest language application arguments for a language context.
|
TruffleContext |
build()
Builds the new context instance.
|
TruffleContext.Builder |
config(String key,
Object value)
Sets a config parameter that the child context of this language can access using
TruffleLanguage.Env.getConfig() . |
TruffleContext.Builder |
environment(Map<String,String> env)
Shortcut for setting multiple
environment variables
using a map. |
TruffleContext.Builder |
environment(String name,
String value)
Sets an environment variable.
|
TruffleContext.Builder |
err(OutputStream err)
Sets the error output stream to be used for the context.
|
TruffleContext.Builder |
forceSharing(Boolean enabled)
Force enables or disables code sharing for this inner context.
|
TruffleContext.Builder |
in(InputStream in)
Sets the input stream to be used for the context.
|
TruffleContext.Builder |
inheritAllAccess(boolean b)
If set to
true allows all access privileges that were also granted to the
outer context. |
TruffleContext.Builder |
initializeCreatorContext(boolean enabled)
Specifies whether the creating language context should be initialized in the new context.
|
TruffleContext.Builder |
onCancelled(Runnable r)
|
TruffleContext.Builder |
onClosed(Runnable r)
Specifies a
Runnable that will be executed when some operation on the new context
attenmpted while the context is already TruffleContext.close() closed}. |
TruffleContext.Builder |
onExited(Consumer<Integer> r)
Specifies a
Consumer that will be executed when the new context is
hard-exited and the exit exception is about
to reach the outer context, or when some operation on the new context is attempted while
the context is already hard-exited. |
TruffleContext.Builder |
option(String key,
String value)
Overrides an option of the inner context.
|
TruffleContext.Builder |
options(Map<String,String> options)
Sets multiple options using a map.
|
TruffleContext.Builder |
out(OutputStream out)
Sets the standard output stream to be used for the context.
|
TruffleContext.Builder |
timeZone(ZoneId zone)
Sets the default time zone to be used for this context.
|
public TruffleContext.Builder config(String key, Object value)
TruffleLanguage.Env.getConfig()
.public TruffleContext.Builder initializeCreatorContext(boolean enabled)
public TruffleContext.Builder out(OutputStream out)
null
, then the standard output stream is inherited from the outer context.public TruffleContext.Builder err(OutputStream err)
null
, then the standard error stream is inherited from the outer context. is
used.public TruffleContext.Builder in(InputStream in)
null
,
then the standard input stream is inherited from the outer context.public TruffleContext.Builder forceSharing(Boolean enabled)
null
which instructs this context to inherit sharing configuration
from the outer context.
If sharing is explicitly set to true
then code may be shared with all
contexts compatible with the configuration of this inner context. Code may also be shared
with the outer context if the outer context supports code sharing and its sharing layer
is compatible. This may be useful to force sharing for multiple created inner contexts if
the outer context configuration disabled sharing.
If sharing is explicitly set to false
then no code will be shared even if
the outer context has code sharing enabled and supported by the language. This may be
useful to avoid runtime profile pollution through code run in an inner context.
If multiple languages are potentially used it is recommended but not required to use
permitted languages
to specify all used
languages ahead of time. This allows to validate sharing layer compatibility eagerly and
avoids late failures when a language is initialized lazily and is not compatible with the
sharing layer. Use --engine.TraceSharing
for details on whether the sharing
configuration is compatible.
public TruffleContext.Builder option(String key, String value)
This method is currently only supported if the outer context is configured with
Context.Builder.allowInnerContextOptions(boolean)
. If all
privileges are denied then an IllegalArgumentException
will be thrown when
building the inner context. To find out whether the inner context option privilege has
been granted languages may use
TruffleLanguage.Env.isInnerContextOptionsAllowed()
.
public TruffleContext.Builder inheritAllAccess(boolean b)
true
allows all access privileges that were also granted to the
outer context. If set to false
then all privileges are denied in the created
context independent of the outer context. By default all privileges are denied and not
inherited.
This privilege enables inheritance for the following privileges:
TruffleContext.Builder.allowCreateThread(boolean)
TruffleContext.Builder.allowNativeAccess(boolean)
TruffleContext.Builder.allowIO(boolean)
TruffleContext.Builder.allowHostClassLookup(boolean)
TruffleContext.Builder.allowHostClassLoading(boolean)
TruffleContext.Builder.allowCreateProcess(boolean)
TruffleContext.Builder.allowPolyglotAccess(boolean)
TruffleContext.Builder.allowInheritEnvironmentAccess(boolean)
TruffleContext.Builder.allowInnerContextOptions(boolean)
If an individual privilege was set explicitly then the value of
TruffleContext.Builder.inheritAllAccess(boolean)
is ignored for that privilege. For example it is
possible to set TruffleContext.Builder.inheritAllAccess(boolean)
to true
but set
TruffleContext.Builder.allowNativeAccess(boolean)
to false
to allow inheritance of all but
native access rights from the outer to the inner context.
In case new privileges are added in the future, then this method will allow or disallow
inheritance for the new privileges as well. For security sensitive use-cases it is
recommended to keep the default value of TruffleContext.Builder.inheritAllAccess(boolean)
and
individually specify allowed privileges for this context. For non security sensitive
use-cases it is recommended to set this flag to true
. Following this
recommendation is important in case new privileges are added to the platform.
public TruffleContext.Builder allowCreateThread(boolean b)
true
to inherit
access privilege from the outer context or false
to deny access for this
context.TruffleContext.Builder.inheritAllAccess(boolean)
,
Context.Builder.allowCreateThread(boolean)
public TruffleContext.Builder allowNativeAccess(boolean b)
true
to inherit
access privilege from the outer context or false
to deny access for this
context.TruffleContext.Builder.inheritAllAccess(boolean)
,
Context.Builder.allowNativeAccess(boolean)
public TruffleContext.Builder allowIO(boolean b)
true
to inherit access
privilege from the outer context or false
to deny access for this context.public TruffleContext.Builder allowHostClassLoading(boolean b)
true
to
inherit access privilege from the outer context or false
to deny access for
this context.public TruffleContext.Builder allowHostClassLookup(boolean b)
true
to
inherit access privilege from the outer context or false
to deny access for
this context.public TruffleContext.Builder allowCreateProcess(boolean b)
true
to inherit
access privilege from the outer context or false
to deny access for this
context.TruffleContext.Builder.inheritAllAccess(boolean)
,
Context.Builder.allowCreateProcess(boolean)
public TruffleContext.Builder allowInnerContextOptions(boolean b)
true
to inherit access privilege from the outer context or
false
to deny access for this context.TruffleContext.Builder.inheritAllAccess(boolean)
,
Context.Builder.allowCreateProcess(boolean)
public TruffleContext.Builder allowPolyglotAccess(boolean b)
true
to inherit access privilege from the outer context or false
to deny access
for this context.public TruffleContext.Builder allowInheritEnvironmentAccess(boolean b)
true
to inherit variables from the outer context or false
to
deny inheritance for this context. Environment variables can be set for the inner context
with TruffleContext.Builder.environment(String, String)
even if inheritance is disabled. If inheritance
is enabled, environment variables specified for the inner context override environment
variables of the outer context.public TruffleContext.Builder environment(String name, String value)
name
- the environment variable namevalue
- the environment variable valuepublic TruffleContext.Builder environment(Map<String,String> env)
environment variables
using a map. All values of the provided map must be non-null.env
- environment variablesTo set a single environment variable.
public TruffleContext.Builder timeZone(ZoneId zone)
null
then the time zone of the outer context will be used.public TruffleContext.Builder arguments(String language, String[] args)
language
- the language id of the primary language.args
- an array of arguments passed to the guest language program.IllegalArgumentException
- if an invalid language id was specified.public TruffleContext.Builder options(Map<String,String> options)
TruffleContext.Builder.option(String, String)
for details.public TruffleContext.Builder onCancelled(Runnable r)
Runnable
that will be executed when the new context is
cancelled
and the cancel exception is
about to reach the outer context, or when some operation on the new context is attempted
while the context is already cancelled. However, the runnable will only be executed if
the outer context is not cancelled.
The purpose of the runnable is to allow throwing a custom guest exception before the
cancel exception reaches the outer context, so that the outer context can properly handle
the exception. In case the runnable does not throw any exception, an internal error is
thrown (should not be caught).public TruffleContext.Builder onExited(Consumer<Integer> r)
Consumer
that will be executed when the new context is
hard-exited
and the exit exception is about
to reach the outer context, or when some operation on the new context is attempted while
the context is already hard-exited. However, the consumer will only be executed if the
outer context is not hard-exited.
The purpose of the consumer is to allow throwing a custom guest exception before the exit
exception reaches the outer context, so that the outer context can properly handle the
exception. In case the consumer does not throw any exception, an internal error is thrown
(should not be caught).
The single input argument to the Consumer
is the exit code.public TruffleContext.Builder onClosed(Runnable r)
Runnable
that will be executed when some operation on the new context
attenmpted while the context is already TruffleContext.close()
closed}. However,
the runnable will only be executed if the outer context is not closed.
The purpose of the runnable is to allow throwing a custom guest exception before the
close exception reaches the outer context, so that the outer context can properly handle
the exception. In case the runnable does not throw any exception, an internal error is
thrown (should not be caught).public TruffleContext build()