docs(lock): document atomic locks

Signed-off-by: memleakd <[email protected]>

Author: memleakd

user_guide_src/source/changelogs/v4.8.0.rst

@@ -222,6 +222,7 @@ Libraries
 
 - **Context**: This new feature allows you to easily set and retrieve normal or hidden contextual data for the current request. See :ref:`Context <context>` for details.
 - **Images:**: Added support for the AVIF file format.
+- **Locks:** Added :doc:`Atomic Locks </libraries/locks>` for owner-aware, cross-process mutual exclusion backed by supported cache handlers.
 - **Logging:** Log handlers now receive the full context array as a third argument to ``handle()``. When ``$logGlobalContext`` is enabled, the CI global context is available under the ``HandlerInterface::GLOBAL_CONTEXT_KEY`` key. Built-in handlers append it to the log output; custom handlers can use it for structured logging.
 - **Logging:** Added :ref:`per-call context logging <logging-per-call-context>` with three new ``Config\Logger`` options (``$logContext``, ``$logContextTrace``, ``$logContextUsedKeys``). Per PSR-3, a ``Throwable`` in the ``exception`` context key is automatically normalized to a meaningful array. All options default to ``false``.
 

user_guide_src/source/libraries/index.rst

@@ -15,6 +15,7 @@ Library Reference
     file_collections
     honeypot
     images
+    locks
     pagination
     publisher
     security

user_guide_src/source/libraries/locks.rst

@@ -0,0 +1,162 @@
+############
+Atomic Locks
+############
+
+.. versionadded:: 4.8.0
+
+.. contents::
+    :local:
+    :depth: 2
+
+Atomic locks provide a simple way to prevent the same task from running
+concurrently across requests, CLI commands, or workers that share the same
+cache storage.
+
+Locks are advisory. Your code must acquire the lock before entering the
+critical section, and release it when the work is finished.
+
+*************
+Configuration
+*************
+
+The Locks library uses the Cache service. The cache handler must support atomic
+lock operations. The built-in **File**, **Redis**, and **Predis** cache handlers
+support locks.
+
+.. note:: Locks are most useful when all competing processes share the same cache
+    storage. The File handler is suitable for a single server. For multiple
+    application servers, use a shared handler such as Redis.
+
+*************
+Example Usage
+*************
+
+You can create a lock through the ``locks`` service. The second argument is the
+lock TTL, in seconds. The TTL prevents abandoned locks from being held forever
+if a process exits unexpectedly.
+
+.. literalinclude:: locks/001.php
+
+.. warning:: If the work takes longer than the lock TTL, another process may
+    acquire the same lock while the first process is still running. For
+    long-running work, choose a TTL that comfortably covers the operation, call
+    ``refresh()`` while the lock is held, or check ``isAcquired()`` before
+    performing irreversible side effects.
+
+Running a Callback
+==================
+
+The ``run()`` method acquires the lock, runs the callback, and releases the lock
+in a ``finally`` block.
+
+.. literalinclude:: locks/002.php
+
+If the lock cannot be acquired, ``run()`` returns ``null`` and the callback is
+not called.
+
+Blocking
+========
+
+The ``block()`` method waits up to the given number of seconds for the lock to
+become available:
+
+.. literalinclude:: locks/003.php
+
+Restoring a Lock by Owner
+=========================
+
+Each acquired lock has an owner token. You may pass this token to another
+process and restore the lock there, for example to release a lock from a queued
+worker that continues work started by the current request.
+
+.. literalinclude:: locks/004.php
+
+************************
+Locks and Cache Handlers
+************************
+
+The default File cache handler supports locks, so locks work without additional
+configuration in a standard application.
+
+If the configured cache handler does not support locks, creating a lock throws a
+``CodeIgniter\Lock\Exceptions\LockException``.
+
+Custom cache handlers can support locks by implementing
+``CodeIgniter\Lock\LockStoreInterface``. This keeps lock support opt-in and does
+not require all cache handlers to implement lock operations.
+
+***************
+Class Reference
+***************
+
+.. php:namespace:: CodeIgniter\Lock
+
+.. php:class:: LockManager
+
+    .. php:method:: create(string $name[, int $ttl = 300[, ?string $owner = null]])
+
+        :param string $name: The logical lock name.
+        :param int $ttl: Number of seconds before the lock expires.
+        :param string|null $owner: Optional owner token.
+        :returns: A lock instance.
+        :rtype: LockInterface
+
+        Creates a lock for the given logical name.
+
+    .. php:method:: restore(string $name, string $owner[, int $ttl = 300])
+
+        :param string $name: The logical lock name.
+        :param string $owner: The owner token.
+        :param int $ttl: Number of seconds before the lock expires.
+        :returns: A lock instance.
+        :rtype: LockInterface
+
+        Restores a lock instance for an existing owner token.
+
+.. php:interface:: LockInterface
+
+    .. php:method:: acquire()
+
+        :returns: ``true`` if the lock was acquired, ``false`` otherwise.
+        :rtype: bool
+
+    .. php:method:: block(int $seconds)
+
+        :param int $seconds: Maximum number of seconds to wait.
+        :returns: ``true`` if the lock was acquired, ``false`` otherwise.
+        :rtype: bool
+
+    .. php:method:: run(Closure $callback[, int $waitSeconds = 0])
+
+        :param Closure $callback: The callback to run while the lock is held.
+        :param int $waitSeconds: Maximum number of seconds to wait.
+        :returns: The callback result, or ``null`` if the lock was not acquired.
+        :rtype: mixed
+
+    .. php:method:: release()
+
+        :returns: ``true`` if the lock was released by its owner.
+        :rtype: bool
+
+    .. php:method:: forceRelease()
+
+        :returns: ``true`` if the lock was force released.
+        :rtype: bool
+
+        Releases the lock without checking the owner token.
+
+    .. php:method:: refresh([?int $ttl = null])
+
+        :param int|null $ttl: Number of seconds before the lock expires.
+        :returns: ``true`` if the owned lock was refreshed.
+        :rtype: bool
+
+    .. php:method:: isAcquired()
+
+        :returns: ``true`` if this lock instance still owns the lock.
+        :rtype: bool
+
+    .. php:method:: owner()
+
+        :returns: The owner token.
+        :rtype: string

user_guide_src/source/libraries/locks/001.php

@@ -0,0 +1,13 @@
+<?php
+
+$lock = service('locks')->create('reports.daily-export', 300);
+
+if (! $lock->acquire()) {
+    return;
+}
+
+try {
+    // Run the work that must not overlap.
+} finally {
+    $lock->release();
+}

user_guide_src/source/libraries/locks/002.php

@@ -0,0 +1,5 @@
+<?php
+
+$result = service('locks')
+    ->create('reports.daily-export', 300)
+    ->run(static fn () => build_daily_report());

user_guide_src/source/libraries/locks/003.php

@@ -0,0 +1,11 @@
+<?php
+
+$lock = service('locks')->create('imports.customer-feed', 300);
+
+if ($lock->block(10)) {
+    try {
+        import_customer_feed();
+    } finally {
+        $lock->release();
+    }
+}

user_guide_src/source/libraries/locks/004.php

@@ -0,0 +1,11 @@
+<?php
+
+$lock = service('locks')->create('exports.monthly', 300);
+
+if ($lock->acquire()) {
+    queue_export_job($lock->owner());
+}
+
+// Later, in another process:
+$restored = service('locks')->restore('exports.monthly', $owner);
+$restored->release();