# greenrobot/eventbus architecture

> Architecture diagram of the GitHub repository greenrobot/eventbus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/greenrobot/eventbus
- Repository: https://github.com/greenrobot/eventbus

## Overview

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/src/org/greenrobot/eventbus/EventBus.java`](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/EventBus.java) (EventBus API), [`EventBusTestJava/src/main/java/org/greenrobot/eventbus`](https://github.com/greenrobot/eventbus/tree/master/EventBusTestJava/src/main/java/org/greenrobot/eventbus) (JVM tests), [`EventBusTest/src/org/greenrobot/eventbus`](https://github.com/greenrobot/eventbus/tree/master/EventBusTest/src/org/greenrobot/eventbus) (Android tests), [`EventBus/src/org/greenrobot/eventbus/SubscriberMethodFinder.java`](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/SubscriberMethodFinder.java) (Method finder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_api["EventBus API<br/>runtime entry<br/>[EventBus.java]"]
  node_builder["Builder<br/>config setup"]
  node_subscriber_contract["Subscriber model<br/>annotations + types<br/>[Subscribe.java]"]
  node_finder["Method finder<br/>discovery"]
  node_meta["Subscriber index<br/>generated metadata"]
  node_posters["Dispatch posters<br/>thread routing<br/>[Poster.java]"]
  node_main_support["Main-thread support<br/>abstraction"]
  node_errors["Events and errors<br/>failure model"]
  node_util["Utilities<br/>support helpers"]
  node_android_detect["Android detect<br/>platform probe"]
end

subgraph group_android["Android extension"]
  node_android_poster["Handler poster<br/>android dispatch<br/>[HandlerPoster.java]"]
  node_android_impl["Android bridge<br/>platform integration"]
  node_android_main["Main-thread impl<br/>android support"]
  node_android_log["Android logger<br/>logging<br/>[AndroidLogger.java]"]
end

subgraph group_tooling["Tooling and validation"]
  node_processor["Annotation processor<br/>compile-time tool"]
  node_tests_java["JVM tests<br/>validation suite"]
  node_tests_android["Android tests<br/>validation suite"]
  node_benchmarks["Benchmarks<br/>perf app"]
  node_subscriber_jar["Jar fixture<br/>test support"]
end

node_builder -->|"creates/configures"| node_api
node_api -->|"uses"| node_subscriber_contract
node_api -->|"discovers"| node_finder
node_finder -->|"loads index"| node_meta
node_finder -->|"reflects"| node_subscriber_contract
node_api -->|"dispatches"| node_posters
node_posters -->|"needs"| node_main_support
node_main_support -->|"implemented by"| node_android_main
node_posters -->|"main thread"| node_android_poster
node_api -->|"reports"| node_errors
node_api -->|"helpers"| node_util
node_android_detect -->|"bridges"| node_android_impl
node_android_detect -->|"enables"| node_android_poster
node_android_impl -->|"logs with"| node_android_log
node_processor -->|"generates"| node_meta
node_tests_java -->|"exercises"| node_api
node_tests_java -->|"verifies index"| node_processor
node_tests_android -->|"exercises"| node_api
node_tests_android -->|"covers"| node_android_poster
node_benchmarks -->|"measures"| node_api
node_tests_java -->|"imports"| node_subscriber_jar
node_tests_android -->|"imports"| node_subscriber_jar

click node_api "https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/EventBus.java"
click node_builder "https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/EventBusBuilder.java"
click node_subscriber_contract "https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/Subscribe.java"
click node_finder "https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/SubscriberMethodFinder.java"
click node_meta "https://github.com/greenrobot/eventbus/tree/master/EventBus/src/org/greenrobot/eventbus/meta"
click node_posters "https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/Poster.java"
click node_main_support "https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/MainThreadSupport.java"
click node_errors "https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/NoSubscriberEvent.java"
click node_util "https://github.com/greenrobot/eventbus/tree/master/EventBus/src/org/greenrobot/eventbus/util"
click node_android_detect "https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/android/AndroidDependenciesDetector.java"
click node_android_poster "https://github.com/greenrobot/eventbus/blob/master/eventbus-android/src/main/java/org/greenrobot/eventbus/HandlerPoster.java"
click node_android_impl "https://github.com/greenrobot/eventbus/blob/master/eventbus-android/src/main/java/org/greenrobot/eventbus/android/AndroidComponentsImpl.java"
click node_android_main "https://github.com/greenrobot/eventbus/blob/master/eventbus-android/src/main/java/org/greenrobot/eventbus/android/DefaultAndroidMainThreadSupport.java"
click node_android_log "https://github.com/greenrobot/eventbus/blob/master/eventbus-android/src/main/java/org/greenrobot/eventbus/android/AndroidLogger.java"
click node_processor "https://github.com/greenrobot/eventbus/blob/master/EventBusAnnotationProcessor/src/org/greenrobot/eventbus/annotationprocessor/EventBusAnnotationProcessor.java"
click node_tests_java "https://github.com/greenrobot/eventbus/tree/master/EventBusTestJava/src/main/java/org/greenrobot/eventbus"
click node_tests_android "https://github.com/greenrobot/eventbus/tree/master/EventBusTest/src/org/greenrobot/eventbus"
click node_benchmarks "https://github.com/greenrobot/eventbus/tree/master/EventBusPerformance/src/org/greenrobot/eventbusperf"
click node_subscriber_jar "https://github.com/greenrobot/eventbus/blob/master/EventBusTestSubscriberInJar/src/org/greenrobot/eventbus/SubscriberInJar.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_builder,node_subscriber_contract,node_finder,node_meta,node_posters,node_main_support,node_errors,node_util,node_android_detect toneBlue
class node_android_poster,node_android_impl,node_android_main,node_android_log toneAmber
class node_processor,node_tests_java,node_tests_android,node_benchmarks,node_subscriber_jar toneMint
```

## Components

### Core runtime

Portable EventBus engine, discovery, dispatch, and shared support types.

- [EventBus API](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/EventBus.java): runtime entry · Main publish/subscribe entry point used by applications. · `EventBus/src/org/greenrobot/eventbus/EventBus.java`
- [Builder](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/EventBusBuilder.java): config setup · Configures EventBus behavior and wiring before creation. · `EventBus/src/org/greenrobot/eventbus/EventBusBuilder.java`
- [Subscriber model](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/Subscribe.java): annotations + types · Defines @Subscribe, ThreadMode, SubscriberMethod, and Subscription. · `EventBus/src/org/greenrobot/eventbus/Subscribe.java`
- [Method finder](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/SubscriberMethodFinder.java): discovery · Finds subscriber methods using reflection or generated metadata. · `EventBus/src/org/greenrobot/eventbus/SubscriberMethodFinder.java`
- [Subscriber index](https://github.com/greenrobot/eventbus/tree/master/EventBus/src/org/greenrobot/eventbus/meta): generated metadata · Runtime contract for compile-time generated subscriber indices. · `EventBus/src/org/greenrobot/eventbus/meta`
- [Dispatch posters](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/Poster.java): thread routing · Queues and routes events to async, background, and posting contexts. · `EventBus/src/org/greenrobot/eventbus/Poster.java`
- [Main-thread support](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/MainThreadSupport.java): abstraction · Abstracts main-thread execution support for platform-specific implementations. · `EventBus/src/org/greenrobot/eventbus/MainThreadSupport.java`
- [Events and errors](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/NoSubscriberEvent.java): failure model · No-subscriber, subscriber-exception, and bus exception types. · `EventBus/src/org/greenrobot/eventbus/NoSubscriberEvent.java`
- [Utilities](https://github.com/greenrobot/eventbus/tree/master/EventBus/src/org/greenrobot/eventbus/util): support helpers · Async execution and failure-reporting helpers around the bus. · `EventBus/src/org/greenrobot/eventbus/util`
- [Android detect](https://github.com/greenrobot/eventbus/blob/master/EventBus/src/org/greenrobot/eventbus/android/AndroidDependenciesDetector.java): platform probe · 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](https://github.com/greenrobot/eventbus/blob/master/eventbus-android/src/main/java/org/greenrobot/eventbus/HandlerPoster.java): android dispatch · Android main-thread poster built on Handler semantics. · `eventbus-android/src/main/java/org/greenrobot/eventbus/HandlerPoster.java`
- [Android bridge](https://github.com/greenrobot/eventbus/blob/master/eventbus-android/src/main/java/org/greenrobot/eventbus/android/AndroidComponentsImpl.java): platform integration · 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](https://github.com/greenrobot/eventbus/blob/master/eventbus-android/src/main/java/org/greenrobot/eventbus/android/DefaultAndroidMainThreadSupport.java): android support · Default Android main-thread support implementation. · `eventbus-android/src/main/java/org/greenrobot/eventbus/android/DefaultAndroidMainThreadSupport.java`
- [Android logger](https://github.com/greenrobot/eventbus/blob/master/eventbus-android/src/main/java/org/greenrobot/eventbus/android/AndroidLogger.java): logging · 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](https://github.com/greenrobot/eventbus/blob/master/EventBusAnnotationProcessor/src/org/greenrobot/eventbus/annotationprocessor/EventBusAnnotationProcessor.java): compile-time tool · Generates subscriber index metadata from @Subscribe usage. · `EventBusAnnotationProcessor/src/org/greenrobot/eventbus/annotationprocessor/EventBusAnnotationProcessor.java`
- [JVM tests](https://github.com/greenrobot/eventbus/tree/master/EventBusTestJava/src/main/java/org/greenrobot/eventbus): validation suite · Pure Java behavior tests for registration, inheritance, threading, and sticky events. · `EventBusTestJava/src/main/java/org/greenrobot/eventbus`
- [Android tests](https://github.com/greenrobot/eventbus/tree/master/EventBusTest/src/org/greenrobot/eventbus): validation suite · Android behavior tests, including main-thread and multithreaded delivery. · `EventBusTest/src/org/greenrobot/eventbus`
- [Benchmarks](https://github.com/greenrobot/eventbus/tree/master/EventBusPerformance/src/org/greenrobot/eventbusperf): perf app · Android performance app comparing EventBus with alternatives. · `EventBusPerformance/src/org/greenrobot/eventbusperf`
- [Jar fixture](https://github.com/greenrobot/eventbus/blob/master/EventBusTestSubscriberInJar/src/org/greenrobot/eventbus/SubscriberInJar.java): test support · Packaged subscriber class used by test suites. · `EventBusTestSubscriberInJar/src/org/greenrobot/eventbus/SubscriberInJar.java`

## Connections

- 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.
