Disruptors

Configure LMAX Disruptor ring buffers for inter-thread communication in Rumi microservices.

Prerequisites: Before diving into configuration, review the Threading Model page to understand the architectural concepts and design rationale behind Rumi's threading architecture.

Overview

Rumi uses LMAX Disruptors to pass data between critical threads in the processing pipeline. Disruptors provide ultra-low latency inter-thread communication using ring buffers and wait strategies optimized for different performance characteristics.

Throughout Rumi configuration you'll see disruptor configuration that looks like:

<persistence enabled="true">
  <detachedPersist enabled="true">
    <queueDepth></queueDepth>
    <queueOfferStrategy></queueOfferStrategy>
    <queueWaitStrategy></queueWaitStrategy>
    <queueDrainerCpuAffinityMask></queueDrainerCpuAffinityMask>
  </detachedPersist>
</persistence>

Disruptor Parameters

Parameter	Description
queueDepth	The size of the ring buffer. This knob controls the size of the ring buffer. It is best to choose a power of 2 for ring buffer. The buffer should be sized large enough to absorb spikes in microservice traffic without blocking the offering thread, but otherwise should generally be kept small enough to keep the amount of active data in the pipeline small enough to avoid taxing CPU caches. The default size for most disruptors is 1024.
queueWaitStrategy	Controls how the thread draining events from the ring buffer waits for more events. One of BusySpin, Yielding, Sleeping, Blocking. For microservices that want the lowest latency possible using BusySpin causes the draining thread to spin without signaling to the OS that it should be context switched which avoids jitter. This policy is most appropriate when the number of cores available in the machine is adequate for each reader to occupy its own core. Otherwise, a Yielding wait strategy can be used. Both BusySpin and Yielding are CPU intensive and are most appropriate for microservices where performance is critical and run on hardware dedicated to the microservice.
queueDrainerCpuAffinityMask	Controls the CPU to which to affinitize the draining thread. For BusySpin or Yielding policies, affinitizing threads can further reduce jitter. See Thread Affinitization for details.
queueOfferStrategy	This can be used to override the offer strategy used to manage concurrency when offering elements to the ring buffer. Warning: In general, microservices should not change this property as the platform will choose a sensible default.

Auto-Tuning of Disruptor Wait Strategies

When the nv.optimizefor environment property is set to latency or throughput, disruptors in the critical path are automatically set to BusySpin and Yielding respectively unless explicitly configured otherwise via configuration.

You can set the environment property:

<env>
  <nv.optimizefor>latency</nv.optimizefor>
  <nv.conservecpu>true</nv.conservecpu>
</env>

Related Topics

• Threading Model - Architectural concepts and design rationale

• Thread Reference - Complete reference of all threads in a Rumi container

• Thread Affinitization - Pin threads to CPU cores for optimal performance

• DDL Reference - Complete DDL syntax reference

Next Steps

1. Review the Threading Model to understand disruptor usage

2. Identify which disruptors are in your microservice's critical path

3. Configure wait strategies based on your performance requirements

4. Consider Thread Affinitization for disruptor drainer threads