Merge branch 'main' into DOC-4137

Author: cmilesb

content/commands/client-caching/index.md

@@ -43,7 +43,7 @@ title: CLIENT CACHING
 This command controls the tracking of the keys in the next command executed
 by the connection, when tracking is enabled in `OPTIN` or `OPTOUT` mode.
 Please check the
-[client side caching documentation]({{< relref "/develop/use/client-side-caching" >}}) for
+[client side caching documentation]({{< relref "/develop/connect/clients/client-side-caching" >}}) for
 background information.
 
 When tracking is enabled Redis, using the [`CLIENT TRACKING`]({{< relref "/commands/client-tracking" >}}) command, it is

content/commands/client-getredir/index.md

@@ -31,7 +31,7 @@ syntax_str: ''
 title: CLIENT GETREDIR
 ---
 This command returns the client ID we are redirecting our
-[tracking]({{< relref "/develop/use/client-side-caching" >}}) notifications to. We set a client
+[tracking]({{< relref "/develop/connect/clients/client-side-caching#tracking" >}}) notifications to. We set a client
 to redirect to when using [`CLIENT TRACKING`]({{< relref "/commands/client-tracking" >}}) to enable tracking. However in
 order to avoid forcing client libraries implementations to remember the
 ID notifications are redirected to, this command exists in order to improve

content/commands/client-tracking/index.md

@@ -75,7 +75,7 @@ syntax_str: "[REDIRECT\_client-id] [PREFIX\_prefix [PREFIX prefix ...]] [BCAST]
 title: CLIENT TRACKING
 ---
 This command enables the tracking feature of the Redis server, that is used
-for [server assisted client side caching]({{< relref "/develop/use/client-side-caching" >}}).
+for [server assisted client side caching]({{< relref "/develop/connect/clients/client-side-caching#tracking" >}}).
 
 When tracking is enabled Redis remembers the keys that the connection
 requested, in order to send later invalidation messages when such keys are
@@ -85,7 +85,7 @@ when the RESP3 protocol is used) or redirected in a different connection
 available where clients participating in this protocol receive every
 notification just subscribing to given key prefixes, regardless of the
 keys that they requested. Given the complexity of the argument please
-refer to [the main client side caching documentation]({{< relref "/develop/use/client-side-caching" >}}) for the details. This manual page is only a reference for the options of this subcommand.
+refer to [the main client side caching documentation]({{< relref "/develop/reference/client-side-caching" >}}) for the details. This manual page is only a reference for the options of this subcommand.
 
 In order to enable tracking, use:
 

content/commands/client-trackinginfo/index.md

@@ -29,7 +29,7 @@ syntax_fmt: CLIENT TRACKINGINFO
 syntax_str: ''
 title: CLIENT TRACKINGINFO
 ---
-The command returns information about the current client connection's use of the [server assisted client side caching]({{< relref "/develop/use/client-side-caching" >}}) feature.
+The command returns information about the current client connection's use of the [server assisted client side caching]({{< relref "/develop/connect/clients/client-side-caching" >}}) feature.
 
 Here's the list of tracking information sections and their respective values:
 

content/develop/connect/clients/client-side-caching.md

@@ -17,8 +17,6 @@ weight: 20
 
 *Client-side caching* reduces network traffic between
 a Redis client and the server, which generally improves performance.
-See [Client-side caching compatibility with Redis Software and Redis Cloud]({{< relref "operate/rs/references/compatibility/client-side-caching" >}})
-for details on Redis versions that support client-side caching.
 
 By default, an [application server](https://en.wikipedia.org/wiki/Application_server)
 (which sits between the user app and the database) contacts the
@@ -45,7 +43,7 @@ client-side caching works well in the very common use case where a small subset
 is accessed much more frequently than the rest of the data (according
 to the [Pareto principle](https://en.wikipedia.org/wiki/Pareto_principle)).
 
-## Updating the cache when the data changes
+## Updating the cache when the data changes {#tracking}
 
 All caching systems must implement a scheme to update data in the cache
 when the corresponding data changes in the main database. Redis uses an
@@ -63,6 +61,12 @@ will evict the stale data in response. Next time a client reads from
 the same key, it will access the database directly and refresh its cache
 with the updated data.
 
+{{< note >}}If any connection from a client gets disconnected (including
+one from a connection pool), then the client will flush all keys from the
+client-side cache. Caching then resumes for subsequent reads from the
+connections that are still active.
+{{< /note >}}
+
 The sequence diagram below shows how two clients might interact as they
 access and update the same key:
 
@@ -82,7 +86,7 @@ will use cached data, except for the following:
     [`HSCAN`]({{< relref "/commands/hscan" >}}),
     and [`ZRANDMEMBER`]({{< relref "/commands/zrandmember" >}}). By design, these commands
     give different results each time they are called.
--   Search and query commands (with the `FT.*` prefix), such as
+-   Redis Query Engine commands (with the `FT.*` prefix), such as
     [`FT.SEARCH`]({{< baseurl >}}/commands/ft.search).
 
 You can use the [`MONITOR`]({{< relref "/commands/monitor" >}}) command to

content/develop/connect/clients/dotnet.md

@@ -37,7 +37,7 @@ dotnet add package NRedisStack
 
 Connect to localhost on port 6379.
 
-```
+```csharp
 using NRedisStack;
 using NRedisStack.RedisStackCommands;
 using StackExchange.Redis;
@@ -70,7 +70,7 @@ Console.WriteLine(String.Join("; ", hashFields));
 // name: John; surname: Smith; company: Redis; age: 29
 ```
 
-To access Redis Stack capabilities, you should use appropriate interface like this:
+To access Redis Stack capabilities, use the appropriate interface like this:
 
 ```
 IBloomCommands bf = db.BF();
@@ -84,7 +84,7 @@ IJsonCommands json = db.JSON();
 ITimeSeriesCommands ts = db.TS();
 ```
 
-### Connect to a Redis cluster
+## Connect to a Redis cluster
 
 To connect to a Redis cluster, you just need to specify one or all cluster endpoints in the client configuration:
 
@@ -106,7 +106,7 @@ db.StringSet("foo", "bar");
 Console.WriteLine(db.StringGet("foo")); // prints bar
 ```
 
-### Connect to your production Redis with TLS
+## Connect to your production Redis with TLS
 
 When you deploy your application, use TLS and follow the [Redis security]({{< relref "/operate/oss_and_stack/management/security/" >}}) guidelines.
 
@@ -169,6 +169,23 @@ conn.StringSet("foo", "bar");
 Console.WriteLine(conn.StringGet("foo"));   
 ```
 
+## Multiplexing
+
+Although example code typically works with a single connection,
+real-world code often uses multiple connections at the same time.
+Opening and closing connections repeatedly is inefficient, so it is best
+to manage open connections carefully to avoid this.
+
+Several other
+Redis client libraries use *connection pools* to reuse a set of open
+connections efficiently. NRedisStack uses a different approach called
+*multiplexing*, which sends all client commands and responses over a
+single connection. NRedisStack manages multiplexing for you automatically.
+This gives high performance without requiring any extra coding.
+See
+[Connection pools and multiplexing]({{< relref "/develop/connect/clients/pools-and-muxing" >}})
+for more information.
+
 ## Example: Indexing and querying JSON documents
 
 This example shows how to convert Redis search results to JSON format using `NRedisStack`.

content/develop/connect/clients/java/jedis.md

@@ -56,46 +56,36 @@ To include `Jedis` as a dependency in your application, edit the dependency file
 
 ## Connect
 
-For many applications, it's best to use a connection pool. You can instantiate and use a `Jedis` connection pool like so:
+The following code opens a basic connection to a local Redis server:
 
 ```java
 package org.example;
-import redis.clients.jedis.Jedis;
-import redis.clients.jedis.JedisPool;
+import redis.clients.jedis.UnifiedJedis;
 
 public class Main {
     public static void main(String[] args) {
-        JedisPool pool = new JedisPool("localhost", 6379);
+        UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379");
 
-        try (Jedis jedis = pool.getResource()) {
-            // Store & Retrieve a simple string
-            jedis.set("foo", "bar");
-            System.out.println(jedis.get("foo")); // prints bar
-            
-            // Store & Retrieve a HashMap
-            Map<String, String> hash = new HashMap<>();;
-            hash.put("name", "John");
-            hash.put("surname", "Smith");
-            hash.put("company", "Redis");
-            hash.put("age", "29");
-            jedis.hset("user-session:123", hash);
-            System.out.println(jedis.hgetAll("user-session:123"));
-            // Prints: {name=John, surname=Smith, company=Redis, age=29}
-        }
+        // Code that interacts with Redis...
+
+        jedis.close();
     }
 }
 ```
 
-Because adding a `try-with-resources` block for each command can be cumbersome, consider using `JedisPooled` as an easier way to pool connections.
+After you have connected, you can check the connection by storing and
+retrieving a simple string value:
 
 ```java
-import redis.clients.jedis.JedisPooled;
+...
 
-//...
+String res1 = jedis.set("bike:1", "Deimos");
+System.out.println(res1); // OK
 
-JedisPooled jedis = new JedisPooled("localhost", 6379);
-jedis.set("foo", "bar");
-System.out.println(jedis.get("foo")); // prints "bar"
+String res2 = jedis.get("bike:1");
+System.out.println(res2); // Deimos
+
+...
 ```
 
 ### Connect to a Redis cluster
@@ -309,15 +299,65 @@ client.hget("person:2", "name");    // Read from the server
 client.hget("person:2", "name");    // Read from the cache
 ```
 
-## Production usage
+The client will also flush the cache automatically
+if any connection (including one from a connection pool)
+is disconnected.
 
-The following sections explain how to handle situations that may occur
-in your production environment.
+## Connect with a connection pool
 
-### Configuring a connection pool
+For production usage, you should use a connection pool to manage
+connections rather than opening and closing connections individually.
+A connection pool maintains several open connections and reuses them
+efficiently. When you open a connection from a pool, the pool allocates
+one of its open connections. When you subsequently close the same connection,
+it is not actually closed but simply returned to the pool for reuse.
+This avoids the overhead of repeated connecting and disconnecting.
+See
+[Connection pools and multiplexing]({{< relref "/develop/connect/clients/pools-and-muxing" >}})
+for more information.
+
+Use the following code to connect with a connection pool:
+
+```java
+package org.example;
+import redis.clients.jedis.Jedis;
+import redis.clients.jedis.JedisPool;
+
+public class Main {
+    public static void main(String[] args) {
+        JedisPool pool = new JedisPool("localhost", 6379);
+
+        try (Jedis jedis = pool.getResource()) {
+            // Store & Retrieve a simple string
+            jedis.set("foo", "bar");
+            System.out.println(jedis.get("foo")); // prints bar
+            
+            // Store & Retrieve a HashMap
+            Map<String, String> hash = new HashMap<>();;
+            hash.put("name", "John");
+            hash.put("surname", "Smith");
+            hash.put("company", "Redis");
+            hash.put("age", "29");
+            jedis.hset("user-session:123", hash);
+            System.out.println(jedis.hgetAll("user-session:123"));
+            // Prints: {name=John, surname=Smith, company=Redis, age=29}
+        }
+    }
+}
+```
+
+Because adding a `try-with-resources` block for each command can be cumbersome, consider using `JedisPooled` as an easier way to pool connections. `JedisPooled`, added in Jedis version 4.0.0, provides capabilities similar to `JedisPool` but with a more straightforward API.
+
+```java
+import redis.clients.jedis.JedisPooled;
+
+//...
+
+JedisPooled jedis = new JedisPooled("localhost", 6379);
+jedis.set("foo", "bar");
+System.out.println(jedis.get("foo")); // prints "bar"
+```
 
-As mentioned in the previous section, use `JedisPool` or `JedisPooled` to create a connection pool.
-`JedisPooled`, added in Jedis version 4.0.0, provides capabilities similar to `JedisPool` but with a more straightforward API.
 A connection pool holds a specified number of connections, creates more connections when necessary, and terminates them when they are no longer needed.
 
 Here is a simplified connection lifecycle in a pool:
@@ -363,6 +403,11 @@ poolConfig.setTimeBetweenEvictionRuns(Duration.ofSeconds(1));
 JedisPooled jedis = new JedisPooled(poolConfig, "localhost", 6379);
 ```
 
+## Production usage
+
+The following sections explain how to handle situations that may occur
+in your production environment.
+
 ### Timeouts
 
 To set a timeout for a connection, use the `JedisPooled` or `JedisPool` constructor with the `timeout` parameter, or use `JedisClientConfig` with the `socketTimeout` and `connectionTimeout` parameters:

content/develop/connect/clients/java/lettuce.md

@@ -234,6 +234,9 @@ try (RedisClient client = RedisClient.create(redisURI)) {
 
 A typical approach with Lettuce is to create a single `RedisClient` instance and reuse it to establish connections to your Redis server(s).
 These connections are multiplexed; that is, multiple commands can be run concurrently over a single or a small set of connections, making explicit pooling less practical.
+See
+[Connection pools and multiplexing]({{< relref "/develop/connect/clients/pools-and-muxing" >}})
+for more information.
 
 Lettuce provides pool config to be used with Lettuce asynchronous connection methods.
 

content/develop/connect/clients/pools-and-muxing.md

@@ -0,0 +1,80 @@
+---
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+description: Manage Redis connections efficiently
+linkTitle: Pooling/multiplexing
+title: Connection pools and multiplexing
+weight: 10
+---
+
+Redis example code generally opens a connection, demonstrates
+a command or feature, and then closes. Real-world code typically
+has short bursts of communication with the server and periods of
+inactivity in between. Opening and closing connections
+involves some overhead and leads to inefficiency if you do
+it frequently. This means that you can improve the performance of production
+code by making as few separate connections as possible.
+
+Managing connections in your own code can be tricky, so the Redis
+client libraries give you some help. The two basic approaches to
+connection management are called *connection pooling* and *multiplexing*.
+The [`redis-py`]({{< relref "/develop/connect/clients/python/redis-py" >}}),
+[`jedis`]({{< relref "/develop/connect/clients/java/jedis" >}}), and
+[`go-redis`]({{< relref "/develop/connect/clients/go" >}}) clients support
+connection pooling, while
+[`NRedisStack`]({{< relref "/develop/connect/clients/dotnet" >}})
+supports multiplexing.
+[`Lettuce`]({{< relref "/develop/connect/clients/java/lettuce" >}})
+supports both approaches.
+
+## Connection pooling
+
+When you initialize a connection pool, the client opens a small number
+of connections and adds them to the pool.
+
+{{< image filename="/images/dev/connect/pool-and-mux/ConnPoolInit.drawio.svg" >}}
+
+Each time you "open" a connection
+from the pool, the client returns one of these existing
+connections and notes the fact that it is in use.
+
+{{< image filename="/images/dev/connect/pool-and-mux/ConnPoolInUse.drawio.svg" >}}
+
+When you later "close"
+the connection, the client puts it back into the pool of available
+connections without actually closing it.
+
+{{< image filename="/images/dev/connect/pool-and-mux/ConnPoolDiscon.drawio.svg" >}}
+
+If all connections in the pool are in use but the app needs more, then
+the client can simply open new connections as necessary. In this way, the client
+eventually finds the right number of connections to satisfy your
+app's demands.
+
+## Multiplexing
+
+Instead of pooling several connections, a multiplexer keeps a
+single connection open and uses it for all traffic between the
+client and the server. The "connections" returned to your code are
+used to identify where to send the response data from your commands.
+
+{{< image filename="/images/dev/connect/pool-and-mux/ConnMux.drawio.svg" >}}
+
+Note that it is not a problem if the multiplexer receives several commands close
+together in time. When this happens, the multiplexer can often combine the commands into a
+[pipeline]({{< relref "/develop/use/pipelining" >}}), which
+improves efficiency.
+
+Multiplexing offers high efficiency but works transparently without requiring
+any special code to enable it in your app. The main disadvantage of multiplexing compared to
+connection pooling is that it can't support the blocking "pop" commands (such as
+[`BLPOP`]({{< relref "/commands/blpop" >}})) since these would stall the
+connection for all callers.