pedrolamarao / generators-jvm

Continuation-based generators for the JVM.

generators-jvm

Continuation-based generators for the JVM.

Module generators contain the core classes, AbstractGenerator, ConsumerGenerator and RunnableGenerator.

AbstractGenerator defines the generator procedure as an abstract method. Concrete generators must extend from AbstractGenerator. The generator procedure has protected access to this.yield. Benchmarking indicates this imposes quite the overhead.

ConsumerGenerator defines the generator as a functional object. Concrete generators may extend or aggregate ConsumerGenerator. The generator procedure receives this::yield as a parameter. Benchmarking indicates this imposes some overhead.

RunnableGenerator defines the generator as a functional object. Concrete generators may extend or aggregate RunnableGenerator. The generator procedure has public static access to RunnableGenerator.yield. Benchmarking indicates this imposes the least overhead. However, it cannot type check the yielded value!

Applications are demonstrated in readers.

building

Build is driven by Gradle.

Have JAVA_HOME point to a JDK version up to 19.

Unpack JDK 21 EA into ${rootDir}/jdk-21. Alternatively, edit ${rootDir}/gradle.properties. For more information, see: https://docs.gradle.org/8.1/userguide/toolchains.html

To build and run automated tests: ./gradlew build

To build benchmarks: ./gradlew jmhJar

To run benchmarks: ./gradlew --console=plain jmh

You may manually run a benchmark by doing something like:

java --add-exports java.base/jdk.internal.vm=ALL-UNNAMED --enable-preview -jar .\readers\ber\build\libs\ber-1.0-SNAPSHOT-jmh.jar -h

using

The generators module require JDK version 21 with preview features enabled.

Because the generators refer to package jdk.internal.vm from module java.base, client code must force exporting that package by that module.

To configure a Gradle consumer project:

build.gradle.kts

plugins {
    id("java")
}

dependencies {
    implementation("br.dev.pedrolamarao.generators:generators:1.0-SNAPSHOT")
}

tasks.withType<JavaCompile>().configureEach {
    options.compilerArgs = listOf("--add-exports","java.base/jdk.internal.vm=br.dev.pedrolamarao.generators","--enable-preview")
}

tasks.withType<Test>().configureEach {
    jvmArgs = listOf("--add-exports","java.base/jdk.internal.vm=br.dev.pedrolamarao.generators","--enable-preview")
}