Skip to content

glide.client_pool

Async client-instance pool — FFI-based, backed by shared Rust pool.

Same architecture as Python sync, Go, and Java pools. Uses the unified glide_pool_create with AsyncClient type. Responses route through the shared async pipe (same as normal GlideClient.create() clients).

PoolConfig dataclass

Configuration for the async client-instance pool.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/client_pool.py
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
@dataclass
class PoolConfig:
    """Configuration for the async client-instance pool."""

    max_size: int = 10
    min_idle: int = 1
    idle_timeout_ms: int = 300_000
    request_timeout_ms: int = 5_000
    acquire_timeout_s: float = 5.0
    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."""
    test_on_borrow: bool = False

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.

AsyncClientPool

FFI-based async client pool. Same Rust pool as all other languages.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/client_pool.py
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 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
327
328
329
330
331
332
class AsyncClientPool:
    """FFI-based async client pool. Same Rust pool as all other languages."""

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

    @classmethod
    async def create(
        cls,
        client_config: BaseClientConfiguration,
        pool_config: Optional[PoolConfig] = None,
    ) -> "AsyncClientPool":
        """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 AsyncClientPool instance.

        Raises:
            The same exception that GlideClient.create() / GlideClusterClient.create()
            would raise on connection failure.
        """
        pool = cls(client_config, pool_config)
        try:
            ClientClass = GlideClusterClient if pool._is_cluster else GlideClient
            probe = await ClientClass.create(client_config)
            await 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."
            )

        ffi_instance = _ASYNC_FFI
        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 = {}
        self._cache_lock = threading.Lock()
        self._is_cluster = isinstance(client_config, GlideClusterClientConfiguration)

        # Serialize connection request. Route through the shared helper so
        # pooled clients honour lib_name / client_info_tag exactly like direct
        # GlideClient.create() clients do (default "GlidePy", user-configured
        # lib_name, and the "(client_info_tag)" suffix).
        conn_req = _create_async_connection_request(client_config)
        self._conn_req_bytes = conn_req.SerializeToString()

        # Initialize the shared async pipe BEFORE creating pool clients.
        # This ensures ASYNC_PIPE is set so pooled AsyncClient adapters
        # write responses to the pipe (not the callback path).
        import glide.glide_client as _gc

        with _async_pipe_lock:
            _gc._detect_fork_and_reset()
            current_pid = os.getpid()

            if _gc._async_pipe_read_fd < 0:
                try:
                    r, w = os.pipe()
                    os.set_blocking(r, False)
                    if (
                        _gc._async_pipe_init_pid > 0
                        and current_pid != _gc._async_pipe_init_pid
                    ):
                        self._lib.reinit_async_pipe(w)
                    else:
                        self._lib.init_async_pipe(w)
                    _gc._async_pipe_read_fd = r
                    _gc._async_pipe_write_fd = w
                    _gc._async_pipe_init_pid = current_pid
                except OSError:
                    pass

        # Create pool with AsyncClient type (no-op callbacks — pipe handles responses)
        client_type = self._ffi.new("ClientType*")
        client_type._type = 0  # AsyncClient
        client_type.async_client.success_callback = self._lib.noop_success_callback
        client_type.async_client.failure_callback = self._lib.noop_failure_callback
        client_type.async_client.allow_stack_response = False

        buf = self._ffi.from_buffer(self._conn_req_bytes)
        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._ffi.cast("const uint8_t*", buf),
            len(self._conn_req_bytes),
            client_type,
        )
        if pool_id < 0:
            raise RuntimeError(f"Failed to create pool: error code {pool_id}")
        self._pool_id = pool_id

    async def acquire(self, timeout: Optional[float] = None) -> int:
        """Acquire a client_id using non-blocking try_acquire with async backoff.

        Uses glide_pool_try_acquire (non-blocking) instead of
        glide_pool_acquire_blocking to avoid blocking thread pool threads.
        Blocking threads prevents the event loop from draining the async pipe,
        which deadlocks the pool's release state-reset (DISCARD + SELECT).
        """
        if self._closed:
            raise RuntimeError("Pool is closed")
        timeout = (
            timeout if timeout is not None else self._pool_config.acquire_timeout_s
        )

        import time

        deadline = time.monotonic() + timeout
        backoff = 0.005  # Start at 5ms

        while True:
            client_id = self._lib.glide_pool_try_acquire(self._pool_id)
            if client_id >= 0:
                return client_id
            if client_id == -2:
                raise RuntimeError("Invalid pool_id — pool was destroyed")

            remaining = deadline - time.monotonic()
            if remaining <= 0:
                raise TimeoutError(
                    f"Pool exhausted: could not acquire client within {timeout}s"
                )

            # Yield to event loop — allows pipe reader to process release responses
            await asyncio.sleep(min(backoff, remaining))
            backoff = min(backoff * 2, 0.05)  # Cap at 50ms

    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):
        """Async context manager."""
        return _AsyncBorrowContext(self, timeout)

    def _get_or_create_client(self, client_id: int) -> BaseClient:
        """Get/create a client wrapper with pipe registration."""
        cached = self._client_cache.get(client_id)
        if cached is not None:
            return cached

        with self._cache_lock:
            cached = self._client_cache.get(client_id)
            if cached is not None:
                return cached

            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"
                )

            ClientClass = GlideClusterClient if self._is_cluster else GlideClient
            client = object.__new__(ClientClass)
            client.config = self._client_config
            client._is_closed = False
            client._ffi = self._ffi
            client._lib = self._lib
            client._pending_futures = {}
            client._pending_push_notifications = []
            client._pubsub_futures = []
            client._pubsub_lock = threading.Lock()
            client._pubsub_callback_ref = None
            client._callback_id_gen = __import__("itertools").count(1)
            client._lock = threading.Lock()
            client._is_asyncio = True
            client._core_client = self._ffi.cast("void*", adapter_ptr)
            client._conn_req_bytes = self._conn_req_bytes
            client._create_pid = os.getpid()

            # The pool created this client with pipe_client_id = client_id
            # (set in create_client_internal via the pre-assigned ID).
            # Register so the pipe reader routes responses here.
            client._pipe_client_id = client_id
            try:
                client._loop = asyncio.get_running_loop()
            except RuntimeError:
                client._loop = None

            _client_registry[client_id] = client
            client._setup_pipe()

            self._client_cache[client_id] = client
            return client

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

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

    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):
        if not self._closed:
            self._closed = True
            for cid in list(self._client_cache.keys()):
                _client_registry.pop(cid, None)
            self._lib.glide_pool_destroy(self._pool_id)
            self._client_cache.clear()

    async def aclose(self):
        self.close()

    async def __aenter__(self):
        return self

    async def __aexit__(self, *_):
        self.close()
        return False

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

create(client_config, pool_config=None) async 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
AsyncClientPool

A ready-to-use AsyncClientPool instance.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/client_pool.py
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
@classmethod
async def create(
    cls,
    client_config: BaseClientConfiguration,
    pool_config: Optional[PoolConfig] = None,
) -> "AsyncClientPool":
    """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 AsyncClientPool instance.

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

acquire(timeout=None) async

Acquire a client_id using non-blocking try_acquire with async backoff.

Uses glide_pool_try_acquire (non-blocking) instead of glide_pool_acquire_blocking to avoid blocking thread pool threads. Blocking threads prevents the event loop from draining the async pipe, which deadlocks the pool's release state-reset (DISCARD + SELECT).

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/client_pool.py
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
async def acquire(self, timeout: Optional[float] = None) -> int:
    """Acquire a client_id using non-blocking try_acquire with async backoff.

    Uses glide_pool_try_acquire (non-blocking) instead of
    glide_pool_acquire_blocking to avoid blocking thread pool threads.
    Blocking threads prevents the event loop from draining the async pipe,
    which deadlocks the pool's release state-reset (DISCARD + SELECT).
    """
    if self._closed:
        raise RuntimeError("Pool is closed")
    timeout = (
        timeout if timeout is not None else self._pool_config.acquire_timeout_s
    )

    import time

    deadline = time.monotonic() + timeout
    backoff = 0.005  # Start at 5ms

    while True:
        client_id = self._lib.glide_pool_try_acquire(self._pool_id)
        if client_id >= 0:
            return client_id
        if client_id == -2:
            raise RuntimeError("Invalid pool_id — pool was destroyed")

        remaining = deadline - time.monotonic()
        if remaining <= 0:
            raise TimeoutError(
                f"Pool exhausted: could not acquire client within {timeout}s"
            )

        # Yield to event loop — allows pipe reader to process release responses
        await asyncio.sleep(min(backoff, remaining))
        backoff = min(backoff * 2, 0.05)  # Cap at 50ms

release(client_id)

Release a borrowed client back to the pool.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/client_pool.py
224
225
226
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)

Async context manager.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/client_pool.py
228
229
230
def borrow(self, timeout: Optional[float] = None):
    """Async context manager."""
    return _AsyncBorrowContext(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-async/python/glide/client_pool.py
290
291
292
293
294
295
296
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}