Add variant of mutex based on flock

src/FileMutex.php

@@ -8,6 +8,13 @@
 use Amp\Sync\SyncException;
 use function Amp\delay;
 
+/**
+ * Async mutex based on files.
+ *
+ * A crash of the program will NOT release the lock, manual user action will be required to remove the lockfile.
+ *
+ * For a mutex that will automatically release the lock in case of a crash, see LockingFileMutex.
+ */
 final class FileMutex implements Mutex
 {
     private const LATENCY_TIMEOUT = 0.01;

src/KeyedFileMutex.php

@@ -8,6 +8,13 @@
 use Amp\Sync\SyncException;
 use function Amp\delay;
 
+/**
+ * Async keyed mutex based on files.
+ *
+ * A crash of the program will NOT release the lock, manual user action will be required to remove the lockfile.
+ *
+ * For a mutex that will automatically release the lock in case of a crash, see KeyedLockingFileMutex.
+ */
 final class KeyedFileMutex implements KeyedMutex
 {
     private const LATENCY_TIMEOUT = 0.01;

src/KeyedLockingFileMutex.php

@@ -0,0 +1,62 @@
+<?php declare(strict_types=1);
+
+namespace Amp\File;
+
+use Amp\Cancellation;
+use Amp\Sync\KeyedMutex;
+use Amp\Sync\Lock;
+use Amp\Sync\SyncException;
+use function Amp\delay;
+
+/**
+ * Async keyed mutex based on flock.
+ *
+ * A crash of the program will automatically release the lock, but the lockfiles will never be removed from the filesystem (even in case of successful release).
+ *
+ * For a mutex that removes the lockfiles but does not release the lock in case of a crash (requiring manual user action to clean up), see KeyedFileMutex.
+ */
+
+final class KeyedLockingFileMutex implements KeyedMutex
+{
+    private const LATENCY_TIMEOUT = 0.01;
+    private const DELAY_LIMIT = 1;
+
+    private readonly Filesystem $filesystem;
+
+    private readonly string $directory;
+
+    /**
+     * @param string $directory Directory in which to store key files.
+     */
+    public function __construct(string $directory, ?Filesystem $filesystem = null)
+    {
+        $this->filesystem = $filesystem ?? filesystem();
+        $this->directory = \rtrim($directory, "/\\");
+    }
+
+    public function acquire(string $key, ?Cancellation $cancellation = null): Lock
+    {
+        if (!$this->filesystem->isDirectory($this->directory)) {
+            throw new SyncException(\sprintf('Directory "%s" does not exist or is not a directory', $this->directory));
+        }
+
+        $filename = $this->getFilename($key);
+
+        $f = \fopen($filename, 'c');
+
+        // Try to create the lock file. If the file already exists, someone else
+        // has the lock, so set an asynchronous timer and try again.
+        for ($attempt = 0; true; ++$attempt) {
+            if (\flock($f, LOCK_EX|LOCK_NB)) {
+                $lock = new Lock(fn () => \flock($f, LOCK_UN));
+                return $lock;
+            }
+            delay(\min(self::DELAY_LIMIT, self::LATENCY_TIMEOUT * (2 ** $attempt)), cancellation: $cancellation);
+        }
+    }
+
+    private function getFilename(string $key): string
+    {
+        return $this->directory . '/' . \hash('sha256', $key) . '.lock';
+    }
+}

src/LockingFileMutex.php

@@ -0,0 +1,53 @@
+<?php declare(strict_types=1);
+
+namespace Amp\File;
+
+use Amp\Cancellation;
+use Amp\Sync\Lock;
+use Amp\Sync\Mutex;
+use Amp\Sync\SyncException;
+use function Amp\delay;
+
+/**
+ * Async mutex based on flock.
+ *
+ * A crash of the program will automatically release the lock, but the lockfiles will never be removed from the filesystem (even in case of successful release).
+ *
+ * For a mutex that removes the lockfiles but does not release the lock in case of a crash (requiring manual user action to clean up), see FileMutex.
+ */
+final class LockingFileMutex implements Mutex
+{
+    private const LATENCY_TIMEOUT = 0.01;
+    private const DELAY_LIMIT = 1;
+
+    private readonly Filesystem $filesystem;
+
+    private readonly string $directory;
+
+    /**
+     * @param string $fileName Name of temporary file to use as a mutex.
+     */
+    public function __construct(private readonly string $fileName, ?Filesystem $filesystem = null)
+    {
+        $this->filesystem = $filesystem ?? filesystem();
+        $this->directory = \dirname($this->fileName);
+    }
+
+    public function acquire(?Cancellation $cancellation = null): Lock
+    {
+        if (!$this->filesystem->isDirectory($this->directory)) {
+            throw new SyncException(\sprintf('Directory of "%s" does not exist or is not a directory', $this->fileName));
+        }
+        $f = \fopen($this->fileName, 'c');
+
+        // Try to create the lock file. If the file already exists, someone else
+        // has the lock, so set an asynchronous timer and try again.
+        for ($attempt = 0; true; ++$attempt) {
+            if (\flock($f, LOCK_EX|LOCK_NB)) {
+                $lock = new Lock(fn () => \flock($f, LOCK_UN));
+                return $lock;
+            }
+            delay(\min(self::DELAY_LIMIT, self::LATENCY_TIMEOUT * (2 ** $attempt)), cancellation: $cancellation);
+        }
+    }
+}

test/KeyedLockingFileMutexTest.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types=1);
+
+namespace Amp\File\Test;
+
+use Amp\File\KeyedLockingFileMutex;
+use Amp\Sync\AbstractKeyedMutexTest;
+use Amp\Sync\KeyedMutex;
+
+final class KeyedLockingFileMutexTest extends AbstractKeyedMutexTest
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+        Fixture::init();
+    }
+
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+        Fixture::clear();
+    }
+
+    public function createMutex(): KeyedMutex
+    {
+        return new KeyedLockingFileMutex(Fixture::path());
+    }
+}

test/LockingFileMutexTest.php

@@ -0,0 +1,15 @@
+<?php declare(strict_types=1);
+
+namespace Amp\File\Test;
+
+use Amp\File\LockingFileMutex;
+use Amp\Sync\AbstractMutexTest;
+use Amp\Sync\Mutex;
+
+final class LockingFileMutexTest extends AbstractMutexTest
+{
+    public function createMutex(): Mutex
+    {
+        return new LockingFileMutex(\tempnam(\sys_get_temp_dir(), 'mutex-') . '.lock');
+    }
+}