How lmax-exchange/disruptor works
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