Full rewrite and redesign (MinecraftForge#69)

Main concepts and changes:
- 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, and selectively opt-out certain subclasses in the inheritance chain using `@MarkerEvent`
- 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

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
+//        }
     }
 }