Redlock Python Client

Common errors

• redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused.

  cause The Redis server is not running or is not accessible at the specified host and port.
  fix Ensure your Redis server is running and accessible from the machine running your Python application. Verify host and port configurations.

• TypeError: lock() missing 1 required positional argument: 'ttl'

  cause You called the `lock()` method without providing the `ttl` (Time-To-Live) argument, which specifies how long the lock should be valid in milliseconds.
  fix Add the `ttl` argument, specifying the lock duration in milliseconds. E.g., `dlm.lock(resource_name, 5000)`.

• Acquired lock for resource: my_critical_resource ... then another process also acquires it shortly after.

  cause This typically happens if you are using only one Redis instance, or if your `lock_ttl` is too short for the operation, allowing the lock to expire and be re-acquired by another client. Clock drift across servers can also contribute.
  fix For true distributed locking, configure Redlock with multiple Redis master instances. Increase `lock_ttl` to ensure your critical section completes before the lock expires. Regularly check server clock synchronization.

Warnings

• gotcha The `ttl` (Time-To-Live) parameter for `lock()` is specified in milliseconds, not seconds. Forgetting this common Redis API convention can lead to locks expiring much faster or slower than intended.
  Fix: Always provide the `ttl` value in milliseconds. E.g., for a 5-second lock, use `5000`.
• gotcha To ensure true distributed locking and fault tolerance as per the Redlock algorithm, you must configure `Redlock` with multiple independent Redis master instances (N/2 + 1 quorum). Using a single Redis instance defeats the purpose of distributed locking and makes your system susceptible to a single point of failure.
  Fix: Provide `Redlock` with a list of at least 3 Redis master instances in `redis_masters`. Ensure these instances are physically distinct and independent.
• gotcha The Redlock algorithm, and thus this library, does not guarantee that a lock holder will finish its critical section before the lock expires. It's crucial to ensure your critical operations complete well within the `lock_ttl` or implement a mechanism to periodically extend the lock if necessary (though Redlock doesn't natively support easy extensions without re-acquiring).
  Fix: Estimate the maximum time your critical section will take and set `lock_ttl` accordingly, with a safety margin. If operations can exceed this, consider breaking them down or finding alternative coordination mechanisms.

Install

• pip install redlock Install stable version

Imports

• Redlock

  from redlock import Redlock

Quickstart

This quickstart demonstrates how to initialize Redlock with a single Redis instance (for demonstration) and acquire/release a distributed lock. In a real-world scenario, you should configure multiple independent Redis master instances to leverage the Redlock algorithm's fault tolerance. The `lock_ttl` is specified in milliseconds.

import redis
from redlock import Redlock
import os

# Configure Redis instances. For production, use multiple instances
# and ensure they are properly configured for high availability.
# Here, we default to localhost for a runnable example.
redis_host = os.environ.get('REDIS_HOST', 'localhost')
redis_port = int(os.environ.get('REDIS_PORT', 6379))

redis_masters = [
    {"host": redis_host, "port": redis_port, "db": 0}
    # For true distributed locking, add more Redis instances:
    # {"host": "192.168.1.30", "port": 6379, "db": 0},
    # {"host": "192.168.1.31", "port": 6379, "db": 0}
]

# Initialize Redlock with Redis instances
dlm = Redlock(redis_masters=redis_masters)

resource_name = "my_critical_resource"
lock_ttl = 5000  # Lock validity time in milliseconds (5 seconds)

print(f"Attempting to acquire lock for resource: {resource_name}")
lock_info = dlm.lock(resource_name, lock_ttl)

if lock_info:
    print(f"Successfully acquired lock: {lock_info}")
    try:
        # --- Critical section begins ---
        print("Performing critical operation...")
        # Simulate work
        import time
        time.sleep(2) # Keep operation less than lock_ttl
        # --- Critical section ends ---
    finally:
        print("Releasing lock...")
        dlm.unlock(lock_info)
        print("Lock released.")
else:
    print(f"Failed to acquire lock for resource: {resource_name}. It might be held by another process.")