Package com.oracle.truffle.api

Class TruffleContext.Builder

java.lang.Object
com.oracle.truffle.api.TruffleContext.Builder
Enclosing class:
TruffleContext
public final class TruffleContext.Builder extends Object
Builder class to create new TruffleContext instances.
Since:
0.27

  • Method Details

    • config

      public TruffleContext.Builder config(String key, Object value)
      Sets a config parameter that the child context of this language can access using TruffleLanguage.Env.getConfig().
      Since:
      0.27

    • initializeCreatorContext

      public TruffleContext.Builder initializeCreatorContext(boolean enabled)
      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

      public TruffleContext.Builder out(OutputStream out)
      Sets the standard output stream to be used for the context. If not set or set to null, then the standard output stream is inherited from the outer context.
      Since:
      22.3

    • err

      public TruffleContext.Builder err(OutputStream err)
      Sets the error output stream to be used for the context. If not set or set to null, then the standard error stream is inherited from the outer context. is used.
      Since:
      22.3

    • in

      public TruffleContext.Builder in(InputStream in)
      Sets the input stream to be used for the context. If not set or set to null, then the standard input stream is inherited from the outer context.
      Since:
      22.3

    • forceSharing

      public TruffleContext.Builder forceSharing(Boolean enabled)
      Force enables or disables code sharing for this inner context. By default this option is set to 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.

      Since:
      22.3

    • option

      public TruffleContext.Builder option(String key, String value)
      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 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().

      Since:
      22.3

    • inheritAllAccess

      public TruffleContext.Builder inheritAllAccess(boolean b)
      If set to 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:

      If an individual privilege was set explicitly then the value of inheritAllAccess(boolean) is ignored for that privilege. For example it is possible to set inheritAllAccess(boolean) to true but set 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 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.

      Since:
      22.3

    • allowCreateThread

      public TruffleContext.Builder allowCreateThread(boolean b)
      Allows or denies creating threads for this context. Set to true to inherit access privilege from the outer context or false to deny access for this context.
      Since:
      22.3
      See Also:

    • allowNativeAccess

      public TruffleContext.Builder allowNativeAccess(boolean b)
      Allows or denies using native access in this context. Set to true to inherit access privilege from the outer context or false to deny access for this context.
      Since:
      22.3
      See Also:

    • allowIO

      public TruffleContext.Builder allowIO(boolean b)
      Allows or denies using IO in this context. Set to true to inherit access privilege from the outer context or false to deny access for this context.
      Since:
      22.3
      See Also:

    • allowHostClassLoading

      public TruffleContext.Builder allowHostClassLoading(boolean b)
      Allows or denies loading new host classes in this context. Set to true to inherit access privilege from the outer context or false to deny access for this context.
      Since:
      22.3
      See Also:

    • allowHostClassLookup

      public TruffleContext.Builder allowHostClassLookup(boolean b)
      Allows or denies loading new host classes in this context. Set to true to inherit access privilege from the outer context or false to deny access for this context.
      Since:
      22.3
      See Also:

    • allowCreateProcess

      public TruffleContext.Builder allowCreateProcess(boolean b)
      Allows or denies creating processes in this context. Set to true to inherit access privilege from the outer context or false to deny access for this context.
      Since:
      22.3
      See Also:

    • allowInnerContextOptions

      public TruffleContext.Builder allowInnerContextOptions(boolean b)
      Allows or denies options for inner contexts created by this context. Set to true to inherit access privilege from the outer context or false to deny access for this context.
      Since:
      22.3
      See Also:

    • allowPolyglotAccess

      public TruffleContext.Builder allowPolyglotAccess(boolean b)
      Allows or denies access to polyglot languages in this context. Set to true to inherit access privilege from the outer context or false to deny access for this context.
      Since:
      22.3
      See Also:

    • allowInheritEnvironmentAccess

      public TruffleContext.Builder allowInheritEnvironmentAccess(boolean b)
      Allows or denies access to the parent context's environment in this context. Set to 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 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.
      Since:
      22.3
      See Also:

    • environment

      public TruffleContext.Builder environment(String name, String value)
      Sets an environment variable.
      Parameters:
      name - the environment variable name
      value - the environment variable value
      Since:
      22.3

    • environment

      public TruffleContext.Builder environment(Map<String,String> env)
      Shortcut for setting multiple environment variables using a map. All values of the provided map must be non-null.
      Parameters:
      env - environment variables
      Since:
      22.3
      See Also:

    • timeZone

      public TruffleContext.Builder timeZone(ZoneId zone)
      Sets the default time zone to be used for this context. If not set, or explicitly set to null then the time zone of the outer context will be used.
      Since:
      22.3

    • arguments

      public TruffleContext.Builder arguments(String language, String[] args)
      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

      public TruffleContext.Builder options(Map<String,String> options)
      Sets multiple options using a map. See option(String, String) for details.
      Since:
      22.3

    • onCancelled

      public TruffleContext.Builder onCancelled(Runnable r)
      Specifies a 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).
      Since:
      22.1

    • onExited

      public 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. 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.
      Since:
      22.1
      See Also:

    • onClosed

      public 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}. 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

      public TruffleContext build()
      Builds the new context instance.
      Since:
      0.27