Introduction to LMAX Disruptor: High‑Performance Java Memory Queue and Its Core Concepts

Disruptor Introduction

Disruptor is an open‑source high‑performance memory queue developed by the UK forex trading company LMAX, which won Oracle's 2011 Duke's Choice Award.

"The Duke's Choice Award" honors the most influential Java technology projects of the year, sponsored by Oracle.

The award article (https://blogs.oracle.com/java/post/and-the-winners-arethe-dukes-choice-award) also lists other winners such as Netty and JRebel.

Several well‑known open‑source projects have adopted Disruptor , for example the high‑performance Java logging framework Log4j 2 and Ant Financial's distributed tracing component SOFATracer , both of which use Disruptor for asynchronous logging.

Disruptor offers functionality similar to distributed queues like Kafka and RocketMQ , but its scope is limited to the JVM (in‑memory).

GitHub: https://github.com/LMAX-Exchange/disruptor

Official tutorial: https://lmax-exchange.github.io/disruptor/user-guide/index.html

Disruptor solves the performance and memory‑safety problems of the built‑in JDK thread‑safe queues.

Common JDK thread‑safe queues:

Queue Name

Lock

Bounded?

ArrayBlockingQueue

Lock (

ReentrantLock

)

Bounded

LinkedBlockingQueue

Lock (

ReentrantLock

)

Bounded

LinkedTransferQueue

Lock‑free (

CAS

)

Unbounded

ConcurrentLinkedQueue

Lock‑free (

CAS

)

Unbounded

These queues are either locked (which hurts performance) or unbounded (which risks OOM). Therefore, the built‑in JDK queues are generally not recommended.

In contrast, Disruptor can be lock‑free, bounded, and thread‑safe.

Disruptor Core Concepts

Event : the message object stored in the queue awaiting consumption.

EventFactory : creates events; required when initializing a Disruptor instance.

EventHandler : processes events; analogous to the consumer in a producer‑consumer model.

EventProcessor : holds the consumer's Sequence and runs the event loop.

Disruptor : the main object that ties producers and consumers together.

RingBuffer : a circular array that stores events.

WaitStrategy : determines how consumers wait when no events are available.

Producer : the code that publishes events to the Disruptor .

ProducerType : specifies single‑producer or multi‑producer mode.

Sequencer : the core component that coordinates data transfer between producers and consumers; implementations include SingleProducerSequencer and MultiProducerSequencer .

Disruptor Practical Example

The following steps build a basic producer‑consumer model using Disruptor:

Define an Event : a class representing a log message.

Create an EventFactory that implements EventFactory<LogEvent> and returns a new LogEvent instance.

Create an EventHandler that implements EventHandler<LogEvent> and prints the message in onEvent .

Initialize Disruptor with five parameters (eventFactory, ringBufferSize, threadFactory, producerType, waitStrategy). Example code: private static Disruptor<LogEvent> getLogEventDisruptor() { LogEventFactory logEventFactory = new LogEventFactory(); int bufferSize = 1024 * 1024; ThreadFactory threadFactory = new ThreadFactory() { final AtomicInteger threadNum = new AtomicInteger(0); @Override public Thread newThread(Runnable r) { return new Thread(r, "LogEventThread [" + threadNum.incrementAndGet() + "]"); } }; return new Disruptor<>(logEventFactory, bufferSize, threadFactory, ProducerType.SINGLE, new BlockingWaitStrategy()); }

Publish Events : Disruptor<LogEvent> disruptor = getLogEventDisruptor(); disruptor.handleEventsWith(new LogEventHandler()); Disruptor.start(); RingBuffer<LogEvent> ringBuffer = disruptor.getRingBuffer(); for (int i = 1; i <= 100000; i++) { long sequence = ringBuffer.next(); try { LogEvent logEvent = ringBuffer.get(sequence); logEvent.setMessage("This is log message %d".formatted(i)); } finally { ringBuffer.publish(sequence); } } Disruptor.shutdown();

Result : The console prints messages from 1 to 100 000, confirming successful processing.

Summary

Disruptor provides functionality similar to distributed queues like Kafka and RocketMQ , but operates entirely within JVM memory, offering lock‑free, bounded, and thread‑safe performance ideal for high‑throughput producer‑consumer scenarios.

GitHub: https://github.com/LMAX-Exchange/disruptor

Official tutorial: https://lmax-exchange.github.io/disruptor/user-guide/index.html

References

[1] Log4j 2: https://github.com/apache/logging-log4j2

[2] SOFATracer: https://github.com/sofastack/sofa-tracer

[3] SOFATracer Disruptor practice (with source): https://www.sofastack.tech/blog/sofa-trcaer-disruptor-practice/