Skip to content

glide_sync.client_pool

Client-instance pool for the synchronous GLIDE client.

Backed by the shared Rust pool in glide-core via FFI. The Rust pool owns client lifecycle (creation, LIFO reuse, bounded size). This Python class provides the acquire-with-timeout retry loop and maps client_id handles to usable GlideClient wrappers for command dispatch.

Usage

from glide_sync import GlideClient, GlideClientConfiguration, NodeAddress from glide_sync.client_pool import ClientPool, PoolConfig

config = GlideClientConfiguration([NodeAddress("localhost", 6379)]) pool = ClientPool(config, PoolConfig(max_size=10, min_idle=2))

Borrow a client, use it, return it automatically

with pool.borrow() as client: client.set("key", "value") result = client.get("key")

pool.close()

PoolConfig dataclass

Configuration for the client-instance pool.

Source code in doc-gen/valkey-glide/python/glide-sync/glide_sync/client_pool.py
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
@dataclass
class PoolConfig:
    """Configuration for the client-instance pool."""

    max_size: int = 10
    """Maximum number of clients in the pool."""

    min_idle: int = 1
    """Minimum idle clients to pre-warm at creation."""

    idle_timeout_ms: int = 300_000
    """Evict idle clients after this duration (ms). Default: 5 minutes."""

    request_timeout_ms: int = 5_000
    """Request timeout for commands (ms)."""

    acquire_timeout_s: float = 5.0
    """Maximum time to wait when pool is exhausted (seconds)."""

    abandon_timeout_ms: int = 300_000
    """Maximum inactivity time for a borrowed client before the pool reclaims it (ms).
    The timer resets on every command sent. The abandon monitor skips clients
    executing blocking commands (BLPOP, XREAD BLOCK, etc.).
    Set to 0 to disable abandon detection. Default: 5 minutes."""

max_size = 10 class-attribute instance-attribute

Maximum number of clients in the pool.

min_idle = 1 class-attribute instance-attribute

Minimum idle clients to pre-warm at creation.

idle_timeout_ms = 300000 class-attribute instance-attribute

Evict idle clients after this duration (ms). Default: 5 minutes.

request_timeout_ms = 5000 class-attribute instance-attribute

Request timeout for commands (ms).

acquire_timeout_s = 5.0 class-attribute instance-attribute

Maximum time to wait when pool is exhausted (seconds).

abandon_timeout_ms = 300000 class-attribute instance-attribute

Maximum inactivity time for a borrowed client before the pool reclaims it (ms). The timer resets on every command sent. The abandon monitor skips clients executing blocking commands (BLPOP, XREAD BLOCK, etc.). Set to 0 to disable abandon detection. Default: 5 minutes.

ClientPool

Client-instance pool backed by the Rust core.

The Rust pool owns client lifecycle (creation, bounded size). This Python class provides: - acquire-with-timeout retry loop (exponential backoff) - Cached GlideClient wrappers (one per client_id, reused across borrows) - Zero-overhead borrow() context manager

Source code in doc-gen/valkey-glide/python/glide-sync/glide_sync/client_pool.py
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
class ClientPool:
    """
    Client-instance pool backed by the Rust core.

    The Rust pool owns client lifecycle (creation, bounded size).
    This Python class provides:
    - acquire-with-timeout retry loop (exponential backoff)
    - Cached GlideClient wrappers (one per client_id, reused across borrows)
    - Zero-overhead borrow() context manager
    """

    __slots__ = (
        "_ffi",
        "_lib",
        "_client_config",
        "_pool_config",
        "_closed",
        "_client_cache",
        "_conn_req_bytes",
        "_pool_id",
        "_cache_lock",
    )

    @classmethod
    def create(
        cls,
        client_config: BaseClientConfiguration,
        pool_config: Optional[PoolConfig] = None,
    ) -> "ClientPool":
        """Create a pool and validate connectivity with a probe client.

        Creates the pool infrastructure, then attempts to connect a single
        probe client using the same config. If the probe fails, the pool is
        destroyed and the actual connection error is propagated (not a timeout).

        Args:
            client_config: Client configuration (standalone or cluster).
            pool_config: Optional pool sizing/timeout configuration.

        Returns:
            A ready-to-use ClientPool instance.

        Raises:
            The same exception that GlideClient.create() would raise on
            connection failure.
        """
        pool = cls(client_config, pool_config)
        try:
            probe = GlideClient.create(client_config)
            probe.close()
        except Exception:
            pool.close()
            raise
        return pool

    def __init__(
        self,
        client_config: BaseClientConfiguration,
        pool_config: Optional[PoolConfig] = None,
    ):
        # Custom providers are direct-client-only; pools may use the default AWS chain.
        credentials = getattr(client_config, "credentials", None)
        iam_config = getattr(credentials, "iam_config", None)
        if iam_config is not None and iam_config.credential_provider is not None:
            raise ValueError(
                "Pool clients cannot use a custom IAM credentials provider. "
                "Configure IAM without a credential_provider to use the default AWS credential chain."
            )

        # Reject pubsub subscriptions — pool state reset doesn't UNSUBSCRIBE
        if (
            hasattr(client_config, "pubsub_subscriptions")
            and client_config.pubsub_subscriptions
        ):
            raise ValueError(
                "Pool clients cannot have pubsub subscriptions configured. "
                "Use the main client's pubsub API for subscriptions."
            )

        # TODO: support RDMA in pools.
        if getattr(client_config, "rdma", None) is not None:
            raise ValueError(
                "Pool clients cannot have RDMA configured. "
                "Use a client outside a pool for RDMA transfers."
            )

        ffi_instance = _GlideFFI()
        self._ffi = ffi_instance.ffi
        self._lib = ffi_instance.lib
        self._client_config = client_config
        self._pool_config = pool_config or PoolConfig()
        self._closed = False
        self._client_cache: dict = {}
        # Lock for _client_cache under free-threading (concurrent get_or_create_client)
        self._cache_lock = threading.Lock()

        # Serialize the connection request protobuf. Route through the shared
        # helper so pooled clients honour lib_name / client_info_tag exactly
        # like direct GlideClient.create() clients do.
        conn_req = _create_sync_connection_request(client_config)
        self._conn_req_bytes = conn_req.SerializeToString()

        # Create the Rust pool via FFI (SyncClient type)
        client_type = self._ffi.new("ClientType*")
        client_type._type = 1  # Sync = 1 (from ClientTypeEnum)
        pool_id = self._lib.glide_pool_create(
            self._pool_config.max_size,
            self._pool_config.min_idle,
            self._pool_config.idle_timeout_ms,
            self._pool_config.request_timeout_ms,
            self._pool_config.abandon_timeout_ms,
            self._conn_req_bytes,
            len(self._conn_req_bytes),
            client_type,
        )

        if pool_id == -1:
            raise ValueError("Invalid pool configuration")
        if pool_id < 0:
            raise RuntimeError(f"Failed to create pool (error code: {pool_id})")

        self._pool_id = pool_id

    @property
    def pool_id(self) -> int:
        return self._pool_id

    @property
    def is_closed(self) -> bool:
        return self._closed

    def acquire(self, timeout: Optional[float] = None) -> int:
        """
        Acquire a client_id from the Rust pool.

        Blocks in Rust using a condvar until a client is available or timeout.
        Single FFI call — no polling loop.

        Returns:
            client_id (positive integer) for use with borrow() or get_client().

        Raises:
            TimeoutError: If no client available within timeout.
            RuntimeError: If pool is closed or invalid.
        """
        if self._closed:
            raise RuntimeError("Pool is closed")

        timeout = (
            timeout if timeout is not None else self._pool_config.acquire_timeout_s
        )
        timeout_ms = int(timeout * 1000)

        client_id = self._lib.glide_pool_acquire_blocking(self._pool_id, timeout_ms)

        if client_id >= 0:
            return client_id
        if client_id == -2:
            raise RuntimeError("Invalid pool_id — pool was destroyed")

        raise TimeoutError(
            f"Pool exhausted: could not acquire client within {timeout}s"
        )

    def release(self, client_id: int) -> None:
        """Release a borrowed client back to the pool."""
        self._lib.glide_pool_release(self._pool_id, client_id)

    def borrow(self, timeout: Optional[float] = None):
        """
        Returns a context manager that acquires a client from the Rust pool.

        The returned client dispatches commands through the native ClientAdapter
        managed by the Rust pool. On exit, the client is released back to the pool.

        Usage:
            with pool.borrow() as client:
                client.set("key", "value")
                result = client.get("key")
        """
        return _BorrowContext(self, timeout)

    def _get_or_create_client(self, client_id: int) -> BaseClient:
        """
        Get a usable GlideClient wrapper for the given client_id.

        On first borrow of a client_id, creates a thin wrapper pointing to the
        Rust-managed ClientAdapter. Subsequent borrows of the same client_id
        reuse the cached wrapper (zero allocation).
        """
        cached = self._client_cache.get(client_id)
        if cached is not None:
            return cached

        with self._cache_lock:
            # Double-check after acquiring lock
            cached = self._client_cache.get(client_id)
            if cached is not None:
                return cached

            # Get the native ClientAdapter pointer from the Rust pool
            adapter_ptr = self._lib.glide_pool_get_client_ptr(client_id)
            if adapter_ptr == 0:
                raise RuntimeError(
                    f"Pool client_id {client_id} has no associated ClientAdapter"
                )

            # Create a GlideClient shell pointing to the pooled adapter.
            cast_ptr = self._ffi.cast("void*", adapter_ptr)

            client = GlideClient.__new__(GlideClient)  # type: ignore[type-abstract]
            client._ffi = self._ffi
            client._lib = self._lib
            client._config = self._client_config
            client._is_closed = False
            client._pubsub_queue = []
            client._pubsub_lock = threading.Lock()
            client._pubsub_condition = threading.Condition(client._pubsub_lock)
            client._pubsub_callback_ref = None
            client._client_lock = threading.Lock()
            client._core_client = cast_ptr
            client._conn_req_bytes = self._conn_req_bytes

            self._client_cache[client_id] = client
            return client

    def metrics(self) -> dict:
        """Get pool metrics: idle, active, total counts.

        Zeros when the pool was destroyed.
        """
        m = self._lib.glide_pool_metrics(self._pool_id)
        return {"idle": m.idle, "active": m.active, "total": m.total}

    @property
    def idle_count(self) -> int:
        return self.metrics()["idle"]

    @property
    def active_count(self) -> int:
        return self.metrics()["active"]

    @property
    def total_count(self) -> int:
        return self.metrics()["total"]

    def close(self) -> None:
        """Destroy the pool. All idle clients are closed."""
        if not self._closed:
            self._closed = True
            self._lib.glide_pool_destroy(self._pool_id)
            self._client_cache.clear()

    def __enter__(self):
        return self

    def __exit__(self, *args):
        self.close()

    def __del__(self):
        # Do NOT call close() from __del__. The FFI glide_pool_destroy call
        # can race with active pubsub callbacks from the Rust side, causing
        # segfaults. Users must call close() explicitly or use context manager.
        pass

create(client_config, pool_config=None) classmethod

Create a pool and validate connectivity with a probe client.

Creates the pool infrastructure, then attempts to connect a single probe client using the same config. If the probe fails, the pool is destroyed and the actual connection error is propagated (not a timeout).

Parameters:

Name Type Description Default
client_config BaseClientConfiguration

Client configuration (standalone or cluster).

required
pool_config Optional[PoolConfig]

Optional pool sizing/timeout configuration.

None

Returns:

Type Description
ClientPool

A ready-to-use ClientPool instance.

Source code in doc-gen/valkey-glide/python/glide-sync/glide_sync/client_pool.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
@classmethod
def create(
    cls,
    client_config: BaseClientConfiguration,
    pool_config: Optional[PoolConfig] = None,
) -> "ClientPool":
    """Create a pool and validate connectivity with a probe client.

    Creates the pool infrastructure, then attempts to connect a single
    probe client using the same config. If the probe fails, the pool is
    destroyed and the actual connection error is propagated (not a timeout).

    Args:
        client_config: Client configuration (standalone or cluster).
        pool_config: Optional pool sizing/timeout configuration.

    Returns:
        A ready-to-use ClientPool instance.

    Raises:
        The same exception that GlideClient.create() would raise on
        connection failure.
    """
    pool = cls(client_config, pool_config)
    try:
        probe = GlideClient.create(client_config)
        probe.close()
    except Exception:
        pool.close()
        raise
    return pool

acquire(timeout=None)

Acquire a client_id from the Rust pool.

Blocks in Rust using a condvar until a client is available or timeout. Single FFI call — no polling loop.

Returns:

Type Description
int

client_id (positive integer) for use with borrow() or get_client().

Raises:

Type Description
TimeoutError

If no client available within timeout.

RuntimeError

If pool is closed or invalid.

Source code in doc-gen/valkey-glide/python/glide-sync/glide_sync/client_pool.py
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
def acquire(self, timeout: Optional[float] = None) -> int:
    """
    Acquire a client_id from the Rust pool.

    Blocks in Rust using a condvar until a client is available or timeout.
    Single FFI call — no polling loop.

    Returns:
        client_id (positive integer) for use with borrow() or get_client().

    Raises:
        TimeoutError: If no client available within timeout.
        RuntimeError: If pool is closed or invalid.
    """
    if self._closed:
        raise RuntimeError("Pool is closed")

    timeout = (
        timeout if timeout is not None else self._pool_config.acquire_timeout_s
    )
    timeout_ms = int(timeout * 1000)

    client_id = self._lib.glide_pool_acquire_blocking(self._pool_id, timeout_ms)

    if client_id >= 0:
        return client_id
    if client_id == -2:
        raise RuntimeError("Invalid pool_id — pool was destroyed")

    raise TimeoutError(
        f"Pool exhausted: could not acquire client within {timeout}s"
    )

release(client_id)

Release a borrowed client back to the pool.

Source code in doc-gen/valkey-glide/python/glide-sync/glide_sync/client_pool.py
227
228
229
def release(self, client_id: int) -> None:
    """Release a borrowed client back to the pool."""
    self._lib.glide_pool_release(self._pool_id, client_id)

borrow(timeout=None)

Returns a context manager that acquires a client from the Rust pool.

The returned client dispatches commands through the native ClientAdapter managed by the Rust pool. On exit, the client is released back to the pool.

Usage

with pool.borrow() as client: client.set("key", "value") result = client.get("key")

Source code in doc-gen/valkey-glide/python/glide-sync/glide_sync/client_pool.py
231
232
233
234
235
236
237
238
239
240
241
242
243
def borrow(self, timeout: Optional[float] = None):
    """
    Returns a context manager that acquires a client from the Rust pool.

    The returned client dispatches commands through the native ClientAdapter
    managed by the Rust pool. On exit, the client is released back to the pool.

    Usage:
        with pool.borrow() as client:
            client.set("key", "value")
            result = client.get("key")
    """
    return _BorrowContext(self, timeout)

metrics()

Get pool metrics: idle, active, total counts.

Zeros when the pool was destroyed.

Source code in doc-gen/valkey-glide/python/glide-sync/glide_sync/client_pool.py
289
290
291
292
293
294
295
def metrics(self) -> dict:
    """Get pool metrics: idle, active, total counts.

    Zeros when the pool was destroyed.
    """
    m = self._lib.glide_pool_metrics(self._pool_id)
    return {"idle": m.idle, "active": m.active, "total": m.total}

close()

Destroy the pool. All idle clients are closed.

Source code in doc-gen/valkey-glide/python/glide-sync/glide_sync/client_pool.py
309
310
311
312
313
314
def close(self) -> None:
    """Destroy the pool. All idle clients are closed."""
    if not self._closed:
        self._closed = True
        self._lib.glide_pool_destroy(self._pool_id)
        self._client_cache.clear()