# LMAX Disruptor — High-Performance Inter-Thread Messaging for Java

> A low-latency, lock-free ring buffer library for Java that achieves millions of operations per second, widely used in trading systems and high-throughput event processing.

## Install

Save in your project root:

# LMAX Disruptor — High-Performance Inter-Thread Messaging for Java

## Quick Use
```xml
<dependency>
  <groupId>com.lmax</groupId>
  <artifactId>disruptor</artifactId>
  <version>4.0.0</version>
</dependency>
```
```java
Disruptor<OrderEvent> disruptor = new Disruptor<>(
    OrderEvent::new, 1024, DaemonThreadFactory.INSTANCE);
disruptor.handleEventsWith((event, seq, end) ->
    process(event));
disruptor.start();
RingBuffer<OrderEvent> rb = disruptor.getRingBuffer();
rb.publishEvent((e, seq) -> e.setPrice(99.5));
```

## Introduction
The LMAX Disruptor is a ring-buffer-based messaging framework created by LMAX Exchange to power their financial trading platform. It replaces traditional queues with a mechanical-sympathy design that minimizes lock contention, false sharing, and garbage collection pressure.

## What the Disruptor Does
- Provides a lock-free ring buffer for passing events between producer and consumer threads
- Achieves single-digit microsecond latencies for inter-thread communication
- Supports multiple consumer patterns: pipeline, diamond, and broadcast topologies
- Eliminates garbage collection pauses by pre-allocating event objects in the ring
- Delivers predictable, low-jitter throughput under sustained high load

## Architecture Overview
The Disruptor uses a fixed-size ring buffer backed by a pre-allocated array. Producers claim slots via an atomic sequence counter, write data, and publish. Consumers track their own sequence cursors and spin-wait or use a WaitStrategy for new events. The design avoids locks, minimizes cache-line contention through padding, and keeps allocation on the hot path to zero.

## Self-Hosting & Configuration
- Add the Maven dependency to your Java project (JDK 11+ for v4.x)
- Choose a WaitStrategy: BusySpinWaitStrategy for lowest latency, SleepingWaitStrategy for lower CPU
- Set the ring buffer size to a power of two for optimal index masking
- Wire event handlers in the desired topology using handleEventsWith() and then()
- No external services or configuration files are required

## Key Features
- Mechanical-sympathy design aligned with CPU cache architecture
- Pre-allocated, GC-free event passing in the hot path
- Pluggable wait strategies to trade latency for CPU usage
- Supports batching: consumers process ranges of events efficiently
- Battle-tested in production at LMAX Exchange handling millions of orders per second

## Comparison with Similar Tools
- **java.util.concurrent queues** — ArrayBlockingQueue and LinkedBlockingQueue use locks; the Disruptor is lock-free and faster
- **Chronicle Queue** — persistent, memory-mapped queue for inter-process messaging; the Disruptor is in-process only but lower latency
- **Aeron** — UDP-based messaging for inter-machine IPC; the Disruptor focuses on intra-JVM threading
- **Akka Actors** — actor-based concurrency model; the Disruptor is a lower-level primitive for maximum throughput

## FAQ
**Q: When should I use the Disruptor over standard Java queues?**
A: When inter-thread latency and throughput are critical, such as trading engines, event sourcing, and log aggregation pipelines.

**Q: Does it support multiple producers?**
A: Yes. Use ProducerType.MULTI when constructing the Disruptor for safe concurrent publishing.

**Q: What happens when the ring buffer is full?**
A: The producer blocks (or spins) until a consumer advances, applying natural back-pressure.

**Q: Is it used outside of finance?**
A: Yes. Log4j2 uses the Disruptor for its async loggers, and it appears in game servers, messaging systems, and data pipelines.

## Sources
- https://github.com/LMAX-Exchange/disruptor
- https://lmax-exchange.github.io/disruptor/

---
Source: https://tokrepo.com/en/workflows/asset-42a6bda0
Author: AI Open Source