[lh0156]

Documents how ClusterPipeline retains per-node connections until sync() or close(), and how concurrent multi-node pipelines can wait indefinitely when the pool uses its default unbounded wait. The guide now recommends a dedicated cluster client with a pool sized for expected concurrency and a finite maxWait, plus single-shard pipelines where possible.

This follows the maintainer guidance on #4557 without changing cluster pipeline acquisition semantics.

Refs #4557.

---

Note

Low Risk
Documentation-only change with no code or configuration defaults modified.

Overview
Adds a Pipelining subsection, Avoiding pool waits with cluster pipelines, to docs/advanced-usage.md.

It documents that ClusterPipeline holds a borrowed connection on each targeted node until sync() or close(), and that overlapping multi-node pipelines with small per-node pools and default unbounded pool wait can deadlock or hang indefinitely.

The guide recommends a dedicated RedisClusterClient with ConnectionPoolConfig sized for expected concurrent pipelines and a finite maxWait, includes a try-with-resources example, and advises single-shard pipelines when possible. No runtime or API changes.

^{Reviewed by Cursor Bugbot for commit 7838c26. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit c0e7984. Configure here.}

[ggivo]

@lh0156
Thanks for the PR. The team is a bit stretched at the moment, and I’ll be away for a few days this week. We’ll get to it as soon as we can.

[ggivo]

Not sure there is a reliable way of detecting a deadlock.
With the suggested "fail-fast approach implementation," we are changing ClusterPipeline behaviour to discard pool-level configured maxWait. Means that now, in the case of a loaded pool, we can close pipelines preemptively.

I think having a dedicated client with a configured maxWait can cover this scenario without the need for a code change.

[lh0156]

Thanks for the guidance. I reworked this PR into a documentation-only change. It now explains that ClusterPipeline retains per-node connections until sync or close, recommends a dedicated client with an appropriately sized pool and a finite maxWait, and suggests single-shard pipelines where possible. There is no runtime behavior or pool-semantics change anymore. @ggivo, could you take another look when you have a chance?

[ggivo]

LGTM