Add AtomicOperationInterface.php

byjg · byjg · commit 54c397df8d5d · 2024-12-20T15:20:14.000-06:00
diff --git a/.github/workflows/phpunit.yml b/.github/workflows/phpunit.yml
@@ -24,8 +24,12 @@ jobs:
     services:
       memcached:
         image: memcached
+        ports:
+          - "11211:11211"
       redis:
         image: redis
+        ports:
+          - "6379:6379"
         options: >-
           --health-cmd "redis-cli ping"
           --health-interval 10s
diff --git a/README.md b/README.md
@@ -52,6 +52,17 @@ You can use a PSR-11 compatible to retrieve the cache keys.
 
 See more [here](docs/psr11-usage.md)
 
+## Beyond the PSR protocol
+
+The PSR protocol is a good way to standardize the cache access, 
+but sometimes you need to go beyond the protocol.
+
+Some cache engines have additional features that are not covered by the PSR protocol.
+
+Some examples are:
+- [Atomic Operations](docs/atomic-operations.md)
+- [Garbage Collection](docs/garbage-collection.md)
+
 ## Install
 
 Just type: 
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -0,0 +1,17 @@
+services:
+  memcached:
+    image: memcached
+    container_name: memcached
+    ports:
+      - "11211:11211"
+
+  redis:
+    image: redis
+    container_name: redis
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
diff --git a/docs/atomic-operations.md b/docs/atomic-operations.md
@@ -0,0 +1,56 @@
+# Atomic Operations
+
+Some cache engines allow you to do atomic operations such as incrementing or decrementing a value.
+
+Besides this is not cache operation, it is a common operation in cache engines.
+
+The advantage of using atomic operations is that you can avoid race conditions when multiple processes 
+are trying to update the same value.
+
+The atomic operations are:
+- Increment: Increment a value by a given number
+- Decrement: Decrement a value by a given number
+- Add: Add a value to a list in the cache
+
+The engines that support atomic operations have to implement the `AtomicOperationInterface`.
+
+Some engines that support atomic operations are:
+- RedisCachedEngine
+- MemcachedEngine
+- TmpfsCacheEngine
+- FileSystemCacheEngine
+
+## Increment
+
+The increment operation is used to increment a value by a given number.
+
+```php
+<?php
+/** @var \ByJG\Cache\AtomicOperationInterface $cache */
+$cache->increment('my-key', 1);
+```
+
+## Decrement
+
+The decrement operation is used to decrement a value by a given number.
+
+```php
+<?php
+/** @var \ByJG\Cache\AtomicOperationInterface $cache */
+$cache->decrement('my-key', 1);
+```
+
+## Add
+
+The add operation is used to add a value to a list in the cache.
+
+```php
+<?php
+/** @var \ByJG\Cache\AtomicOperationInterface $cache */
+$cache->add('my-key', 'value1');
+$cache->add('my-key', 'value2');
+$cache->add('my-key', 'value3');
+
+print_r($cache->get('my-key')); // ['value1', 'value2', 'value3']
+```
+
diff --git a/docs/garbage-collection.md b/docs/garbage-collection.md
@@ -0,0 +1,30 @@
+# Garbage Collection
+
+Some cache engines need to have a garbage collection process to remove the expired keys.
+
+In some engines like `Memcached` and `Redis` the garbage collection is done automatically by the engine itself.
+
+In other engines like `FileSystem` and `Array` there is no such process. The current implementation
+is based on the Best Effort. It means an expired key is removed only when you try to access it.
+
+If the cache engine has a low hit rate, it is recommended to run a garbage collection process
+to avoid the cache to grow indefinitely.
+
+The classes that implement the `GarbageCollectionInterface` have the method `collectGarbage()`.
+
+Some engines that support garbage collection are:
+- FileSystemCacheEngine
+- ArrayCacheEngine
+- TmpfsCacheEngine
+
+## Example
+
+```php
+<?php
+/** @var \ByJG\Cache\GarbageCollectionInterface $cache */
+$cache->collectGarbage();
+```
+
+Note: The garbage collection process is blocking. 
+It means the process will be slow if you have a lot of keys to remove.
+
diff --git a/src/AtomicOperationInterface.php b/src/AtomicOperationInterface.php
@@ -0,0 +1,14 @@
+<?php
+
+namespace ByJG\Cache;
+
+use DateInterval;
+
+interface AtomicOperationInterface
+{
+    public function increment(string $key, int $value = 1, DateInterval|int|null $ttl = null): int;
+
+    public function decrement(string $key, int $value = 1, DateInterval|int|null $ttl = null): int;
+
+    public function add(string $key, $value, DateInterval|int|null $ttl = null): array;
+}
diff --git a/src/Psr16/FileSystemCacheEngine.php b/src/Psr16/FileSystemCacheEngine.php
@@ -2,15 +2,17 @@
 
 namespace ByJG\Cache\Psr16;
 
+use ByJG\Cache\AtomicOperationInterface;
 use ByJG\Cache\GarbageCollectorInterface;
+use Closure;
 use DateInterval;
 use Exception;
 use Psr\Container\ContainerExceptionInterface;
 use Psr\Container\NotFoundExceptionInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 
-class FileSystemCacheEngine extends BaseCacheEngine implements GarbageCollectorInterface
+class FileSystemCacheEngine extends BaseCacheEngine implements GarbageCollectorInterface, AtomicOperationInterface
 {
 
     protected ?LoggerInterface $logger = null;
@@ -75,21 +77,10 @@ public function set(string $key, mixed $value, DateInterval|int|null $ttl = null
         $this->logger->info("[Filesystem cache] Set '$key' in FileSystem");
 
         try {
-            if (file_exists($fileKey)) {
-                unlink($fileKey);
-            }
-            if (file_exists("$fileKey.ttl")) {
-                unlink("$fileKey.ttl");
-            }
-
-            if (is_null($value)) {
-                return false;
-            }
-
             if (is_string($value) && (strlen($value) === 0)) {
                 touch($fileKey);
             } else {
-                $this->putContents($fileKey, $value, $this->addToNow($ttl));
+                return $this->putContents($fileKey, $value, $this->addToNow($ttl));
             }
         } catch (Exception $ex) {
             $this->logger->warning("[Filesystem cache] I could not write to cache on file '" . basename($key) . "'. Switching to nocache=true mode.");
@@ -208,12 +199,34 @@ protected function getContents(string $fileKey, mixed $default = null): mixed
         return $content;
     }
 
-    protected function putContents(string $fileKey, mixed $value, ?string $ttl): void
+    protected function putContents(string $fileKey, mixed $value, ?int $ttl, ?Closure $operation = null): mixed
     {
-        $fo = fopen($fileKey, 'w');
+        $returnValue = true;
+
+        if (file_exists("$fileKey.ttl")) {
+            unlink("$fileKey.ttl");
+        }
+
+        if (is_null($value)) {
+            if (file_exists($fileKey)) {
+                unlink($fileKey);
+            }
+            return false;
+        }
+
+        $fo = fopen($fileKey, 'a+');
         $waitIfLocked = 1;
         $lock = flock($fo, LOCK_EX, $waitIfLocked);
         try {
+            if (!is_null($operation)) {
+                if (!file_exists($fileKey)) {
+                    $currentValue = 0;
+                } else {
+                    $content = file_get_contents($fileKey);
+                    $currentValue = !empty($content) ? unserialize($content) : $content;
+                }
+                $value = $returnValue = $operation($currentValue, $value);
+            }
             file_put_contents($fileKey, serialize($value));
             if (!is_null($ttl)) {
                 file_put_contents("$fileKey.ttl", serialize($ttl));
@@ -222,6 +235,8 @@ protected function putContents(string $fileKey, mixed $value, ?string $ttl): voi
             flock($fo, LOCK_UN);
             fclose($fo);
         }
+
+        return $returnValue;
     }
 
     public function collectGarbage()
@@ -250,4 +265,32 @@ public function getTtl(string $key): ?int
         }
         return null;
     }
+
+    public function increment(string $key, int $value = 1, DateInterval|int|null $ttl = null): int
+    {
+        return $this->putContents($this->fixKey($key), $value, $ttl, function ($currentValue, $value) {
+            return intval($currentValue) + $value;
+        });
+    }
+
+    public function decrement(string $key, int $value = 1, DateInterval|int|null $ttl = null): int
+    {
+        return $this->putContents($this->fixKey($key), $value, $ttl, function ($currentValue, $value) {
+            return intval($currentValue) - $value;
+        });
+    }
+
+    public function add(string $key, $value, DateInterval|int|null $ttl = null): array
+    {
+        return $this->putContents($this->fixKey($key), $value, $ttl, function ($currentValue, $value) {
+            if (empty($currentValue)) {
+                return [$value];
+            }
+            if (!is_array($currentValue)) {
+                return [$currentValue, $value];
+            }
+            $currentValue[] = $value;
+            return $currentValue;
+        });
+    }
 }
diff --git a/src/Psr16/MemcachedEngine.php b/src/Psr16/MemcachedEngine.php
@@ -2,6 +2,7 @@
 
 namespace ByJG\Cache\Psr16;
 
+use ByJG\Cache\AtomicOperationInterface;
 use ByJG\Cache\Exception\InvalidArgumentException;
 use ByJG\Cache\Exception\StorageErrorException;
 use DateInterval;
@@ -11,7 +12,7 @@
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 
-class MemcachedEngine extends BaseCacheEngine
+class MemcachedEngine extends BaseCacheEngine implements AtomicOperationInterface
 {
 
     /**
@@ -88,7 +89,7 @@ public function get(string $key, mixed $default = null): mixed
             return $default;
         }
 
-        return unserialize($value);
+        return $value;
     }
 
     /**
@@ -107,7 +108,7 @@ public function set(string $key, mixed $value, DateInterval|int|null $ttl = null
 
         $ttl = $this->convertToSeconds($ttl);
 
-        $this->memCached->set($this->fixKey($key), serialize($value), is_null($ttl) ? 0 : $ttl);
+        $this->memCached->set($this->fixKey($key), $value, is_null($ttl) ? 0 : $ttl);
         $this->logger->info("[Memcached] Set '$key' result " . $this->memCached->getResultCode());
         if ($this->memCached->getResultCode() !== Memcached::RES_SUCCESS) {
             $this->logger->error("[Memcached] Set '$key' failed with status " . $this->memCached->getResultCode());
@@ -172,4 +173,73 @@ public function has(string $key): bool
         $this->memCached->get($this->fixKey($key));
         return ($this->memCached->getResultCode() === Memcached::RES_SUCCESS);
     }
+
+    public function increment(string $key, int $value = 1, DateInterval|int|null $ttl = null): int
+    {
+        $this->lazyLoadMemCachedServers();
+
+        $ttl = $this->convertToSeconds($ttl);
+
+        if ($this->memCached->get($this->fixKey($key)) === false) {
+            $this->memCached->set($this->fixKey($key), 0, is_null($ttl) ? 0 : $ttl);
+        }
+
+        $result = $this->memCached->increment($this->fixKey($key), $value);
+        $this->logger->info("[Memcached] Increment '$key' result " . $this->memCached->getResultCode());
+        if ($this->memCached->getResultCode() !== Memcached::RES_SUCCESS) {
+            $this->logger->error("[Memcached] Set '$key' failed with status " . $this->memCached->getResultCode());
+        }
+
+        return $result;
+    }
+
+    public function decrement(string $key, int $value = 1, DateInterval|int|null $ttl = null): int
+    {
+        $this->lazyLoadMemCachedServers();
+
+        $ttl = $this->convertToSeconds($ttl);
+
+        if ($this->memCached->get($this->fixKey($key)) === false) {
+            $this->memCached->set($this->fixKey($key), 0, is_null($ttl) ? 0 : $ttl);
+        }
+
+        $result = $this->memCached->decrement($this->fixKey($key), $value);
+        $this->logger->info("[Memcached] Decrement '$key' result " . $this->memCached->getResultCode());
+        if ($this->memCached->getResultCode() !== Memcached::RES_SUCCESS) {
+            $this->logger->error("[Memcached] Set '$key' failed with status " . $this->memCached->getResultCode());
+        }
+
+        return $result;
+    }
+
+    public function add(string $key, $value, DateInterval|int|null $ttl = null): array
+    {
+        $this->lazyLoadMemCachedServers();
+
+        $ttl = $this->convertToSeconds($ttl);
+        $fixKey = $this->fixKey($key);
+
+        if ($this->memCached->get($fixKey) === false) {
+            $this->memCached->set($fixKey, [], is_null($ttl) ? 0 : $ttl);
+        }
+
+        do {
+            $data = $this->memCached->get($fixKey, null, Memcached::GET_EXTENDED);
+            $casToken = $data['cas'];
+            $currentValue = $data['value'];
+
+            if ($currentValue === false) {
+                $currentValue = [];
+            }
+
+            if (!is_array($currentValue)) {
+                $currentValue = [$currentValue];
+            }
+
+            $currentValue[] = $value;
+            $success = $this->memCached->cas($casToken, $fixKey, $currentValue, is_null($ttl) ? 0 : $ttl);
+        } while (!$success);
+
+        return $currentValue;
+    }
 }
diff --git a/src/Psr16/RedisCacheEngine.php b/src/Psr16/RedisCacheEngine.php
diff --git a/tests/BaseCacheTest.php b/tests/BaseCacheTest.php
diff --git a/tests/CachePSR16Test.php b/tests/CachePSR16Test.php
