How greenrobot/eventbus works
1. Overall shape
This is a multi-module library repository for greenrobot EventBus, not an application. The main product is a publish/subscribe event bus with a small core runtime, an Android-specific extension, an annotation processor for subscriber indexes, plus test and benchmark apps that validate behavior across Java and Android.
2. Core runtime module: EventBus/
The heart of the repo is EventBus/src/org/greenrobot/eventbus. This module contains the runtime API and engine: EventBus, EventBusBuilder, Subscribe, ThreadMode, SubscriberMethod, Subscription, the error/event classes, and the internal posting machinery. This is the layer that application code depends on directly in both Java and Android projects.
3. Primary runtime flow
The main data flow is: subscriber object registers → subscriber methods are discovered → subscriptions are stored → event is posted → matching subscriptions are invoked. Discovery happens through SubscriberMethodFinder, which can use either reflection or generated subscriber metadata. Delivery is controlled by the ThreadMode assigned on each @Subscribe method.
4. Threading and dispatch boundary
Event delivery is split across poster implementations. The core module includes AsyncPoster, BackgroundPoster, PendingPostQueue, and Poster, which together route events to the correct execution context. The Android add-on contributes the main-thread handler implementation; the Java core defines the abstraction via MainThreadSupport.
5. Subscriber discovery and optimization
The repo supports two discovery paths:
- Reflection-based scanning of @Subscribe methods at runtime.
- Generated subscriber index via metadata types in EventBus/src/org/greenrobot/eventbus/meta.
The index path avoids expensive reflection and is the recommended production setup. The metadata classes define the contract the annotation processor generates or consumes.
6. Annotation processor module: EventBusAnnotationProcessor/
This module implements EventBusAnnotationProcessor and registers it through the META-INF/services/javax.annotation.processing.Processor entry. Its job is to analyze subscriber classes at compile time and generate index information, which the runtime can later load for faster and safer method lookup.
7. Android-specific module: eventbus-android/
The Android artifact adds the platform bridge for main-thread delivery and logging. Key classes include HandlerPoster, AndroidComponentsImpl, DefaultAndroidMainThreadSupport, and AndroidLogger. This module is the boundary where the core library becomes aware of Android lifecycle/threading primitives without polluting the Java-only core.
8. Android runtime dependency detection
The core module also contains android/AndroidComponents.java and AndroidDependenciesDetector.java, which help the library adapt when Android classes are present or absent. This keeps the core usable in plain Java while still enabling Android behavior when packaged with the Android extension.
9. Utility and failure-handling subsystem
The util/ package provides support functions rather than core dispatch logic. AsyncExecutor handles background execution integration, ExceptionToResourceMapping and ThrowableFailureEvent support error translation/reporting, and HasExecutionScope provides a way to associate execution context with async work. These are secondary helpers around the bus, not the event-routing core.
10. Testing architecture: Java and Android
There are two major test suites:
- EventBusTestJava/ for pure JVM behavior.
- EventBusTest/ for Android-specific behavior.
These suites cover registration, ordering, sticky events, inheritance, thread modes, cancellation, multithreading, and fallback behavior. The split is important because many EventBus guarantees depend on Android lifecycle and main-thread semantics.
11. Indexed-vs-reflection test coverage
The test tree includes many WithIndex variants under EventBusTest/src/.../indexed. These verify that the generated subscriber index produces the same semantics as reflection. That is a key architectural concern in this repo: the runtime is designed to work both with and without compile-time generated metadata.
12. Performance benchmark app: EventBusPerformance/
This is an Android benchmark/measurement app that compares EventBus against alternatives such as Otto. It contains test harness classes like TestRunner, TestRunnerActivity, TestSetupActivity, and benchmark subjects under testsubject/. Its purpose is to measure dispatch and registration performance under realistic Android conditions.
13. Cross-module packaging and published artifacts
The repository builds multiple artifacts: the core EventBus library, the Android artifact, and the annotation processor. The README reflects this split by documenting separate Maven coordinates for Android and Java usage. This is an intentional packaging boundary in the architecture.
14. Tooling and release pipeline
The repo is built with Gradle, uses a GitHub Actions workflow under .github/workflows/gradle.yml, and includes ProGuard/R8 consumer rules for Android distribution. Those pieces matter because they show the library is meant to be consumed as an optimized binary artifact rather than only from source.
15. How to draw the architecture
A good diagram would show:
- Application code on the left posting events and subscribing with @Subscribe.
- The core EventBus engine in the center, with subscription registry, discovery, and dispatch.
- Thread-specific dispatchers around it, including Android main-thread support.
- An optional compile-time annotation processor feeding a subscriber index into runtime discovery.
- Separate validation/benchmark modules off to the side, exercising the same runtime from Java and Android.
Main entry points: EventBus.java EventBus API · greenrobot/eventbus JVM tests · greenrobot/eventbus Android tests · SubscriberMethodFinder.java Method finder
Components 19
Core runtime
Portable EventBus engine, discovery, dispatch, and shared support types.
- EventBus API · Main publish/subscribe entry point used by applications.
EventBus/src/org/greenrobot/eventbus/EventBus.java - Builder · Configures EventBus behavior and wiring before creation.
EventBus/src/org/greenrobot/eventbus/EventBusBuilder.java - Subscriber model · Defines @Subscribe, ThreadMode, SubscriberMethod, and Subscription.
EventBus/src/org/greenrobot/eventbus/Subscribe.java - Method finder · Finds subscriber methods using reflection or generated metadata.
EventBus/src/org/greenrobot/eventbus/SubscriberMethodFinder.java - Subscriber index · Runtime contract for compile-time generated subscriber indices.
EventBus/src/org/greenrobot/eventbus/meta - Dispatch posters · Queues and routes events to async, background, and posting contexts.
EventBus/src/org/greenrobot/eventbus/Poster.java - Main-thread support · Abstracts main-thread execution support for platform-specific implementations.
EventBus/src/org/greenrobot/eventbus/MainThreadSupport.java - Events and errors · No-subscriber, subscriber-exception, and bus exception types.
EventBus/src/org/greenrobot/eventbus/NoSubscriberEvent.java - Utilities · Async execution and failure-reporting helpers around the bus.
EventBus/src/org/greenrobot/eventbus/util - Android detect · Detects Android presence and bridges optional Android components in the core.
EventBus/src/org/greenrobot/eventbus/android/AndroidDependenciesDetector.java
Android extension
Android-specific main-thread and platform integration.
- Handler poster · Android main-thread poster built on Handler semantics.
eventbus-android/src/main/java/org/greenrobot/eventbus/HandlerPoster.java - Android bridge · Provides Android component wiring used by the core runtime on Android.
eventbus-android/src/main/java/org/greenrobot/eventbus/android/AndroidComponentsImpl.java - Main-thread impl · Default Android main-thread support implementation.
eventbus-android/src/main/java/org/greenrobot/eventbus/android/DefaultAndroidMainThreadSupport.java - Android logger · Android-specific logger implementation.
eventbus-android/src/main/java/org/greenrobot/eventbus/android/AndroidLogger.java
Tooling and validation
Compile-time processor, tests, benchmark app, and support jar used to validate the library.
- Annotation processor · Generates subscriber index metadata from @Subscribe usage.
EventBusAnnotationProcessor/src/org/greenrobot/eventbus/annotationprocessor/EventBusAnnotationProcessor.java - JVM tests · Pure Java behavior tests for registration, inheritance, threading, and sticky events.
EventBusTestJava/src/main/java/org/greenrobot/eventbus - Android tests · Android behavior tests, including main-thread and multithreaded delivery.
EventBusTest/src/org/greenrobot/eventbus - Benchmarks · Android performance app comparing EventBus with alternatives.
EventBusPerformance/src/org/greenrobot/eventbusperf - Jar fixture · Packaged subscriber class used by test suites.
EventBusTestSubscriberInJar/src/org/greenrobot/eventbus/SubscriberInJar.java
Connections 22
- Builder → EventBus API: creates/configures · Builder feeds configured instances of the bus.
- EventBus API → Subscriber model: uses · Public API is driven by subscriber annotations and thread modes.
- EventBus API → Method finder: discovers · Bus resolves subscriber methods through the finder.
- Method finder → Subscriber index: loads index · Uses generated metadata when available.
- Method finder → Subscriber model: reflects · Falls back to scanning @Subscribe methods at runtime.
- EventBus API → Dispatch posters: dispatches · Event posting is routed through poster implementations.
- Dispatch posters → Main-thread support: needs · Main-thread delivery depends on the platform abstraction.
- Main-thread support → Main-thread impl: implemented by · Android module supplies the concrete main-thread support.
- Dispatch posters → Handler poster: main thread · Android handler-based poster handles UI-thread delivery.
- EventBus API → Events and errors: reports · No-subscriber and subscriber-failure events originate here.
- EventBus API → Utilities: helpers · Async and failure helper utilities support the bus.
- Android detect → Android bridge: bridges · Core Android detection connects to Android-specific components.
- Android detect → Handler poster: enables · Android presence activates handler-based dispatch.
- Android bridge → Android logger: logs with · Android bridge uses the Android logger.
- Annotation processor → Subscriber index: generates · Compile-time processor produces subscriber index metadata.
- JVM tests → EventBus API: exercises · JVM tests validate core runtime behavior.
- JVM tests → Annotation processor: verifies index · Tests cover indexed and reflection-based discovery.
- Android tests → EventBus API: exercises · Android tests validate delivery semantics on device/emulator.
- Android tests → Handler poster: covers · Tests verify Android main-thread poster behavior.
- Benchmarks → EventBus API: measures · Benchmark app times EventBus registration and dispatch.
- JVM tests → Jar fixture: imports · Fixture jar is used by JVM tests.
- Android tests → Jar fixture: imports · Fixture jar is also used in Android test coverage.