Workers is a high-performance Java library for distributing events across multiple worker threads. It is designed around ring buffers, lock-free sequences, and consistent hashing to achieve predictable throughput and low latency.

• ⚡ High performance: lock-free queues with cache-line padding to minimize contention.

• 🎯 Consistent hashing: route events to the correct worker based on a key.

• 🧩 Pluggable factories & handlers: customize how events are created and processed.

• 🛡️ Fault isolation: if one worker fails, others continue to process events.

• 🧵 Thread-aware design: workers run on dedicated threads with controlled lifecycle.

• WorkerService – orchestrates a pool of workers, distributes events based on keys.

• WorkerNode – logical partition that maps to a worker (with replicas for load balancing).

• Worker – lightweight event processor that consumes from a ring buffer.

• EventHandler – user-defined callback for handling events.

• EventFactory – supplier for creating reusable event objects.

private static final EventHandler<Event> EVENT_HANDLER = new EventHandler<>() {
    @Override
    public void onEvent(String name, Event event, long sequence) {
        System.out.println("Worker name: " + name + ", sequence: " + sequence);
    }

    @Override
    public void onError(String name, Event event, long sequence, Throwable ex) {

    }

    @Override
    public void onStart(String name) {

    }

    @Override
    public void onShutdown(String name) {

    }
};
private static final EventFactory<Event> EVENT_FACTORY = Event::new;
private static final EventTranslatorOneArg<Event, Integer>  EVENT_TRANSLATOR = Event::setId;
private static final WorkerService<Event> WORKER_SERVICE = new WorkerService<>("test", EVENT_HANDLER, EVENT_FACTORY, DefaultHashCodeProvider.INSTANCE, WorkerServiceConfig.INSTANCE);

void main(String[] args) {
    WORKER_SERVICE.start();
    for (int i = 0; i < 10_000_000; i++) {
        WORKER_SERVICE.publishEvent(i, EVENT_TRANSLATOR, i);
    }
    WORKER_SERVICE.shutdown();
}

public static class Event {
    private int id;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }
}

WorkerServiceTerminatedException – thrown when a worker service is shut down or no longer available.

Optimized for millions of events per second on modern CPUs.

Scales with number of workers (power of 2 recommended for distribution).