Full rewrite and redesign (#69)

Highlights/main concepts and changes:
- Major performance improvements, no transforms needed
- ListenerList is merged into EventBus. Groups of them are called a BusGroup now
- Posting, registration, etc is all done directly on the events you care about
- Events can be records or mutable classes and can opt-into various characteristics
- Events can support multi-inheritance with an opt-in
- Only monitoring events can receiveCancelled now
- Cancellation and monitoring state are decoupled from the event objects themselves, allowing for records and other immutable data structures (such as the upcoming Valhalla value classes)
- Strong encapsulation with module system enforcement and sealed types, good separation between API spec and implementation to allow freedom for future internal enhancements

See the linked PR for more details.

Author: PaintNinja

.github/workflows/publish.yml

@@ -9,15 +9,16 @@ permissions:
 
 jobs:
   build:
-    uses: MinecraftForge/SharedActions/.github/workflows/gradle.yml@main
+    uses: MinecraftForge/SharedActions/.github/workflows/gradle.yml@v0
     with:
-      java: 17
-      gradle_tasks: "publish"
+      java: 21
+      gradle_tasks: "check publish"
       artifact_name: "eventbus"
     secrets:
       DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
       PROMOTE_ARTIFACT_WEBHOOK: ${{ secrets.PROMOTE_ARTIFACT_WEBHOOK }}
       PROMOTE_ARTIFACT_USERNAME: ${{ secrets.PROMOTE_ARTIFACT_USERNAME }}
       PROMOTE_ARTIFACT_PASSWORD: ${{ secrets.PROMOTE_ARTIFACT_PASSWORD }}
       MAVEN_USER: ${{ secrets.MAVEN_USER }}
-      MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+      MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+      GRADLE_CACHE_KEY: ${{ secrets.GRADLE_CACHE_KEY }}

Benchmarking.md

@@ -1,15 +1,64 @@
 # EventBus
 
-EventBus is designed to be a simple subscriber-publisher framework. Originally inspired by [Guava], with intentions to be faster by replacing reflection with generated accessor classes. EventBus is intended to be a generic library usable in any project. It has grown larger API/Feature/Complexity/Dependency wise then it was ever intended, and thus will be receiving some redesigns and simplification eventually. 
+A flexible, high-performance, thread-safe subscriber-publisher framework designed with modern Java in mind.
 
-The major focus of EventBus is fast event dispatching. As such any changes should have benchmarks run. See [Benchmarking].
+## Overview
+The core functionality of EventBus is to provide a simple and efficient way to handle events in a decoupled manner.
 
-### Thanks
-[![YourKit](https://www.yourkit.com/images/yklogo.png)](https://www.yourkit.com/)
+Each event may have one or more buses associated with it, which are responsible for managing listeners and dispatching
+instances of the event object to them. To maximise performance, the underlying implementation is tailored on the fly
+based on the event's type, characteristics, inheritance chain and the number and type of listeners registered to the bus.
 
-YourKit for providing us access to their [YourKit Java Profiler] which helps identify bottlenecks and places for improvment.
+## Quickstart guide
+First, add the Forge Maven repository and the EventBus dependency to your project:
+```gradle
+repositories {
+    maven {
+        name = "Forge"
+        url = "https://maven.minecraftforge.net"
+    }
+}
 
+dependencies {
+    implementation "net.minecraftforge:eventbus:<version>"
+}
+```
 
-[Guava]: https://guava.dev/releases/snapshot-jre/api/docs/com/google/common/eventbus/EventBus.html
-[Benchmarking]: https://github.com/MinecraftForge/EventBus/blob/master/Benchmarking.md
-[YourKit Java Profiler]: https://www.yourkit.com/java/profiler/
+You can find the list of available versions [here][Versions].
+
+Now you can start using EventBus in your project. Simple usage example:
+```java
+import net.minecraftforge.eventbus.api.event.RecordEvent;
+import net.minecraftforge.eventbus.api.bus.EventBus;
+
+// Define an event and a bus for it
+record PlayerLoggedInEvent(String username) implements RecordEvent {
+    public static final EventBus<PlayerLoggedInEvent> BUS = EventBus.create(PlayerLoggedInEvent.class);
+}
+
+// Register an event listener
+PlayerLoggedInEvent.BUS.addListener(event -> System.out.println("Player logged in: " + event.username()));
+
+// Post an event to the registered listeners
+PlayerLoggedInEvent.BUS.post(new PlayerLoggedInEvent("Paint_Ninja"));
+```
+
+Browse the `net.minecraftforge.eventbus.api` package and read the Javadocs for more information. For real-world
+examples, check out Forge's extensive use of EventBus [here][Forge usages].
+
+## Nullability
+The entirety of EventBus' API is `@NullMarked` and compliant with the [jSpecify specification](https://jspecify.dev/) -
+this means that everything is non-null by default unless otherwise specified.
+
+Attempting to pass a `null` value to a method param that isn't explicitly marked as `@Nullable` is an unsupported
+operation and won't be considered a breaking change if a future version throws an exception in such cases when it didn't
+before.
+
+## Contributing
+One of the main goals of EventBus is performance. As such, any changes should be benchmarked with the `jmh` Gradle task
+to help ensure that there are no unintended performance regressions. If you are unsure how to do this or would like
+to discuss your ideas before submitting a PR, feel free to reach out to us on the [Forge Discord].
+
+[Versions]: https://files.minecraftforge.net/net/minecraftforge/eventbus/
+[Forge usages]: https://github.com/MinecraftForge/MinecraftForge/tree/1.21.x/src/main/java/net/minecraftforge/event
+[Forge Discord]: https://discord.minecraftforge.net/

README.md

@@ -1,21 +1,25 @@
 import net.minecraftforge.gradleutils.PomUtils
+import net.ltgt.gradle.errorprone.ErrorProneOptions
+import net.ltgt.gradle.nullaway.NullAwayOptions
 
 plugins {
-    id 'eclipse'
     id 'java-library'
     id 'maven-publish'
-    id 'com.github.ben-manes.versions' version '0.50.0'
-    id 'org.gradlex.extra-java-module-info' version '1.8'
-    id 'net.minecraftforge.gradleutils' version '2.3.3'
-    id 'net.minecraftforge.licenser' version '1.0.1'
+    id 'org.gradlex.extra-java-module-info' version '1.11'
+    id 'net.minecraftforge.gradleutils' version '2.4.13'
+    id 'net.minecraftforge.licenser' version '1.1.1'
+
+    // Enforce jSpecify annotations at compile-time
+    id 'net.ltgt.errorprone' version '4.1.0'
+    id 'net.ltgt.nullaway' version '2.2.0'
 }
 
 group = 'net.minecraftforge'
-version = gradleutils.tagOffsetVersion
-print("Version: $version")
+version = gitversion.version.tagOffset
+print "Version: $version"
 
 java {
-    toolchain.languageVersion = JavaLanguageVersion.of(16)
+    toolchain.languageVersion = JavaLanguageVersion.of(21)
     modularity.inferModulePath = true
     withSourcesJar()
 }
@@ -26,12 +30,9 @@ repositories {
 }
 
 dependencies {
-    api(libs.typetools)
-    implementation(libs.log4j.api)
-    implementation(libs.bundles.asm)
-    compileOnly(libs.modlauncher)
-    compileOnly(libs.securemodules)
-    compileOnly(libs.nulls)
+    api libs.jspecify.annotations
+    errorprone libs.errorprone.core
+    errorprone libs.nullaway
 }
 
 extraJavaModuleInfo {
@@ -42,17 +43,37 @@ changelog {
     from '1.0.0'
 }
 
-jar {
+tasks.withType(JavaCompile).configureEach {
+    // Set up compile-time enforcement of the jSpecify spec via ErrorProne and NullAway
+    options.errorprone { ErrorProneOptions errorProne ->
+        errorProne.disableAllChecks = true // Opt-into only the checks we care about
+
+        // Enforce the jSpecify spec
+        errorProne.nullaway { NullAwayOptions nullAway ->
+            nullAway.jspecifyMode = true
+            nullaway.onlyNullMarked = true // Only enforce nullability checks on @NullMarked classes and packages
+            nullAway.error() // Throw a compile error on jSpecify spec violations
+        }
+
+        // Enforce the ErrorProne checks we care about
+        errorProne.error("FieldCanBeFinal", "MethodCanBeStatic", "LambdaFunctionalInterface")
+    }
+}
+
+tasks.named('jar', Jar) {
     manifest {
         attributes([
             'Specification-Title':   'EventBus',
-            'Specification-Version':  gradleutils.gitInfo.tag,
+            'Specification-Version':  gitversion.version.info.tag,
             'Specification-Vendor':   'Forge Development LLC',
             'Implementation-Title':   'EventBus',
             'Implementation-Version': project.version,
             'Implementation-Vendor':  'Forge Development LLC'
-        ] as LinkedHashMap, 'net/minecraftforge/eventbus/service/')
+        ])
     }
+
+    reproducibleFileOrder = true
+    preserveFileTimestamps = false
 }
 
 license {
@@ -65,17 +86,15 @@ publishing {
         from components.java
         artifactId = 'eventbus'
         pom {
-            name = 'Event Bus'
+            name = 'EventBus'
             description = 'High performance Event Bus library'
-            url = 'https://github.com/MinecraftForge/EventBus'
 
-            PomUtils.setGitHubDetails(pom, 'EventBus')
+            gradleutils.pom.gitHubDetails = pom
 
             license PomUtils.Licenses.LGPLv2_1
 
             developers {
-                developer PomUtils.Developers.LexManos
-                developer PomUtils.Developers.cpw
+                developer PomUtils.Developers.Paint_Ninja
             }
         }
     }
@@ -87,18 +106,16 @@ publishing {
 
 allprojects {
     ext.VALID_VMS = [
-        'Adoptium':  [16, 17, 18, 19, 20, 21],
-        'Amazon':    [16, 17, 18, 19, 20, 21],
-        'Azul':      (16..21),
-        'BellSoft':  (16..21),
-        'Graal_VM':  [16, 17,     19, 20, 21],
-        'IBM':       [16, 17, 18, 19, 20    ],
-        'Microsoft': [16, 17,             21],
-        'Oracle':    (16..21),
-        'SAP':       (16..20)
+        'Adoptium':  [21],
+        'Amazon':    [21],
+        'Azul':      (21),
+        'BellSoft':  (21),
+        'Graal_VM':  [21],
+        'Microsoft': [21],
+        'Oracle':    (21),
     ]
 
     // Tests are expensive to run all variants, so only run if asked to
     if (!project.hasProperty('bulk_tests'))
-        ext.VALID_VMS = ['Adoptium':  [17]]//, 18, 19, 20, 21] ]
+        ext.VALID_VMS = ['Adoptium':  [21]]
 }

build.gradle

@@ -4,10 +4,10 @@ plugins {
 
 repositories {
     mavenCentral()
-    maven { url 'https://jitpack.io' }
+    maven { url = 'https://jitpack.io' }
 }
 
-java.toolchain.languageVersion = JavaLanguageVersion.of(17)
+java.toolchain.languageVersion = JavaLanguageVersion.of(21)
 
 dependencies {
     implementation 'com.github.Steppschuh:Java-Markdown-Generator:1.3.2'

buildSrc/build.gradle

@@ -24,7 +24,8 @@ abstract class AggregateTest extends DefaultTask {
                 if (!test.name.startsWith('TEST-') || !test.name.endsWith('.xml'))
                     continue
 
-                def dirName = test.parentFile.name
+                String dirName = test.parentFile.name
+                if (!dirName.contains('-')) continue
                 def (javaName, javaVersion) = dirName.split('-')
                 javas.computeIfAbsent(javaName, { [] as SortedSet }).add(javaVersion)
 
@@ -44,7 +45,7 @@ abstract class AggregateTest extends DefaultTask {
                 }
                 test.delete()
             }
-            if (java.listFiles().length == 0)
+            if (java.listFiles().length === 0)
                 java.deleteDir()
         }
 

buildSrc/src/main/groovy/AggregateTest.groovy

@@ -11,7 +11,7 @@ repositories {
 }
 
 java {
-    toolchain.languageVersion = JavaLanguageVersion.of(16)
+    toolchain.languageVersion = JavaLanguageVersion.of(21)
 }
 
 license {
@@ -20,19 +20,14 @@ license {
 }
 
 dependencies {
-    compileOnly(libs.nulls)
-
-    implementation(rootProject)
-    implementation(libs.bundles.asm) // Needed by ModLauncher
-    implementation(libs.junit.api)
-    implementation(libs.securemodules)
-    implementation(libs.modlauncher)
-    implementation(libs.unsafe)
-    implementation(projects.eventbusTestJar)
+    implementation rootProject
+    implementation projects.eventbusTestJar
 
     implementation libs.jmh.core
     runtimeOnly libs.jmh.annotationProcessor
     annotationProcessor libs.jmh.annotationProcessor
+
+    implementation libs.jspecify.annotations
 }
 
 extraJavaModuleInfo {
@@ -57,21 +52,19 @@ tasks.register('archiveJfr', ArchiveJfr) {
     output = file('build/jmh_profile_results/archive/')
 }
 
-tasks.register('jmh') {
-    dependsOn 'aggregateJmh'
-}
+tasks.register('jmh')
 
 ((Map<String, List<Integer>>) ext.VALID_VMS).forEach { javaVendor, javaVersions ->
     for (Integer javaVersion in javaVersions) {
         var output = file("build/jmh_results/jmh-${javaVendor}-${javaVersion}.json")
-        var outputJfr = file("build/jmh_profile_results/last_run/${javaVendor}-${javaVersion}/")
-        outputJfr.mkdirs()
+        output.mkdirs()
+//        var outputJfr = file("build/jmh_profile_results/last_run/${javaVendor}-${javaVersion}/")
+//        outputJfr.mkdirs()
         var task = tasks.register("jmh${javaVendor}${javaVersion}", JavaExec) {
             classpath = sourceSets.main.runtimeClasspath
             mainModule = 'net.minecraftforge.eventbus.jmh'
             mainClass = 'net.minecraftforge.eventbus.benchmarks.Main'
             modularity.inferModulePath = true
-            systemProperty 'jmh.ignoreLock', 'true'
             jvmArgs += '-Xmx8g' // Some tests are fast enough that they generate millions of class files, so, give more memory
             args = [
                     '-bm', 'AverageTime',  // Benchmark mode. Available modes are: [Throughput, AverageTime, SampleTime, SingleShotTime, All]
@@ -83,9 +76,9 @@ tasks.register('jmh') {
                     '-f',  '1',   // Forks per benchmark
                     '-rf', 'json', // Results File Format
 
-                    // Todo: Conditionally enable these when given a debug flag. Log a warning if they are enabled
-                    //       saying that they should only be used for identifying hotspots and to not trust the
-                    //       results of the benchmarks when they are enabled.
+                    // Todo: [EB][Benchmarks] Conditionally enable these when given a debug flag. Log a warning if they
+                    //       are enabled saying that they should only be used for identifying hotspots and to not trust
+                    //       the results of the benchmarks when they are enabled.
 //                    '-prof', 'stack', // Profiler: Simple and naive Java stack profiler
 //                    '-prof', "jfr:dir=${outputJfr}", // Profiler: Java Flight Recorder profiler
 
@@ -101,7 +94,7 @@ tasks.register('jmh') {
                 args += project.property('bench')
 
             doFirst {
-                outputJfr.deleteDir()
+//                outputJfr.deleteDir()
                 if (!output.parentFile.exists())
                     output.parentFile.mkdirs()
                 if (output.exists())
@@ -113,13 +106,16 @@ tasks.register('jmh') {
                 implementation = JvmImplementation.VENDOR_SPECIFIC
             }
         }
-        tasks.named('aggregateJmh') {
-            dependsOn task
-            inputs.file output
-        }
-        tasks.named('archiveJfr') {
+        tasks.named('jmh') {
             dependsOn task
-            inputs.dir outputJfr
         }
+//        tasks.named('aggregateJmh') {
+//            dependsOn task
+//            inputs.file output
+//        }
+//        tasks.named('archiveJfr') {
+//            dependsOn task
+//            inputs.dir outputJfr
+//        }
     }
 }