lib-lock

lib-lock

Distributed locking abstraction with pluggable backends.

Overview

Provides a simple API for distributed mutex locks with two implementations:

• LocalLockManager: In-memory implementation for local development and testing
• RedisLockManager: Redis-based implementation for production (in lib-jedis-lock)

The correct implementation is automatically selected via Micronaut's conditional bean activation.

Installation

Add this dependency to your build.gradle:

dependencies {
    implementation 'io.seqera:lib-lock:1.1.0'

    // For Redis support in production:
    runtimeOnly 'io.seqera:lib-jedis-lock:1.0.0'
}

Usage

import io.seqera.lock.LockManager
import io.seqera.lock.Lock

@Singleton
class MyService {

    @Inject
    LockManager lockManager

    void processWithLock(String resourceId) {
        try (Lock lock = lockManager.acquire("my-resource:" + resourceId, Duration.ofMinutes(5))) {
            // Critical section - only one process can execute this
            processSharedResource()
        } catch (TimeoutException e) {
            // Lock not acquired within timeout
        }
    }

    void tryProcessWithLock(String resourceId) {
        Lock lock = lockManager.tryAcquire("my-resource:" + resourceId)
        if (lock) {
            try {
                processSharedResource()
            } finally {
                lock.release()
            }
        }
    }
}

API

LockManager

Method	Description
Lock tryAcquire(String lockKey)	Non-blocking acquire. Returns Lock if acquired, null otherwise
Lock acquire(String lockKey, Duration timeout)	Blocking acquire. Throws TimeoutException if not acquired within timeout

Lock

Method	Description
boolean release()	Release the lock. Returns true if released successfully
void close()	AutoCloseable - calls release()

Configuration

seqera:
  lock:
    my-lock:
      auto-expire-duration: 5m       # Lock TTL (default: 5m)
      acquire-retry-interval: 100ms  # Polling interval when waiting for lock (default: 100ms)
      watchdog-enabled: true         # Auto-renew TTL while held (default: true)

Property	Default	Description
auto-expire-duration	5m	Lock TTL. Safety net if the holder crashes.
acquire-retry-interval	100ms	Polling interval for blocking acquire().
watchdog-enabled	true	(since 1.1.0) When enabled, the lock TTL is automatically renewed at ttl/3 intervals while the holder is alive, preventing silent expiration for long-held locks.

Implementation Selection

Environment	Implementation	Activation
Local dev (no Redis)	LocalLockManager	@Requires(missingBeans = RedisActivator)
Production (Redis)	RedisLockManager	@Requires(bean = RedisActivator)

Testing

./gradlew :lib-lock:test