Disruptor for Java: Complete Guide with Examples

1. What Is It and Why Use It

Disruptor is a high-performance library for inter-thread communication (IPC) in Java, developed by LMAX. It's designed to transfer data between threads with minimal latency and maximum throughput. Unlike traditional queues (e.g., LinkedBlockingQueue), Disruptor uses a fixed-size ring buffer, eliminating overhead from memory allocation, synchronization, and garbage collection.

The core problem Disruptor solves is thread contention for resources. In traditional queues, multiple producers and consumers compete for locks, causing idle time and performance drops. Disruptor uses sequence barriers and optimistic locking (CAS — Compare-And-Swap), achieving microsecond-level latency and millions of messages per second.

This library is ideal for systems where event processing speed is critical: trading platforms, game servers, log processing systems, and high-traffic web applications. Disruptor powers many modern frameworks, including Apache Storm and several Event Sourcing implementations.

2. Setup

Disruptor is distributed via Maven Central. To use it in your project, add the dependency to your pom.xml (Maven):

<dependency>
    <groupId>com.lmax</groupId>
    <artifactId>disruptor</artifactId>
    <version>4.0.0</version>
</dependency>

For Gradle (build.gradle):

implementation 'com.lmax:disruptor:4.0.0'

If you use another dependency manager, download the JAR from Maven Central.

3. Quick Start — Minimal Working Example

In this example, we'll create a simple Disruptor that accepts string events and prints them to the console.

import com.lmax.disruptor.*;
import com.lmax.disruptor.dsl.Disruptor;
import com.lmax.disruptor.util.DaemonThreadFactory;

// 1. Define the event class
public class StringEvent {
    private String value;

    public String getValue() { return value; }
    public void setValue(String value) { this.value = value; }
}

// 2. Event factory (creates empty events for reuse)
public class StringEventFactory implements EventFactory<StringEvent> {
    @Override
    public StringEvent newInstance() {
        return new StringEvent();
    }
}

// 3. Event handler (Consumer)
public class StringEventHandler implements EventHandler<StringEvent> {
    @Override
    public void onEvent(StringEvent event, long sequence, boolean endOfBatch) {
        System.out.println("Received: " + event.getValue());
    }
}

// 4. Main class
public class QuickStart {
    public static void main(String[] args) throws InterruptedException {
        // Ring buffer size (must be a power of 2)
        int bufferSize = 1024;

        // Create the Disruptor
        Disruptor<StringEvent> disruptor = new Disruptor<>(
            new StringEventFactory(),
            bufferSize,
            DaemonThreadFactory.INSTANCE
        );

        // Connect the handler
        disruptor.handleEventsWith(new StringEventHandler());

        // Start the Disruptor
        disruptor.start();

        // Get a reference to the RingBuffer
        RingBuffer<StringEvent> ringBuffer = disruptor.getRingBuffer();

        // Publish events
        for (int i = 0; i < 10; i++) {
            long sequence = ringBuffer.next(); // Claim the slot
            try {
                StringEvent event = ringBuffer.