A simple, ETS-based locking mechanism for local synchronization.

This module provides a lightweight locking system suitable for single-node use cases, such as implementing transactions in local cache adapters. It uses ETS for lock storage with atomic operations for acquiring and releasing locks.

Features

• Atomic lock acquisition - Uses insert_new for atomic operations.
• Deadlock prevention - Locks are acquired in sorted key order.
• Dual stale lock cleanup - Automatic cleanup via two mechanisms:
  • On-demand: During lock acquisition attempts
  • Periodic: Background cleanup at configurable intervals
• Fine-grained locking - Lock specific keys for better concurrency.
• Retry with jitter - Configurable retries with jitter to prevent thundering herd.
• Scalable cleanup - Batch-based cleanup using ETS continuation to handle large numbers of locks efficiently.

Usage

The module supports two modes of operation:

Named mode (recommended)

When you provide a :name option, both the GenServer and the ETS table are registered with that name, allowing direct access without calling get_table/1:

# Start with a name
children = [
  {Nebulex.Locks, name: MyApp.Locks}
]

Supervisor.start_link(children, strategy: :one_for_one)

# Use the name directly for acquire/release
case Nebulex.Locks.acquire(MyApp.Locks, [:key1, :key2], retries: 5) do
  :ok ->
    try do
      # Critical section
    after
      Nebulex.Locks.release(MyApp.Locks, [:key1, :key2])
    end

  {:error, :timeout} ->
    # Failed to acquire locks
end

Anonymous mode

When :name is not provided or is nil, the GenServer starts unnamed and you must use get_table/1 to obtain the table reference:

# Start without a name
{:ok, pid} = Nebulex.Locks.start_link([])

# Get the table reference
table = Nebulex.Locks.get_table(pid)

# Use the table reference
Nebulex.Locks.acquire(table, [:key1], retries: 3)

Start Options

• :name (atom/0) - Optional name to register both the GenServer and ETS table. When provided, allows direct access to the locks table using the name. When nil or not provided, the GenServer starts unnamed.

• :cleanup_interval (timeout/0) - The interval in milliseconds for the periodic cleanup of stale locks. Stale locks are detected by checking if the owner process is alive and if the lock has exceeded the :lock_timeout. The default value is 300000.

• :cleanup_batch_size (pos_integer/0) - The number of locks to process per batch during periodic cleanup. Larger values reduce iteration overhead but increase memory usage during cleanup. Smaller values reduce memory spikes but increase the number of ETS select operations. The default value is 100.

• :init_callback - An optional callback MFA (module, function, arguments) to be invoked after the locks table is created during GenServer initialization.

  The callback is invoked as apply(module, function, [table | args]), where table is the newly created ETS locks table prepended to the provided argument list. The return value is ignored.

  This is useful for integration scenarios where the locks table reference needs to be stored in external state, such as an adapter's metadata table.

  Example

  # Store the locks table in the adapter's metadata
  {Nebulex.Locks, [
    name: MyApp.Locks,
    init_callback: {MyApp, :init, [:some_arg]}
  ]}
  
  # Will call: MyApp.init(table, :some_arg)

Lock Entry Structure

Locks are stored in ETS as records:

{:lock, lock_key, owner_pid, timestamp, timeout}

Where:

• lock_key - The key being locked (sorted to prevent deadlocks).
• owner_pid - The PID of the process holding the lock.
• timestamp - When the lock was acquired (for stale detection).
• timeout - Maximum time the lock can be held before being stale.

Stale Lock Detection and Cleanup

This module implements a defense-in-depth approach to stale lock cleanup, combining two complementary mechanisms:

On-Demand Cleanup

When a process attempts to acquire a lock and finds an existing lock, it checks if the lock is stale before failing the acquisition:

• Dead process detection: Uses Process.alive?/1 to detect if the lock owner has crashed.
• Timeout detection: Compares the lock's timestamp with its configured lock_timeout to detect locks held longer than allowed.

If a stale lock is detected, it is immediately removed and the acquiring process can obtain the lock. This ensures low latency for lock acquisition on frequently accessed keys.

Periodic Cleanup

A background cleanup process runs at the configured :cleanup_interval (default: 5 minutes) to proactively remove stale locks. Locks are processed in batches (default: 100 locks per batch) using ETS continuation to avoid loading the entire table into memory at once.

This periodic cleanup ensures that stale locks from infrequently accessed keys don't accumulate in memory, preventing memory leaks.

Why Two Mechanisms?

• On-demand cleanup: Provides immediate cleanup for actively used keys with minimal latency.
• Periodic cleanup: Prevents memory leaks by cleaning up locks for keys that are no longer accessed.
• Together: Ensures robust cleanup under all usage patterns.

Performance Characteristics

Lock Acquisition and Release

• No GenServer bottleneck: Lock operations hit ETS directly via atomic insert_new operations. Only get_table/1 requires a GenServer call.
• High concurrency: Public ETS table with :write_concurrency and :read_concurrency enabled.

Lock Fairness

• No FIFO guarantee: When multiple processes compete for the same lock, the winner is determined by ETS race conditions and scheduler timing.
• Practical fairness: With retry intervals and jitter, starvation is virtually impossible in practice.
• Trade-off: Prioritizes performance over strict ordering. For use cases requiring FIFO fairness, consider sleeplocks or a queue-based approach.