# lmax-exchange/disruptor architecture

> Architecture diagram of the GitHub repository lmax-exchange/disruptor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lmax-exchange/disruptor
- Repository: https://github.com/lmax-exchange/disruptor

## Overview

##### Project Type and Purpose
- This is a Java library (LMAX Disruptor) that provides a high-performance inter-thread messaging framework. It is not a web application or microservice; it is an embeddable concurrency library used to build low-latency pipelines in JVM applications.

##### File Structure
- src/main/java/com/lmax/disruptor: core library classes (RingBuffer, Sequencer, WaitStrategy, EventProcessor, DSL)
- src/main/java/com/lmax/disruptor/dsl: fluent API (“Disruptor” class) for wiring producers to consumers
- src/main/java/com/lmax/disruptor/util: helpers (thread factory, hints)
- src/examples: sample usage patterns (pipelines, batching, exception handling)
- src/jmh, src/jcstress, src/perftest: benchmarks and stress tests showing performance characteristics
- config/, gradle/: build, CI, style & testing configuration
- src/docs: user- and developer- guides

##### README
- Describes the library’s goal: “A High Performance Inter-Thread Messaging Library”
- References user guide, API docs, developer guide

##### Components
a. Main Components
- Producers (application threads using EventTranslator)
- RingBuffer (circular data store)
- Sequencer (slot claims, gating sequences)
- WaitStrategy implementations (BusySpin, Blocking, Yielding, etc.)
- SequenceBarrier (synchronizes processors)
- EventProcessor/BatchEventProcessor (consumer threads)
- EventHandlers (business logic consumers)
- DSL layer (Disruptor class that ties it all together)
- Optional: ThreadFactory, ExceptionHandler plug-points

b. Relationships & Data Flow
1. Producers call Disruptor.publish(…):
– Claim a sequence via Sequencer
– Write event into RingBuffer slot
– Commit sequence so consumers can see it
2. Sequencer updates gating sequences used by SequenceBarrier
3. EventProcessors block or spin by invoking WaitStrategy.waitFor(sequence) on the barrier
4. Once events are available, EventProcessor reads from RingBuffer and invokes EventHandlers
5. Handlers can form pipelines (handler A → handler B) or parallel groups
6. On exceptions or shutdown, ExceptionHandler and Rewind strategies come into play

c. Architectural Patterns & Principles
- Fluent DSL: Disruptor API for wiring components
- Producer/Consumer ring buffer pattern (bounded circular queue)
- Pluggable wait strategies to trade off latency vs. CPU usage
- Explicit sequencing to avoid locks and false sharing
- Support for dynamic handler graphs (pipelines, fan-out/fan-in)

d. Key Technologies & Frameworks
- Java 8+ with java.util.concurrent
- Gradle build with plugins for Asciidoc, JMH, JCStress
- JMH benchmarks and JCStress suite for performance validation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% DSL Layer
    subgraph "DSL Configuration Layer"
        DSL["Disruptor"]:::dsl
        CR["ConsumerRepository"]:::dsl
        EHG["EventHandlerGroup"]:::dsl
        EPF["EventProcessorFactory"]:::dsl
        EHS["ExceptionHandlerSetting"]:::dsl
    end

    %% Producer Layer
    subgraph "Producer Layer"
        Prod["Producers\n(EventTranslator API)"]:::producer
    end

    %% Core Components
    subgraph "Core Components"
        Ring["RingBuffer"]:::core
        subgraph "Sequencer Implementations"
            Seq["Sequencer"]:::core
            AbsSeq["AbstractSequencer"]:::core
            MPS["MultiProducerSequencer"]:::core
            SPS["SingleProducerSequencer"]:::core
        end
        subgraph "Sequence Abstractions"
            Sequence["Sequence"]:::core
            SeqGroup["SequenceGroup"]:::core
            FixedSeq["FixedSequenceGroup"]:::core
        end
    end

    %% Barrier Layer
    subgraph "Barrier Layer"
        SB["SequenceBarrier"]:::barrier
        PSB["ProcessingSequenceBarrier"]:::barrier
    end

    %% Wait Strategies
    subgraph "WaitStrategy Implementations"
        WS["WaitStrategy"]:::strategy
        BS["BusySpinWaitStrategy"]:::strategy
        BL["BlockingWaitStrategy"]:::strategy
        YS["YieldingWaitStrategy"]:::strategy
        LB["LiteBlockingWaitStrategy"]:::strategy
        LTB["LiteTimeoutBlockingWaitStrategy"]:::strategy
        SL["SleepingWaitStrategy"]:::strategy
        PB["PhasedBackoffWaitStrategy"]:::strategy
        TB["TimeoutBlockingWaitStrategy"]:::strategy
    end

    %% Processor Layer
    subgraph "Processor Layer"
        EP["EventProcessor"]:::processor
        BEP["BatchEventProcessor"]:::processor
        BEPB["BatchEventProcessorBuilder"]:::processor
    end

    %% Handler Layer
    subgraph "EventHandler Layer"
        EH["EventHandler"]:::handler
        AEH["AggregateEventHandler"]:::handler
        REH["RewindableEventHandler"]:::handler
        EHB["EventHandlerBase"]:::handler
    end

    %% Exception & Utilities
    subgraph "Exception Handling"
        EXH["ExceptionHandler"]:::exception
        EXHS["ExceptionHandlers"]:::exception
        FEH["FatalExceptionHandler"]:::exception
        IEH["IgnoreExceptionHandler"]:::exception
    end
    subgraph "Utilities"
        TF["DaemonThreadFactory"]:::util
        TH["ThreadHints"]:::util
        U["Util"]:::util
    end

    %% Data Flow
    DSL -->|"configure producers"| Prod
    DSL -->|"configure consumers"| BEP
    Prod -->|"publish()"| Seq
    Seq -->|"claim()"| Ring
    Ring -->|"cursor update"| Sequence
    Sequence -->|"gating seqs"| AbsSeq
    AbsSeq --> MPS
    AbsSeq --> SPS
    Ring -->|"available events"| SB
    SB -->|"create barrier"| PSB
    PSB -->|"waitFor()"| BS
    PSB -->|"waitFor()"| BL
    PSB -->|"waitFor()"| YS
    PSB -->|"waitFor()"| LB
    PSB -->|"waitFor()"| LTB
    PSB -->|"waitFor()"| SL
    PSB -->|"waitFor()"| PB
    PSB -->|"waitFor()"| TB
    PSB -->|"signal processors"| EP
    EP -->|"process"| EH
    EH -->|"chain"| AEH
    AEH -->|"chain"| REH
    EH -->|"extends"| EHB
    BEP --> EP
    BEP --> BEPB
    BEPB --> EP

    %% Exception Hooks
    EP -->|"onException"| EXH
    EXH --> EXHS
    EXH --> FEH
    EXH --> IEH

    %% Utilities Usage
    DSL --> TF
    Prod --> TF
    BS --> TH
    PB --> TH
    BL --> U

    %% Click Events
    click Prod "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/EventTranslator.java"
    click Ring "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/RingBuffer.java"
    click Seq "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/Sequencer.java"
    click AbsSeq "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/AbstractSequencer.java"
    click MPS "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/MultiProducerSequencer.java"
    click SPS "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/SingleProducerSequencer.java"
    click WS "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/WaitStrategy.java"
    click BS "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/BusySpinWaitStrategy.java"
    click BL "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/BlockingWaitStrategy.java"
    click YS "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/YieldingWaitStrategy.java"
    click LB "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/LiteBlockingWaitStrategy.java"
    click LTB "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/LiteTimeoutBlockingWaitStrategy.java"
    click SL "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/SleepingWaitStrategy.java"
    click PB "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/PhasedBackoffWaitStrategy.java"
    click TB "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/TimeoutBlockingWaitStrategy.java"
    click SB "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/SequenceBarrier.java"
    click PSB "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/ProcessingSequenceBarrier.java"
    click EP "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/EventProcessor.java"
    click BEP "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/BatchEventProcessor.java"
    click BEPB "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/BatchEventProcessorBuilder.java"
    click EH "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/EventHandler.java"
    click AEH "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/AggregateEventHandler.java"
    click REH "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/RewindableEventHandler.java"
    click EHB "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/EventHandlerBase.java"
    click DSL "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/dsl/Disruptor.java"
    click CR "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/dsl/ConsumerRepository.java"
    click EHG "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/dsl/EventHandlerGroup.java"
    click EPF "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/dsl/EventProcessorFactory.java"
    click EHS "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/dsl/ExceptionHandlerSetting.java"
    click EXH "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/ExceptionHandler.java"
    click EXHS "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/ExceptionHandlers.java"
    click FEH "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/FatalExceptionHandler.java"
    click IEH "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/IgnoreExceptionHandler.java"
    click TF "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/util/DaemonThreadFactory.java"
    click TH "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/util/ThreadHints.java"
    click U "https://github.com/lmax-exchange/disruptor/blob/master/src/main/java/com/lmax/disruptor/util/Util.java"

    %% Styles
    classDef producer fill:#d4f4dd,stroke:#2d8f3c,color:#084c0f;
    classDef core fill:#d0e1f9,stroke:#2c5f92,color:#112f56;
    classDef barrier fill:#ecd5f3,stroke:#8a2be2,color:#4b0082;
    classDef strategy fill:#f3e6c9,stroke:#c47f00,color:#804000;
    classDef processor fill:#ffe5b4,stroke:#e69500,color:#993d00;
    classDef handler fill:#fff7b2,stroke:#e6c200,color:#7f6600;
    classDef dsl fill:#e0e0e0,stroke:#7f7f7f,color:#333333;
    classDef exception fill:#f8d7da,stroke:#d9534f,color:#842029;
    classDef util fill:#d1f7f2,stroke:#29a3a3,color:#0d5151;
```
