feat: add parallel cache support

src/Cache/Cache.php

@@ -136,4 +136,18 @@ public static function fromJson(string $json): self
 
         return $cache;
     }
+
+    /**
+     * @internal
+     */
+    public function backfillHashes(self $oldCache): bool
+    {
+        if (!$this->getSignature()->equals($oldCache->getSignature())) {
+            return false;
+        }
+
+        $this->hashes = array_merge($oldCache->hashes, $this->hashes);
+
+        return true;
+    }
 }

src/Cache/FileHandler.php

@@ -25,6 +25,8 @@ final class FileHandler implements FileHandlerInterface
 {
     private string $file;
 
+    private int $fileMTime = 0;
+
     public function __construct(string $file)
     {
         $this->file = $file;
@@ -41,21 +43,80 @@ public function read(): ?CacheInterface
             return null;
         }
 
-        $content = file_get_contents($this->file);
-
-        try {
-            $cache = Cache::fromJson($content);
-        } catch (\InvalidArgumentException $exception) {
+        $handle = fopen($this->file, 'r');
+        if (false === $handle) {
             return null;
         }
 
+        $cache = $this->readFromHandle($handle);
+        $this->fileMTime = $this->getFileCurrentMTime();
+
+        fclose($handle);
+
         return $cache;
     }
 
     public function write(CacheInterface $cache): void
     {
-        $content = $cache->toJson();
+        $this->ensureFileIsWriteable();
+
+        $handle = fopen($this->file, 'r+');
+        if (false === $handle) {
+            return;
+        }
+
+        if (method_exists($cache, 'backfillHashes') && $this->fileMTime < $this->getFileCurrentMTime()) {
+            flock($handle, LOCK_EX);
+            $oldCache = $this->readFromHandle($handle);
+            rewind($handle);
+
+            if (null !== $oldCache) {
+                $cache->backfillHashes($oldCache);
+            }
+        }
+        ftruncate($handle, 0);
+        fwrite($handle, $cache->toJson());
+        fflush($handle);
+        fsync($handle);
+        $this->fileMTime = $this->getFileCurrentMTime();
+        fclose($handle);
+    }
+
+    private function getFileCurrentMTime(): int
+    {
+        clearstatcache(true, $this->file);
+
+        $mtime = filemtime($this->file);
+
+        if (false === $mtime) {
+            // cannot check mtime? OK, let's pretend file is old
+            $mtime = 0;
+        }
 
+        return $mtime;
+    }
+
+    /**
+     * @param resource $handle
+     */
+    private function readFromHandle($handle): ?CacheInterface
+    {
+        try {
+            $size = @filesize($this->file);
+            if (false === $size || 0 === $size) {
+                return null;
+            }
+
+            $content = fread($handle, $size);
+
+            return Cache::fromJson($content);
+        } catch (\InvalidArgumentException $exception) {
+            return null;
+        }
+    }
+
+    private function ensureFileIsWriteable(): void
+    {
         if (file_exists($this->file)) {
             if (is_dir($this->file)) {
                 throw new IOException(
@@ -95,18 +156,5 @@ public function write(CacheInterface $cache): void
             @touch($this->file);
             @chmod($this->file, 0666);
         }
-
-        $bytesWritten = @file_put_contents($this->file, $content);
-
-        if (false === $bytesWritten) {
-            $error = error_get_last();
-
-            throw new IOException(
-                sprintf('Failed to write file "%s", "%s".', $this->file, $error['message'] ?? 'no reason available'),
-                0,
-                null,
-                $this->file
-            );
-        }
     }
 }