fix(lock): return false when run cannot acquire

- return false from run() when lock acquisition fails
- update lock docs and tests for the new return value
- list LockManager in the core classes user guide

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

Author: memleakd

system/Lock/Lock.php

@@ -66,7 +66,7 @@ public function run(Closure $callback, int $waitSeconds = 0): mixed
         $acquired = $waitSeconds > 0 ? $this->block($waitSeconds) : $this->acquire();
 
         if (! $acquired) {
-            return null;
+            return false;
         }
 
         try {

tests/system/Lock/LockTest.php

@@ -157,13 +157,13 @@ public function testRunReleasesLockAfterCallback(): void
         $this->assertTrue($this->locks->create('notifications.send', 60)->acquire());
     }
 
-    public function testRunReturnsNullWhenLockCannotBeAcquired(): void
+    public function testRunReturnsFalseWhenLockCannotBeAcquired(): void
     {
         $first  = $this->locks->create('notifications.send', 60);
         $second = $this->locks->create('notifications.send', 60);
 
         $this->assertTrue($first->acquire());
-        $this->assertNull($second->run(static fn (): string => 'sent'));
+        $this->assertFalse($second->run(static fn (): string => 'sent'));
     }
 
     public function testLogicalNamesCanContainReservedCacheCharacters(): void

user_guide_src/source/extending/core_classes.rst

@@ -51,6 +51,7 @@ The following is a list of the core system classes that are invoked every time C
 *  ``CodeIgniter\HTTP\SiteURIFactory``
 *  ``CodeIgniter\HTTP\URI``
 *  ``CodeIgniter\HTTP\UserAgent`` (if launched over HTTP)
+*  ``CodeIgniter\Lock\LockManager``
 *  ``CodeIgniter\Log\Logger``
 *  ``CodeIgniter\Log\Handlers\BaseHandler``
 *  ``CodeIgniter\Log\Handlers\FileHandler``

user_guide_src/source/libraries/locks.rst

@@ -57,7 +57,7 @@ in a ``finally`` block.
 
 .. literalinclude:: locks/002.php
 
-If the lock cannot be acquired, ``run()`` returns ``null`` and the callback is
+If the lock cannot be acquired, ``run()`` returns ``false`` and the callback is
 not called.
 
 Blocking
@@ -143,7 +143,7 @@ Class Reference
 
         :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.
+        :returns: The callback result, or ``false`` if the lock was not acquired.
         :rtype: mixed
 
     .. php:method:: release()