feat: implemented generic LockedResource object

README.md

@@ -43,6 +43,25 @@ $criticalOutput = CriticalSection::withLocks([$lockA, $lockB])(fn () => 'This wa
 var_dump($criticalOutput);
 ```
 
+## Do you need to accept only locked resources?
+
+Use [`LockedResource`s](./src/LockedResource.php) if you need to be sure that you are not processing resource outside it's critical section.
+
+```php
+namespace PetrKnap\CriticalSection;
+
+use Symfony\Component\Lock\NoLock;
+
+/** @param LockedResource<LockedResource\Resource> $lockedResource */
+function f(LockedResource $lockedResource) {
+    echo $lockedResource->value;
+}
+
+$lock = new NoLock();
+$resource = LockableResource::create(new LockedResource\Resource('data'), $lock);
+CriticalSection::withLock($lock)(fn () => f($resource));
+```
+
 ## Does your critical section work with database?
 
 Use [`doctrine/dbal`](https://packagist.org/packages/doctrine/dbal) and its `transactional` method.

composer.json

@@ -31,11 +31,11 @@
   "name": "petrknap/critical-section",
   "require": {
     "php": ">=8.1",
+    "petrknap/shorts": "^2.1",
     "symfony/lock": "^6.0|^7.0"
   },
   "require-dev": {
     "nunomaduro/phpinsights": "^2.11",
-    "petrknap/shorts": "^2.1",
     "phpstan/phpstan": "^1.10",
     "phpunit/phpunit": "^9.6",
     "squizlabs/php_codesniffer": "^3.7"

src/Exception/CouldNotGetUnlockedResource.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\CriticalSection\Exception;
+
+use PetrKnap\Shorts\Exception\CouldNotProcessData;
+
+/**
+ * @template T of mixed
+ *
+ * @extends CouldNotProcessData<T>
+ */
+final class CouldNotGetUnlockedResource extends CouldNotProcessData implements LockedResourceException
+{
+}

src/Exception/LockableResourceException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\CriticalSection\Exception;
+
+use Throwable;
+
+interface LockableResourceException extends Throwable
+{
+}

src/Exception/LockedResourceException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\CriticalSection\Exception;
+
+interface LockedResourceException extends LockableResourceException
+{
+}

src/LockableResource.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\CriticalSection;
+
+use Symfony\Component\Lock\LockInterface;
+
+final class LockableResource
+{
+    /**
+     * @template T of mixed
+     *
+     * @param T $resource
+     *
+     * @return LockedResource<T>
+     */
+    public static function create(
+        mixed $resource,
+        LockInterface $lock1,
+        LockInterface ...$lockN,
+    ): LockedResource {
+        return new Symfony\Lock\LockedResource($resource, $lock1, ...$lockN);
+    }
+}

src/LockedResource.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\CriticalSection;
+
+/**
+ * @template T of mixed
+ *
+ * @mixin T
+ */
+abstract class LockedResource
+{
+    /**
+     * @param T $resource
+     */
+    public function __construct(
+        private readonly mixed $resource,
+    ) {
+    }
+
+    /**
+     * @param array<mixed> $arguments
+     */
+    public function __call(string $name, array $arguments): mixed
+    {
+        return $this->get()->$name(...$arguments);
+    }
+
+    public function __set(string $name, mixed $value): void
+    {
+        $this->get()->$name = $value;
+    }
+
+    public function __get(string $name): mixed
+    {
+        return $this->get()->$name;
+    }
+
+    /**
+     * @return T
+     *
+     * @throws Exception\CouldNotGetUnlockedResource<T>
+     */
+    public function get(): mixed
+    {
+        if (!$this->isLocked()) {
+            throw new Exception\CouldNotGetUnlockedResource(
+                __METHOD__,
+                $this->resource,
+            );
+        }
+        return $this->resource;
+    }
+
+    abstract protected function isLocked(): bool;
+}

src/Symfony/Lock/LockedResource.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\CriticalSection\Symfony\Lock;
+
+use PetrKnap\CriticalSection\LockedResource as Base;
+use Symfony\Component\Lock\LockInterface;
+
+/**
+ * @template T of mixed
+ *
+ * @extends Base<T>
+ */
+final class LockedResource extends Base
+{
+    /**
+     * @var array<LockInterface>
+     */
+    private readonly array $locks;
+
+    /**
+     * @param T $resource
+     */
+    public function __construct(
+        mixed $resource,
+        LockInterface $lock1,
+        LockInterface ...$lockN,
+    ) {
+        parent::__construct($resource);
+        $this->locks = [$lock1, ...$lockN];
+    }
+
+    protected function isLocked(): bool
+    {
+        foreach ($this->locks as $lock) {
+            if (!$lock->isAcquired()) {
+                return false;
+            }
+        }
+        return true;
+    }
+}

tests/LockedResource/Resource.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\CriticalSection\LockedResource;
+
+final class Resource
+{
+    public function __construct(
+        public string $value,
+    ) {
+    }
+
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+}

tests/LockedResourceTestCase.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\CriticalSection;
+
+use PHPUnit\Framework\TestCase;
+use stdClass;
+
+abstract class LockedResourceTestCase extends TestCase
+{
+    public function testCouldNotGetUnlockedResource(): void
+    {
+        self::expectException(Exception\CouldNotGetUnlockedResource::class);
+
+        $this->getUnlockedResource(null)->get();
+    }
+
+    public function testCouldGetLockedResource(): void
+    {
+        $instance = new stdClass();
+
+        self::assertSame(
+            $instance,
+            $this->getLockedResource($instance)->get(),
+        );
+    }
+
+    public function testIsMixin(): void
+    {
+        $string = 'string';
+        /** @var LockedResource<LockedResource\Resource> $locked */
+        $locked = $this->getLockedResource(new LockedResource\Resource(''));
+
+        $locked->value = $string;
+        self::assertSame($string, $locked->value);
+        self::assertSame($string, $locked->getValue());
+    }
+
+    abstract protected function getUnlockedResource(mixed $resource): LockedResource;
+    abstract protected function getLockedResource(mixed $resource): LockedResource;
+}

tests/ReadmeTest.php

@@ -23,6 +23,7 @@ public static function getExpectedOutputsOfPhpExamples(): iterable
             'single-lock' => 'string(18) "This was critical."' . PHP_EOL,
             'double-lock' => 'string(18) "This was critical."' . PHP_EOL,
             'array-lock' => 'string(18) "This was critical."' . PHP_EOL,
+            'resources' => 'data',
             'transactional' => null,
         ];
     }

tests/Symfony/Lock/LockedResourceTest.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\CriticalSection\Symfony\Lock;
+
+use PetrKnap\CriticalSection\LockedResourceTestCase;
+use Symfony\Component\Lock\LockInterface;
+
+final class LockedResourceTest extends LockedResourceTestCase
+{
+    protected function getUnlockedResource(mixed $resource): LockedResource
+    {
+        $lock = $this->createMock(LockInterface::class);
+        $lock->expects(self::any())->method('isAcquired')->willReturn(false);
+        return new LockedResource($resource, $lock);
+    }
+
+    protected function getLockedResource(mixed $resource): LockedResource
+    {
+        $lock = $this->createMock(LockInterface::class);
+        $lock->expects(self::any())->method('isAcquired')->willReturn(true);
+        return new LockedResource($resource, $lock);
+    }
+}