From e695eb7a92ecbd23f8de0e8ad7c4e553d2d314f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Till=20Kru=CC=88ss?= Date: Thu, 3 Jul 2025 13:14:48 -0700 Subject: [PATCH 1/3] wip --- docs/1.x/adaptive.md | 35 +++++++++++++++++++++++++++++++++++ docs/1.x/api.md | 5 +++-- docs/1.x/configuration.md | 3 ++- docs/1.x/connections.md | 2 +- docs/1.x/index.md | 5 +++-- 5 files changed, 44 insertions(+), 6 deletions(-) create mode 100644 docs/1.x/adaptive.md diff --git a/docs/1.x/adaptive.md b/docs/1.x/adaptive.md new file mode 100644 index 0000000..24825a0 --- /dev/null +++ b/docs/1.x/adaptive.md @@ -0,0 +1,35 @@ +--- +title: Adaptive Caching +--- + +# Adaptive Caching + +Relay supports an adaptive caching mechanism to only cache keys that meet a read-write ratio to aid applications that suffer from cache thrashing, e.g. WordPress sites. + +The configuration for the adaptive cache is highly individual to an application and should ideally be benchmarked. At the very least match the `width` of the cache to the unique number of keys that exist in the cache. + +```php +$relay = new Relay( + host: 'localhost', + port: 6379, + context: [ + 'adaptive-cache' => [ + // Number of horizontal cells. Ideally this should scale with the number of unique keys in the database. Supported values: 512 - 2^31. + 'width' => 100_000, + + // Number of vertical cells. Supported values: 1 - 8. + 'depth' => 6, + + // Minimum number of events (reads + writes) before Relay + // will use the ratio to determine if a key should remain cached. + // Using a negative number will invert this and Relay won't cache + // a key until its seen at least that many events for the key. + 'minEvents' => 10, + + // Minimum ratio of reads to writes of a key to remain + // cached (positive events) or be cached (negative events). + 'minRatio' => 5.0, + ], + ], +); +``` diff --git a/docs/1.x/api.md b/docs/1.x/api.md index d290cd9..281aacf 100644 --- a/docs/1.x/api.md +++ b/docs/1.x/api.md @@ -20,7 +20,8 @@ curl -O "https://builds.r2.relay.so/v0.9.1/relay.stub.php" All methods have PHP attributes to provide some metadata which can be inspected at runtime using the Reflection APIs. -- `Local` indicates the method _does not_ communicate with Redis -- `Server` indicates the method that _may_ communicate with Redis +- `Local` indicates the method _does not_ communicate with Redis/Valkey +- `Server` indicates the method that _may_ communicate with Redis/Valkey - `RedisCommand` indicates the method represents a [command](https://redis.io/commands/) +- `ValkeyCommand` indicates the method represents a [command](https://valkey.io/commands/) - `Cached` indicates the method _may_ use in-memory caching diff --git a/docs/1.x/configuration.md b/docs/1.x/configuration.md index d961b9a..a93b02e 100644 --- a/docs/1.x/configuration.md +++ b/docs/1.x/configuration.md @@ -41,13 +41,14 @@ To disable all in-memory caching and memory allocation `relay.maxmemory` can be | `relay.locks.cache` | `mutex` | Locking mechanism used for the in-memory cache (databases). Supported values: `spinlock`, `mutex`, `adaptive-mutex` | | `relay.default_pconnect` | `1` | Default to using a persistent connection when calling `connect()`. | | `relay.initial_readers` | `128` | The number of epoch readers allocated on startup. | -| `relay.invalidation_poll_freq` | `5` | How often (in microseconds) Relay should proactively check the connection for invalidation messages from Redis. | +| `relay.invalidation_poll_freq` | `5` | How often (in microseconds) Relay should proactively check the connection for invalidation messages from Redis/Valkey. | | `relay.loglevel` | `off` | Whether Relay should log debug information. Supported levels: `debug`, `verbose`, `error`, `off` | | `relay.logfile` | | The path to the file in which information should be logged, if logging is enabled. | | `relay.cluster.seeds` | | The list of cluster nodes addresses grouped by cluster name, which will be used to initialize each cluster, encoded as URL query string, e.g. `cluster1[]=127.0.0.1:7000&cluster2[]=127.0.0.1:8000` | | `relay.cluster.auth` | | The list of credentials for each cluster, encoded as URL query string. Password string or username/password pairs may be used, e.g. `cluster1=secret&cluster2[]=username&cluster2[]=secret` | | `relay.cluster.timeout` | | The maximum number of seconds Relay will wait while establishing connection to a single cluster node. | | `relay.cluster.read_timeout` | | The maximum number of seconds Relay will wait while reading from a cluster node. | +| `relay.cluster.slot_cache_expiry` | | ??? | | `relay.session.locking_enabled` | `0` | Whether to enable session locking to avoid race conditions and keep session data consistent across requests. | | `relay.session.lock_expire` | `0` | The number of seconds while Relay will try to acquire lock. When value is zero or negative `max_execution_time` will be used. | | `relay.session.lock_retries` | `0` | The number of attempts Relay will try to acquire lock. If value is zero or negative `100` will be used to be compatible with PhpRedis. | diff --git a/docs/1.x/connections.md b/docs/1.x/connections.md index 86f0ace..ffc6dce 100644 --- a/docs/1.x/connections.md +++ b/docs/1.x/connections.md @@ -8,7 +8,7 @@ title: Connections ## Overview -Relay treats all connections as persistent by default, meaning each PHP worker will open its own dedicated connection to Redis and it will be reused between invocations. +Relay treats all connections as persistent by default, meaning each PHP worker will open its own dedicated connection to Redis/Valkey and it will be reused between invocations. Establishing connections with Relay can be done just like using PhpRedis: diff --git a/docs/1.x/index.md b/docs/1.x/index.md index b5b2882..79905cc 100644 --- a/docs/1.x/index.md +++ b/docs/1.x/index.md @@ -7,10 +7,11 @@ - [Integrations](/docs/1.x/integrations) - ##### The Basics - [Connections](/docs/1.x/connections) + - [Eviction](/docs/1.x/eviction) - [Events](/docs/1.x/events) - - [Tables](/docs/1.x/tables) + - [Ratios](/docs/1.x/events) - [Options](/docs/1.x/options) - - [Eviction](/docs/1.x/eviction) + - [Tables](/docs/1.x/tables) - ##### Digging Deeper - [Performance](/docs/1.x/performance) - [Compatibility](/docs/1.x/compatibility) From c6ab9321d9d3151142f1d6b8f5b586815d415126 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Till=20Kr=C3=BCss?= Date: Thu, 3 Jul 2025 13:17:38 -0700 Subject: [PATCH 2/3] Update adaptive.md --- docs/1.x/adaptive.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/1.x/adaptive.md b/docs/1.x/adaptive.md index 24825a0..dfe31ef 100644 --- a/docs/1.x/adaptive.md +++ b/docs/1.x/adaptive.md @@ -14,7 +14,8 @@ $relay = new Relay( port: 6379, context: [ 'adaptive-cache' => [ - // Number of horizontal cells. Ideally this should scale with the number of unique keys in the database. Supported values: 512 - 2^31. + // Number of horizontal cells. Ideally this should scale with the + // number of unique keys in the database. Supported values: 512 - 2^31. 'width' => 100_000, // Number of vertical cells. Supported values: 1 - 8. From 4466e32e29369b3c226ebecb49257f3ed2a4aba4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Till=20Kr=C3=BCss?= Date: Tue, 29 Jul 2025 12:23:45 -0700 Subject: [PATCH 3/3] Update configuration.md --- docs/1.x/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/1.x/configuration.md b/docs/1.x/configuration.md index a93b02e..f88c23a 100644 --- a/docs/1.x/configuration.md +++ b/docs/1.x/configuration.md @@ -48,7 +48,7 @@ To disable all in-memory caching and memory allocation `relay.maxmemory` can be | `relay.cluster.auth` | | The list of credentials for each cluster, encoded as URL query string. Password string or username/password pairs may be used, e.g. `cluster1=secret&cluster2[]=username&cluster2[]=secret` | | `relay.cluster.timeout` | | The maximum number of seconds Relay will wait while establishing connection to a single cluster node. | | `relay.cluster.read_timeout` | | The maximum number of seconds Relay will wait while reading from a cluster node. | -| `relay.cluster.slot_cache_expiry` | | ??? | +| `relay.cluster.slot_cache_expiry` | | The TTL of the cluster slot cache. | | `relay.session.locking_enabled` | `0` | Whether to enable session locking to avoid race conditions and keep session data consistent across requests. | | `relay.session.lock_expire` | `0` | The number of seconds while Relay will try to acquire lock. When value is zero or negative `max_execution_time` will be used. | | `relay.session.lock_retries` | `0` | The number of attempts Relay will try to acquire lock. If value is zero or negative `100` will be used to be compatible with PhpRedis. |