com.oracle.truffle.api

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 TruffleThreadBuilder.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 Summary

Modifier and Type	Method and Description
TruffleThreadBuilder	afterLeave(Runnable r) Specifies after leave notification for the threads created by this builder.
TruffleThreadBuilder	beforeEnter(Runnable r) Specifies before enter notification for the threads created by this builder.
Thread	build() Creates a new thread based on the parameters specified by this builder.
TruffleThreadBuilder	context(TruffleContext innerContext) Specifies TruffleContext for the threads created by the builder.
TruffleThreadBuilder	stackSize(long size) Specifies stack size for the threads created by this builder.
TruffleThreadBuilder	threadGroup(ThreadGroup g) Specifies thread group for the threads created by this builder.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

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

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:

class AsyncThreadLanguage extends TruffleLanguage<Context> {

    @Override
    protected Context createContext(TruffleLanguage.Env env) {
        return new Context(env);
    }

    @Override
    protected boolean isThreadAccessAllowed(Thread thread,
                    boolean singleThreaded) {
        // allow access from any thread instead of just one
        return true;
    }

    @Override
    protected void initializeContext(Context context) throws Exception {
        // create and start a Thread for the asynchronous task
        // remeber the Thread reference to stop and join it in
        // the finalizeContext
        Thread t = context.env.newTruffleThreadBuilder(new Runnable() {
            @Override
            public void run() {
                // asynchronous task
            }
        }).build();
        context.startedThreads.add(t);
        t.start();
    }

    @Override
    protected void finalizeContext(Context context) {
        // stop and join all the created Threads
        boolean interrupted = false;
        for (int i = 0; i < context.startedThreads.size();) {
            Thread threadToJoin  = context.startedThreads.get(i);
            try {
                if (threadToJoin != Thread.currentThread()) {
                    threadToJoin.interrupt();
                    threadToJoin.join();
                }
                i++;
            } catch (InterruptedException ie) {
                interrupted = true;
            }
        }
        if (interrupted) {
            Thread.currentThread().interrupt();
        }
    }
}

Since:

23.1