Locket

Warnings

• gotcha Locket provides non-reentrant locks. This means a thread cannot acquire a lock it already holds without blocking or raising a `LockError` if a timeout is specified. If you need reentrant behavior, use `threading.RLock` or ensure your code structure avoids re-acquiring the same lock.
  Fix: Avoid recursive lock acquisition, or use `threading.RLock` if reentrant locking is strictly required within a single process.
• breaking The behavior of Locket's file-based locks after a process `fork` is undefined. This means using `locket` directly with `multiprocessing` modules that rely on forking might lead to unpredictable results or deadlocks.
  Fix: Avoid inheriting locks across `fork` calls. Acquire locks *after* forking in each child process if separate locking is needed, or use `multiprocessing.Lock` for IPC within the `multiprocessing` module.
• gotcha Calling `release()` on an already unlocked lock will raise a `locket.LockError`. This typically indicates a logic error where `release()` is called more times than `acquire()` or when a lock is not held by the current process/thread.
  Fix: Always pair `acquire()` with `release()`, ideally using a `try...finally` block or, preferably, the `with` statement (context manager) provided by `locket.lock_file()` to ensure automatic and safe release.
• deprecated The last release of Locket (version 1.0.0) was in April 2022. While functional, the library has not received recent updates, which might imply a maintenance-only status. Users should be aware that it may not receive updates for newer Python versions or address new edge cases/bugs promptly.
  Fix: Evaluate for your specific use case. For critical applications requiring active maintenance or features, consider alternatives like `fasteners` or `oslo.concurrency` (though `oslo.concurrency` might be more heavyweight for simple needs).

Install

• pip install locket Install latest version

Imports

• locket

  import locket

  The primary interface is through the `locket` module directly, often using `locket.lock_file()`.
• LockError

  from locket import LockError

  The specific exception raised by locket operations.

Quickstart

This quickstart demonstrates how to use `locket.lock_file()` with a context manager for safe and automatic lock acquisition and release. It also shows the explicit `acquire()` and `release()` pattern, which requires careful handling to prevent deadlocks or `LockError` if `release()` is called on an unlocked lock. The `timeout` parameter prevents indefinite blocking.

import locket
import os
import time

# Define a lock file path, using an environment variable for flexibility
lock_file_path = os.environ.get('LOCKET_EXAMPLE_PATH', './my_app.lock')

print(f"Attempting to acquire lock on {lock_file_path}...")
try:
    # Acquire the lock using a context manager, with a 5-second timeout
    # If another process holds the lock, this will block for up to 5 seconds.
    # If the lock cannot be acquired, a LockError is raised.
    with locket.lock_file(lock_file_path, timeout=5):
        print(f"Lock acquired on {lock_file_path}. Performing critical action...")
        # Simulate work within the critical section
        time.sleep(2)
        print("Critical action complete. Lock will be released automatically.")
except locket.LockError:
    print(f"Could not acquire lock on {lock_file_path} within the timeout. Another process might hold it.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

print("\nDemonstrating explicit acquire/release (less recommended)...")
lock = None
try:
    # Acquire the lock explicitly
    lock = locket.lock_file(lock_file_path, timeout=1)
    lock.acquire()
    print(f"Lock acquired on {lock_file_path} (manual). Performing critical action...")
    time.sleep(1)
    print("Critical action complete (manual).")
finally:
    # Always ensure the lock is released, even if errors occur
    if lock:
        try:
            lock.release()
            print("Lock released (manual).")
        except locket.LockError:
            print("Warning: Attempted to release an already unlocked lock. This should not happen if `release()` is paired with `acquire()`.")