Class TruffleThreadBuilder

java.lang.Object
com.oracle.truffle.api.TruffleThreadBuilder
public final class TruffleThreadBuilder extends Object
A builder for threads that have access to the appropriate TruffleContext. The context is either the one that corresponds to the language environment that was used to create the builder, or the one specified by context(TruffleContext). The method TruffleLanguage.Env.newTruffleThreadBuilder(Runnable) is the only way to create the builder.

Threads without an associated context should be created by TruffleLanguage.Env.createSystemThread(Runnable).

Since:
23.0

  • Method Details

    • context

      public TruffleThreadBuilder context(TruffleContext innerContext)
      Specifies TruffleContext for the threads created by the builder. It has to be an inner context created by TruffleLanguage.Env.newInnerContextBuilder(String...).build(). If not specified, the context associated with the language environment that created this builder is used (TruffleLanguage.Env.getContext()).

      Threads without an associated context should be created by TruffleLanguage.Env.createSystemThread(Runnable).

      Parameters:
      innerContext - TruffleContext for the threads created by this builder.
      Since:
      23.1

    • threadGroup

      public TruffleThreadBuilder threadGroup(ThreadGroup g)
      Specifies thread group for the threads created by this builder.
      Parameters:
      g - thread group for the threads created by this builder.
      Since:
      23.1

    • stackSize

      public TruffleThreadBuilder stackSize(long size)
      Specifies stack size for the threads created by this builder. The default is 0 which means that the parameter is ignored.
      Parameters:
      size - stack size for the threads created by this builder.
      Since:
      23.1

    • beforeEnter

      public TruffleThreadBuilder beforeEnter(Runnable r)
      Specifies before enter notification for the threads created by this builder. The notification runnable is invoked on the thread when the threads starts before the context is entered on the thread.

      The default value for the notification runnable is null which means that no notification is executed.

      If the notification runnable throws an exception, it is propagated up and can be handled by an uncaught exception handler

      Parameters:
      r - before enter notification runnable for the threads created by this builder.
      Since:
      23.1

    • afterLeave

      public TruffleThreadBuilder afterLeave(Runnable r)
      Specifies after leave notification for the threads created by this builder. The notification runnable is invoked on the thread after the thread leaves the context for the last time, i.e. the thread is about to finish.

      The default value for the notification runnable is null which means that no notification is executed.

      If the notification runnable throws an exception, it is propagated up and can be handled by an uncaught exception handler

      Parameters:
      r - after leave notification runnable for the threads created by this builder.
      Since:
      23.1

    • virtual

      public TruffleThreadBuilder virtual(boolean v)
      Specifies whether to create a virtual thread (Thread#ofVirtual()) or a regular platform thread (the default) for the threads created by this builder.
      Parameters:
      v - whether to create a virtual thread.
      Since:
      24.1

    • build

      public Thread build()
      Creates a new thread based on the parameters specified by this builder. The thread is initialized when it is started, and finalized and disposed when it finishes its execution.

      It is recommended to set an uncaught exception handler for the created thread. For example the thread can throw an uncaught exception if one of the initialized language contexts don't support execution on this thread.

      The language that created and started the thread is responsible to stop and join it during the finalizeContext, otherwise an internal error is thrown. It's not safe to use the ExecutorService.awaitTermination(long, java.util.concurrent.TimeUnit) to detect Thread termination as the polyglot thread may be cancelled before executing the executor worker.
      A typical implementation looks like: TruffleLanguage.finalizeContext(TruffleLanguageSnippets.Context)

      Since:
      23.1