working on docs

tillkruss · tillkruss · commit a67cab166de1 · 2026-05-28T19:42:43.000-07:00
diff --git a/docs/1.x/adaptive.md b/docs/1.x/adaptive.md
@@ -6,6 +6,8 @@ title: 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 problem it solves is thrashing: when every key is cached, a flood of one-off reads can evict the small, hot set of keys your application actually relies on. By observing access patterns and only keeping keys whose reads sufficiently outweigh their writes, Relay keeps its cache warm even under realistic, skewed workloads — where a small slice of keys absorbs the bulk of the reads.
+
 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
@@ -24,7 +26,7 @@ $relay = new Relay(
             // 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.
+            // a key until it's seen at least that many events for the key.
             'minEvents' => 10,
 
             // Minimum ratio of reads to writes of a key to remain
diff --git a/docs/1.x/api.md b/docs/1.x/api.md
@@ -4,15 +4,15 @@ title: API
 
 # API
 
-Relay's API is available in a searchable format at [docs.relay.so/api](https://docs.relay.so/api/develop/) and bundled with the extension [stubs of PhpStorm](https://github.com/JetBrains/phpstorm-stubs).
+Relay's API is available in a searchable format at [docs.relay.so/api](https://docs.relay.so/api/develop/) and bundled with [PhpStorm's extension stubs](https://github.com/JetBrains/phpstorm-stubs).
 
 ## Stubs
 
 All [builds](/docs/1.x/builds) include a `relay.stub.php` file, which outlines that build’s classes and their APIs. Fetching a specific stub without downloading a build can be done as well:
 
 ```bash
 wget "https://builds.r2.relay.so/dev/relay.stub.php"
-curl -O "https://builds.r2.relay.so/v0.21.0/relay.stub.php"
+curl -O "https://builds.r2.relay.so/{{relay}}/relay.stub.php"
 ```
 
 ## Attributes
diff --git a/docs/1.x/builds.md b/docs/1.x/builds.md
@@ -30,8 +30,8 @@ curl "https://builds.r2.relay.so/meta/builds"
 
 ## Release artifacts
 
-Each release has a `artifacts.json` that contains the various build artifacts.
+Each release has an `artifacts.json` that contains the various build artifacts.
 
 ```bash
-curl "https://builds.r2.relay.so/v0.21.0/artifacts.json"
+curl "https://builds.r2.relay.so/{{relay}}/artifacts.json"
 ```
diff --git a/docs/1.x/configuration.md b/docs/1.x/configuration.md
@@ -32,7 +32,7 @@ To disable all in-memory caching and memory allocation `relay.maxmemory` can be
 | `relay.environment`               | `development`    | The environment Relay is running in. Supported values: `production`, `staging`, `testing`, `development` |
 | `relay.maxmemory`                 | `16MB`           | How much memory Relay allocates on startup. This value can either be a number like `134217728` [or a unit](https://php.net/manual/faq.using.php#faq.using.shorthandbytes) (e.g. `128M`) like `memory_limit`. Relay will allocate at least 16M for overhead structures. Set to `0` to disable in-memory caching and use as client only. |
 | `relay.maxmemory_pct`             | `95`             | At what percentage of used memory should Relay start evicting keys. |
-| `relay.eviction_policy`           | `noeviction`     | How should relay evict keys. This has been designed to mirror Redis’ options. Supported values: `noeviction`, `lru`, and `random` |
+| `relay.eviction_policy`           | `noeviction`     | How should Relay evict keys. This has been designed to mirror Redis’ options. Supported values: `noeviction`, `lru`, and `random` |
 | `relay.eviction_sample_keys`      | `128`            | How many keys should we scan each time we process evictions. |
 | `relay.databases`                 | `16`             | The number of databases Relay will create per in-memory cache. This setting should match the `databases` setting in your `redis.conf`. |
 | `relay.max_endpoint_dbs`          | `32`             | The maximum number of PHP workers that will have their own in-memory cache. This setting is per connection endpoint (distinct Redis connections), e.g. connecting to two separate instances will double the workers. See [Performance](/docs/1.x/performance). |
@@ -52,7 +52,7 @@ To disable all in-memory caching and memory allocation `relay.maxmemory` can be
 | `relay.cluster.slot_cache_expiry` |                  | The TTL of the cluster slot cache. |
 | `relay.cluster.shard_health_wait_time` | `0`         | The time to wait for shard health checks. |
 | `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_expire`       | `0`              | The number of seconds 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. |
 | `relay.session.lock_wait_time`    | `0`              | The number of microseconds Relay will wait between each attempt to acquire lock. If value is zero or negative `20000` will be used to be compatible with PhpRedis. |
 | `relay.session.compression`       | `none`           | Compression algorithm used for session data. Supported values: `lzf`, `lz4`, `zstd` and `none` |
diff --git a/docs/1.x/events.md b/docs/1.x/events.md
@@ -12,7 +12,7 @@ Relay’s in-memory cache is exceptionally fast and reliable, however in some sc
 
 On distributed infrastructures Relay will execute event callbacks `0.01ms` after the key changed in Redis. If a key is deleted or altered using Relay itself, it will perform [client-side invalidation](#client-side-invalidation) and __additionally__ execute event listeners instantaneously on all workers in the same PHP process pool.
 
-Event listeners are executed, after Relay invalidated keys in its in-memory cache.
+Event listeners are executed after Relay has invalidated keys in its in-memory cache.
 
 ## Event types
 
@@ -43,15 +43,15 @@ It’s worth noting that event listeners are connection specific, which means:
 
 ## Listening for flushes
 
-Application might want to register a distinct callback for `FLUSHDB` and `FLUSHALL` events. This can be accomplished using the `onFlushed()` method:
+Applications might want to register a distinct callback for `FLUSHDB` and `FLUSHALL` events. This can be accomplished using the `onFlushed()` method:
 
 ```php
 $relay->onFlushed(fn () => flushCache());
 ```
 
 ## Listening for invalidations
 
-Application may want to register one or more distinct invalidation listeners. This also be accomplished using the `onInvalidated()` method:
+Applications may want to register one or more distinct invalidation listeners. This can also be accomplished using the `onInvalidated()` method:
 
 ```php
 $relay->onInvalidated($callback);
diff --git a/docs/1.x/installation.md b/docs/1.x/installation.md
@@ -44,7 +44,7 @@ _It is worth noting that macOS lacks a decent futex mechanism and Relay will be
 
 ## Linux
 
-Relay can be installed on any Linux system. We have [packages](https://github.com/cachewerk/linux-repos) for popular PHP repositories, and for other common systems we have various [Docker examples](https://github.com/cachewerk/relay/tree/main/docker), as well as [manual installation instructions](#manual-installation) for highly customized system.
+Relay can be installed on any Linux system. We have [packages](https://github.com/cachewerk/linux-repos) for popular PHP repositories, and for other common systems we have various [Docker examples](https://github.com/cachewerk/relay/tree/main/docker), as well as [manual installation instructions](#manual-installation) for highly customized systems.
 
 ## Using Docker
 
@@ -201,7 +201,7 @@ jobs:
         with:
           php-version: 8.4
           extensions: relay
-          # extensions: relay-0.12.1
+          # extensions: relay-0.22.0
           # extensions: relay-nightly
 
       - name: Dump Relay configuration
@@ -254,7 +254,7 @@ Next, [grab the URL](/docs/1.x/builds) for the build matching the system. We'll
 
 ```bash
 mkdir /tmp/relay
-curl -sSL "https://builds.r2.relay.so/v0.21.0/relay-v0.21.0-php8.1-debian-x86-64.tar.gz" | tar -xz --strip-components=1 -C /tmp/relay
+curl -sSL "https://builds.r2.relay.so/{{relay}}/relay-{{relay}}-php8.1-debian-x86-64.tar.gz" | tar -xz --strip-components=1 -C /tmp/relay
 ```
 
 If we're missing a build for your particular system or architecture, please [open an issue](https://github.com/cachewerk/relay/issues).
@@ -275,7 +275,7 @@ ldd /tmp/relay/relay.so
 # liblz4.so.1 => /lib/aarch64-linux-gnu/liblz4.so.1 (0x0000ffff96203000)
 ```
 
-_If you're looking for OpenSSL 3.0 builds, you need to download the artifact with the `+libssl3` modifier instead.
+_If you're looking for OpenSSL 3.0 builds, you need to download the artifact with the `+libssl3` modifier instead._
 
 _If you're seeing a `not a dynamic executable` error, then the downloaded build doesn't match the os/arch, or your obscure distro is blocking `ldd` calls in `/tmp`._
 
@@ -378,7 +378,7 @@ First, ensure that the `json`, `igbinary` and `msgpack` PHP extensions are insta
 Then make sure `zstd` and `lz4` are installed, as well as other required system libraries.
 
 ```bash
-RELAY_VERSION="v0.21.0"                        # https://builds.r2.relay.so/meta/latest
+RELAY_VERSION="{{relay}}" # https://builds.r2.relay.so/meta/latest
 RELAY_PHP=$(php-config --version | cut -c -3)  # 8.1
 RELAY_INI_DIR=$(php-config --ini-dir)          # /etc/php/8.1/cli/conf.d/
 RELAY_EXT_DIR=$(php-config --extension-dir)    # /usr/lib/php/20210902
diff --git a/docs/1.x/introduction.md b/docs/1.x/introduction.md
@@ -4,7 +4,7 @@ title: Introduction
 
 # Introduction
 
-Relay is a PHP extension, that is a drop-in replacement for [PhpRedis](https://github.com/phpredis/phpredis) as well as a shared in-memory cache like APCu.
+Relay is a PHP extension that is a drop-in replacement for [PhpRedis](https://github.com/phpredis/phpredis) as well as a shared in-memory cache like APCu.
 
 It allows PHP to interact with Redis just like PhpRedis does, however all retrieved keys are also held in PHP’s memory, which is shared across all FPM workers.
 
@@ -18,6 +18,8 @@ $redis->connect('127.0.0.1', 6379);
 $users = $redis->get('users:count');
 ```
 
+Serving reads from local memory instead of over the network makes them dramatically faster — Relay's [benchmarks](https://github.com/cachewerk/relay#benchmarks) show cache reads up to __100× faster__ than going to Redis — while cutting bandwidth to a bare minimum. Because this partial replica lives in the PHP master process and uses a multi-threaded, lock-free design, every worker can read from it concurrently without blocking. A single node can serve millions of requests per second, sidestepping the single-threaded bottleneck that often pushes Redis deployments into extra replication or clustering.
+
 To prevent its cache from going stale, Relay uses *server-assisted client side caching* to actively invalidate its in-memory cache. Meaning, __Relay will instantaneously know when the dataset on Redis changes__ and invalidate its local cache.
 
 ```php
@@ -42,7 +44,7 @@ App::setUserCount($redis->get('users:count'));
 
 $redis->onInvalidated(function ($event) {
     if ($event->key === 'users:count') {
-        $users = App::setUserCount(null);
+        App::setUserCount(null);
     }
 });
 ```
diff --git a/docs/1.x/performance.md b/docs/1.x/performance.md
@@ -6,6 +6,8 @@ title: Performance
 
 For Relay to perform at its peak, some configuration directives might need to be adjusted to match your system.
 
+Relay keeps its in-memory replica in the PHP master process and is built around a multi-threaded, lock-free read path: every PHP worker reads from the shared cache concurrently, without blocking on a global lock. This sidesteps the single-threaded bottleneck that often pushes Redis deployments into extra replication or clustering, and lets throughput scale with the number of CPU cores. The directives below tune how that shared memory is sized and partitioned, and which locking primitives Relay uses for writes and allocation.
+
 ## `relay.max_endpoint_dbs`
 
 This directive determines the maximum number of PHP workers that will have their own in-memory cache. Not all workers need their own cache — workers without one become read-only workers that read from the shared memory pool. Giving too many workers an in-memory cache can negatively impact performance.
@@ -30,7 +32,7 @@ The default locking mechanism used for the in-memory cache and allocator is `ada
 
 - `spinlock`: The lowest latency lock which will busy-wait until the lock is available. This is likely the right choice on machines with only a few cores.
 - `mutex`: When contention is detected, this lock will sleep until it is available. It has higher latency than a spinlock but uses far less CPU. On machines with many cores it is likely the right choice.
-- `adaptive-mutex`: This lock is a hybrid of the two above. When contention is detected it will first spin waiting for the lock to free and then sleep if the lock is still not available. Each time it spins it will update its strategy depending on how long it took. Requires glibc and will fallback to `mutex` if glibc is not available.
+- `adaptive-mutex`: This lock is a hybrid of the two above. When contention is detected it will first spin waiting for the lock to free and then sleep if the lock is still not available. Each time it spins it will update its strategy depending on how long it took. Requires glibc and will fall back to `mutex` if glibc is not available.
 
 ## `relay.cap_endpoint_dbs`
 
