Loomania

Loomania is a project that provides access to selected internals of virtual threads and continuations for the purposes of experimenting with APIs that are not (yet) public within the Loom system.

Usage

The Loomania JAR can be included in any project compiled against Java 11 or later, however it will only function if the JVM is Java 19.

Furthermore, the following flags must be given on the command line:

• --enable-preview - this enables the Loom/virtual thread features

• --add-opens=java.base/java.lang=ALL-UNNAMED - this allows the library to hack into the virtual thread internals

• --add-opens=java.base/jdk.internal.vm=ALL-UNNAMED - this allows the library to hack into yet more virtual thread internals

Without all of these flags, any Loomania operation will fail by throwing UnsupportedOperationException.

Usage in production

DO NOT use Loomania in production. It’s only for experimentation! If the experiments work out, then some or all of these APIs may be added to OpenJDK and this library will go away.

The code

To use Loomania, use methods on the io.github.loomania.Loomania class.

• isInstalled() - returns true if Loomania is usable in the current process.

• Loomania#newEventLoopExecutorService(ThreadFactory, EventLoop, ExecutorServiceListener) - constructs a new event loop based executor service using the given event loop handler and carrier thread factory. The carrier thread factory is used to construct the carrier thread, which is then started. The given ExecutorServiceListener can be used to perform actions when the executor service is shut down. The new executor service is returned.

• Loomania#newVirtualThreadExecutor(ExecutorService, String, ExecutorServiceListener) - constructs a new virtual thread executor with the given name which uses the given delegate executor service to schedule tasks. The new executor service is returned. This API is unlikely to be supported in the long term.

• Loomania#newJdkVirtualThreadExecutorBuilder() - this method constructs a new builder which can be used to configure a fork-join-pool-based virtual thread executor. The builder can be used to configure the parameters of the fork-join pool used for scheduling. The new executor service is returned.

More complete API JavaDoc can be found here.

The example

This trivial example can be run using jshell like this:

$ jshell --class-path path/to/loomania-2.0.jar \
    --enable-preview \
    -R--add-opens=java.base/java.lang=ALL-UNNAMED \
    -R--add-opens=java.base/jdk.internal.vm=ALL-UNNAMED

|  Welcome to JShell -- Version 19-beta
|  For an introduction type: /help intro

jshell> import io.github.loomania.*

jshell> Loomania.newVirtualThreadExecutor(Executors.newFixedThreadPool(10), "My pool", ExecutorServiceListener.EMPTY).execute(() -> { System.out.println("hello!"); })
hello!

jshell>

Note that on Java 20 or later, the --enable-preview flag is not needed.

Maven

The maven artifact coordinates are:

<dependency>
    <groupId>io.github.loomania</groupId>
    <artifactId>loomania</artifactId>
    <version>2.0</version>
</dependency>