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.
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
.
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.
To use Loomania, use methods on the io.github.loomania.Loomania
class.
-
isInstalled()
- returnstrue
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 givenExecutorServiceListener
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.
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.