Getting Started¶

Requirements¶

Java 17 or later.
One of the supported storage backends:
- An Aerospike cluster reachable from application nodes, or
- An HBase cluster reachable from application nodes.

Add Dependency¶

<dependency>
  <groupId>com.phonepe</groupId>
  <artifactId>distributed-latch</artifactId>
  <version>${distributed-latch.version}</version>
</dependency>

Replace ${distributed-latch.version} with the latest version from Maven Central or GitHub Releases.

Build Locally¶

git clone https://github.com/PhonePe/DistributedLatch.git
cd DistributedLatch
mvn clean install

To run the tests:

mvn clean test

Minimal Example¶

CountDown Latch (Coordinator side)¶

// 1. Create a count-down latch with initial count = 3
IDistributedCountDownLatch latch = DistributedLatchFactory.createCountDownLatch(
    "order-service",                    // clientId
    LatchLevel.DC,                      // latch level
    "dc1",                              // farmId
    "batch-job-123",                    // latchId
    AerospikeLatchStorageContext.builder()
        .aerospikeClient(aerospikeClient)
        .namespace("latches")
        .setSuffix("distributed_latch")
        .storageType(StorageType.AEROSPIKE)
        .ttl(3600)                      // TTL in seconds
        .build(),
    3                                   // initial count
);

// 2. Wait for all workers to finish
latch.await();
// execution continues after count reaches 0

CountDown Latch (Worker side)¶

// 1. Get a reference to the existing latch (no init)
IDistributedCountDownLatch latch = DistributedLatchFactory.getCountDownLatch(
    "order-service",
    LatchLevel.DC,
    "dc1",
    "batch-job-123",
    AerospikeLatchStorageContext.builder()
        .aerospikeClient(aerospikeClient)
        .namespace("latches")
        .setSuffix("distributed_latch")
        .storageType(StorageType.AEROSPIKE)
        .ttl(3600)
        .build()
);

// 2. Signal completion
latch.countDown();

Tip

The coordinator creates the latch with an initial count using createCountDownLatch. Workers obtain a reference to the same latch using getCountDownLatch (without re-initializing the count) and call countDown() when their work is done.

What's Next¶

Usage — factory methods, CountUpDown latch, await with timeout, error handling.
Latch Semantics — API reference, latch levels, watcher behavior.
Storage Backends — Aerospike and HBase details.