Crate disruptor

Low latency library for inter-thread communication.

Use it when a single thread is not enough and you need multiple threads to communicate with the lowest latency possible.

General Usage

The usage can be divided into three stages:

1. Setup: Build the Disruptor and setup consumers including any interdependencies.
2. Publish: Publish into the Disruptor.
3. Shutdown: Stop all consumer threads and drop the Disruptor and the consumer(s).

The Disruptor in this library can only be used once. I.e. it cannot be rewound and restarted.

It also owns and manages the processing thread(s) for the convenience of the library users.

Setup

When the Disruptor is created, you choose whether publication to the Disruptor will happen from one or multiple threads via Producer handles. The size of the RingBuffer is also specified and you have to provide a “factory” closure for initializing the events inside the RingBufffer. Then all consumers are added.

Use either build_single_producer or build_multi_producer to get started.

Publish

Once the Disruptor is built, you have a Producer “handle” which can be used to publish into the Disruptor. In case of a multi producer Disruptor, the Producer can be cloned so that each publishing thread has its own handle.

Shutdown

Finally, when there’s no more events to publish and the last Producer goes out of scope, all events published are processed and then the processing thread(s) will be stopped and the entire Disruptor will be dropped including consumers.

Examples

use disruptor::*;

// *** Phase SETUP ***

// The data entity on the ring buffer.
struct Event {
    price: f64
}

// Define a factory for populating the ring buffer with events.
let factory = || { Event { price: 0.0 }};

// Define a closure for processing events. A thread, controlled by the disruptor, will run this
// processor closure each time an event is published.
let processor = |e: &Event, sequence: Sequence, end_of_batch: bool| {
    // Process the Event `e` published at `sequence`.
    // If `end_of_batch` is false, you can batch up events until it's invoked with
    // `end_of_batch` being true.
};

// Create a Disruptor with a ring buffer of size 8 and use the `BusySpin` wait strategy.
let mut producer = build_single_producer(8, factory, BusySpin)
    .handle_events_with(processor)
    .build();

// *** Phase PUBLISH ***

// Publish into the Disruptor.
for i in 0..10 {
    producer.publish(|e| {
        e.price = i as f64;
    });
}
// *** Phase SHUTDOWN ***

// The Producer instance goes out of scope and the Disruptor, the processor (consumer) and
// the Producer are dropped.

Re-exports

• pub use crate::wait_strategies::BusySpin;
• pub use crate::wait_strategies::BusySpinWithSpinLoopHint;
• pub use crate::consumer::SingleConsumerBarrier;
• pub use crate::consumer::MultiConsumerBarrier;

Modules

• wait_strategies
  Module with different strategies for waiting for an event to be published.

Structs

• MultiProducer
  Producer for publishing to the Disruptor from multiple threads.
• RingBufferFull
  Error indicating that the ring buffer is full.
• SingleProducer
  Producer for publishing to the Disruptor from a single thread.

Traits

• ProcessorSettings
  The processor’s thread name and CPU affinity can be set via the builders that implement this trait.
• Producer
  Producer used for publishing into the Disruptor.

Functions

• build_multi_producer
  Build a multi producer Disruptor. Use this if you need to publish events from many threads.
• build_single_producer
  Build a single producer Disruptor. Use this if you only need to publish events from one thread.

Type Aliases

• Sequence
  The type for Sequence numbers in the Ring Buffer (i64).