Class TruffleContext.Builder
- Enclosing class:
TruffleContext
TruffleContext
instances.- Since:
- 0.27
-
Method Summary
Modifier and TypeMethodDescriptionallowCreateProcess
(boolean b) Allows or denies creating processes in this context.allowCreateThread
(boolean b) Allows or denies creating threads for this context.allowHostClassLoading
(boolean b) Allows or denies loading new host classes in this context.allowHostClassLookup
(boolean b) Allows or denies loading new host classes in this context.allowInheritEnvironmentAccess
(boolean b) Allows or denies access to the parent context's environment in this context.allowInnerContextOptions
(boolean b) Allows or denies options for inner contexts created by this context.allowIO
(boolean b) Allows or denies using IO in this context.allowNativeAccess
(boolean b) Allows or denies using native access in this context.allowPolyglotAccess
(boolean b) Allows or denies access to polyglot languages in this context.Sets the guest language application arguments for a language context.build()
Builds the new context instance.Sets a config parameter that the child context of this language can access usingTruffleLanguage.Env.getConfig()
.environment
(String name, String value) Sets an environment variable.environment
(Map<String, String> env) Shortcut for setting multipleenvironment variables
using a map.err
(OutputStream err) Sets the error output stream to be used for the context.forceSharing
(Boolean enabled) Force enables or disables code sharing for this inner context.in
(InputStream in) Sets the input stream to be used for the context.inheritAllAccess
(boolean b) If set totrue
allows all access privileges that were also granted to the outer context.initializeCreatorContext
(boolean enabled) Specifies whether the creating language context should be initialized in the new context.Specifies aRunnable
that will be executed when some operation on the new context attenmpted while the context is alreadyTruffleContext.close()
closed}.Specifies aConsumer
that will be executed when the new context ishard-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.Overrides an option of the inner context.Sets multiple options using a map.out
(OutputStream out) Sets the standard output stream to be used for the context.threadAccessDeniedHandler
(Consumer<String> handler) Installs handler to control what happens on multiple thread access.Sets the default time zone to be used for this context.
-
Method Details
-
config
Sets a config parameter that the child context of this language can access usingTruffleLanguage.Env.getConfig()
.- Since:
- 0.27
-
initializeCreatorContext
Specifies whether the creating language context should be initialized in the new context. By default the creating language won't get initialized.- Since:
- 21.3
-
out
Sets the standard output stream to be used for the context. If not set or set tonull
, then the standard output stream is inherited from the outer context.- Since:
- 22.3
-
err
Sets the error output stream to be used for the context. If not set or set tonull
, then the standard error stream is inherited from the outer context. is used.- Since:
- 22.3
-
in
Sets the input stream to be used for the context. If not set or set tonull
, then the standard input stream is inherited from the outer context.- Since:
- 22.3
-
forceSharing
Force enables or disables code sharing for this inner context. By default this option is set tonull
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.- Since:
- 22.3
-
option
Overrides an option of the inner context. Only language options may be changed. Engine or instrument options cannot be modified after their initial configuration in the outer context. All options for inner contexts are inherited from the outer context, but options set for the inner context have precedence over options set in the outer context.This method is currently only supported if the outer context is configured with
Context.Builder.allowInnerContextOptions(boolean)
. If all privileges are denied then anIllegalArgumentException
will be thrown when building the inner context. To find out whether the inner context option privilege has been granted languages may useTruffleLanguage.Env.isInnerContextOptionsAllowed()
.- Since:
- 22.3
-
inheritAllAccess
If set totrue
allows all access privileges that were also granted to the outer context. If set tofalse
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:
allowCreateThread(boolean)
allowNativeAccess(boolean)
allowIO(boolean)
allowHostClassLookup(boolean)
allowHostClassLoading(boolean)
allowCreateProcess(boolean)
allowPolyglotAccess(boolean)
allowInheritEnvironmentAccess(boolean)
allowInnerContextOptions(boolean)
If an individual privilege was set explicitly then the value of
inheritAllAccess(boolean)
is ignored for that privilege. For example it is possible to setinheritAllAccess(boolean)
totrue
but setallowNativeAccess(boolean)
tofalse
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
inheritAllAccess(boolean)
and individually specify allowed privileges for this context. For non security sensitive use-cases it is recommended to set this flag totrue
. Following this recommendation is important in case new privileges are added to the platform.- Since:
- 22.3
-
allowCreateThread
Allows or denies creating threads for this context. Set totrue
to inherit access privilege from the outer context orfalse
to deny access for this context.- Since:
- 22.3
- See Also:
-
allowNativeAccess
Allows or denies using native access in this context. Set totrue
to inherit access privilege from the outer context orfalse
to deny access for this context.- Since:
- 22.3
- See Also:
-
allowIO
Allows or denies using IO in this context. Set totrue
to inherit access privilege from the outer context orfalse
to deny access for this context.- Since:
- 22.3
- See Also:
-
allowHostClassLoading
Allows or denies loading new host classes in this context. Set totrue
to inherit access privilege from the outer context orfalse
to deny access for this context.- Since:
- 22.3
- See Also:
-
allowHostClassLookup
Allows or denies loading new host classes in this context. Set totrue
to inherit access privilege from the outer context orfalse
to deny access for this context.- Since:
- 22.3
- See Also:
-
allowCreateProcess
Allows or denies creating processes in this context. Set totrue
to inherit access privilege from the outer context orfalse
to deny access for this context.- Since:
- 22.3
- See Also:
-
allowInnerContextOptions
Allows or denies options for inner contexts created by this context. Set totrue
to inherit access privilege from the outer context orfalse
to deny access for this context.- Since:
- 22.3
- See Also:
-
allowPolyglotAccess
Allows or denies access to polyglot languages in this context. Set totrue
to inherit access privilege from the outer context orfalse
to deny access for this context.- Since:
- 22.3
- See Also:
-
threadAccessDeniedHandler
Installs handler to control what happens on multiple thread access. When multiple threads are accessing a context which isn't ready for multithreaded access an exception is yielded by default. By installing thishandler
one can control what shall happen. Either to throw exception (with the provided reason) or to resolve the multithreaded situation somehow and return to retry the thread access again.- Parameters:
handler
- callback (that gets a reason as an input) that either throws an exception or returns to signal a request for retry- Returns:
- this builder
- Since:
- 24.2
-
allowInheritEnvironmentAccess
Allows or denies access to the parent context's environment in this context. Set totrue
to inherit variables from the outer context orfalse
to deny inheritance for this context. Environment variables can be set for the inner context withenvironment(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.- Since:
- 22.3
- See Also:
-
environment
Sets an environment variable.- Parameters:
name
- the environment variable namevalue
- the environment variable value- Since:
- 22.3
-
environment
Shortcut for setting multipleenvironment variables
using a map. All values of the provided map must be non-null.- Parameters:
env
- environment variables- Since:
- 22.3
- See Also:
-
timeZone
Sets the default time zone to be used for this context. If not set, or explicitly set tonull
then the time zone of the outer context will be used.- Since:
- 22.3
-
arguments
Sets the guest language application arguments for a language context. Application arguments are typically made available to guest language implementations. Passing no arguments to a language is equivalent to providing an empty arguments array.- Parameters:
language
- the language id of the primary language.args
- an array of arguments passed to the guest language program.- Throws:
IllegalArgumentException
- if an invalid language id was specified.- Since:
- 22.3
-
options
Sets multiple options using a map. Seeoption(String, String)
for details.- Since:
- 22.3
-
onCancelled
Specifies aRunnable
that will be executed when the new context iscancelled
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).- Since:
- 22.1
-
onExited
Specifies aConsumer
that will be executed when the new context ishard-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 theConsumer
is the exit code.- Since:
- 22.1
- See Also:
-
onClosed
Specifies aRunnable
that will be executed when some operation on the new context attenmpted while the context is alreadyTruffleContext.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).- Since:
- 22.1
-
build
Builds the new context instance.- Since:
- 0.27
-