Skip to content

glide.isolated_scope

Async Isolated Execution Scope for the GLIDE async client.

Provides a dedicated connection for operations requiring per-connection state: WATCH/MULTI/EXEC, CLIENT TRACKING, blocking commands. Commands bypass the multiplexer and execute on a single TCP connection.

Usage

from glide import GlideClient from glide.config import GlideClientConfiguration, NodeAddress

client = await GlideClient.create(GlideClientConfiguration([NodeAddress("localhost", 6379)]))

async with client.scoped_connection() as scope: await scope.watch("counter") val = await scope.get("counter") await scope.multi() await scope.set("counter", str(int(val) + 1)) result = await scope.exec()

AsyncIsolatedScope

Async wrapper around a dedicated scoped connection.

Commands are dispatched to a thread pool executor (since the underlying FFI call blocks on Tokio), keeping the asyncio event loop free.

Thread Safety: A single AsyncIsolatedScope should only be used from one coroutine at a time. Multiple coroutines should each acquire their own scope.

Use as an async context manager

async with client.scoped_connection() as scope: await scope.watch("key") ...

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 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
class AsyncIsolatedScope:
    """
    Async wrapper around a dedicated scoped connection.

    Commands are dispatched to a thread pool executor (since the underlying
    FFI call blocks on Tokio), keeping the asyncio event loop free.

    Thread Safety: A single AsyncIsolatedScope should only be used from one
    coroutine at a time. Multiple coroutines should each acquire their own scope.

    Use as an async context manager:
        async with client.scoped_connection() as scope:
            await scope.watch("key")
            ...
    """

    __slots__ = (
        "_scope_id",
        "_client_id",
        "_ffi",
        "_lib",
        "_released",
        "_response_parser",
        "_executor",
    )

    def __init__(
        self,
        scope_id: int,
        client_id: int,
        ffi_instance: _GlideFFI,
        response_parser,
        executor=None,
    ):
        self._scope_id = scope_id
        self._client_id = client_id
        self._ffi = ffi_instance.ffi
        self._lib = ffi_instance.lib
        self._released = False
        self._response_parser = response_parser
        self._executor = executor  # ThreadPoolExecutor or None (uses default)

    @property
    def scope_id(self) -> int:
        if self._released:
            raise RuntimeError("Scope already released")
        return self._scope_id

    @property
    def is_released(self) -> bool:
        return self._released

    # ═══════════════════════════════════════════════════════════════════════════
    # COMMANDS (all async)
    # ═══════════════════════════════════════════════════════════════════════════

    async def watch(self, *keys: str) -> Optional[str]:
        """WATCH one or more keys for optimistic locking."""
        return await self._cmd("WATCH", *keys)

    async def unwatch(self) -> Optional[str]:
        """Discard all watched keys."""
        return await self._cmd("UNWATCH")

    async def multi(self) -> Optional[str]:
        """Begin a transaction block."""
        return await self._cmd("MULTI")

    async def exec(self) -> Optional[str]:
        """Execute the transaction (returns None if WATCH detected a conflict)."""
        return await self._cmd("EXEC")

    async def discard(self) -> Optional[str]:
        """Discard the transaction."""
        return await self._cmd("DISCARD")

    async def get(self, key: str) -> Optional[str]:
        """GET a key value."""
        return await self._cmd("GET", key)

    async def set(self, key: str, value: str) -> Optional[str]:
        """SET a key to a value."""
        return await self._cmd("SET", key, value)

    async def incr(self, key: str) -> Optional[str]:
        """Increment a key's integer value by 1."""
        return await self._cmd("INCR", key)

    async def ping(self, message: Optional[str] = None) -> Optional[str]:
        """PING the server."""
        if message:
            return await self._cmd("PING", message)
        return await self._cmd("PING")

    async def select(self, db: int) -> Optional[str]:
        """SELECT a database by index."""
        return await self._cmd("SELECT", str(db))

    async def execute_command(self, command: str, *args: str) -> Optional[str]:
        """Execute an arbitrary command on this scope."""
        return await self._cmd(command, *args)

    # ═══════════════════════════════════════════════════════════════════════════
    # INTERNAL
    # ═══════════════════════════════════════════════════════════════════════════

    async def _cmd(self, command: str, *args: str) -> Optional[str]:
        """Serialize and execute a command on the scoped connection (async)."""
        if self._released:
            raise RuntimeError("Scope already released")

        # Serialize in wire format
        cmd_bytes = command.encode("utf-8")
        parts = [
            struct.pack("<I", len(cmd_bytes)),
            cmd_bytes,
            struct.pack("<I", len(args)),
        ]
        for arg in args:
            arg_bytes = arg.encode("utf-8")
            parts.append(struct.pack("<I", len(arg_bytes)))
            parts.append(arg_bytes)
        payload = b"".join(parts)

        # Execute in thread pool to avoid blocking the event loop
        loop = asyncio.get_running_loop()
        result_ptr = await loop.run_in_executor(
            self._executor, self._execute_sync, payload
        )

        if result_ptr == self._ffi.NULL:
            raise RuntimeError(f"Scope execute failed: invalid scope {self._scope_id}")

        try:
            return self._parse_result(result_ptr)
        finally:
            self._lib.free_command_result(result_ptr)

    def _execute_sync(self, payload: bytes):
        """Synchronous FFI call (runs in executor thread)."""
        buf = self._ffi.from_buffer(payload)
        return self._lib.glide_scope_execute(
            self._scope_id,
            self._ffi.cast("const uint8_t*", buf),
            len(payload),
        )

    def _parse_result(self, result_ptr) -> Optional[str]:
        """Parse a CommandResult pointer into a Python value."""
        result = result_ptr

        if result.command_error != self._ffi.NULL:
            err = result.command_error
            msg = self._ffi.string(err.command_error_message).decode("utf-8")
            raise RuntimeError(f"Scope command error: {msg}")

        if result.response == self._ffi.NULL:
            return None

        return self._response_parser(result.response)

    # ═══════════════════════════════════════════════════════════════════════════
    # ASYNC CONTEXT MANAGER
    # ═══════════════════════════════════════════════════════════════════════════

    async def close(self):
        """Release the scope back to the pool."""
        if not self._released:
            self._released = True
            self._lib.glide_scope_release(self._scope_id, self._client_id)

    async def __aenter__(self):
        return self

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        await self.close()
        return False

    def __del__(self):
        """Safety net — release on GC if not explicitly closed."""
        if not self._released:
            try:
                self._released = True
                self._lib.glide_scope_release(self._scope_id, self._client_id)
            except Exception:
                pass

watch(*keys) async

WATCH one or more keys for optimistic locking.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
87
88
89
async def watch(self, *keys: str) -> Optional[str]:
    """WATCH one or more keys for optimistic locking."""
    return await self._cmd("WATCH", *keys)

unwatch() async

Discard all watched keys.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
91
92
93
async def unwatch(self) -> Optional[str]:
    """Discard all watched keys."""
    return await self._cmd("UNWATCH")

multi() async

Begin a transaction block.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
95
96
97
async def multi(self) -> Optional[str]:
    """Begin a transaction block."""
    return await self._cmd("MULTI")

exec() async

Execute the transaction (returns None if WATCH detected a conflict).

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
 99
100
101
async def exec(self) -> Optional[str]:
    """Execute the transaction (returns None if WATCH detected a conflict)."""
    return await self._cmd("EXEC")

discard() async

Discard the transaction.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
103
104
105
async def discard(self) -> Optional[str]:
    """Discard the transaction."""
    return await self._cmd("DISCARD")

get(key) async

GET a key value.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
107
108
109
async def get(self, key: str) -> Optional[str]:
    """GET a key value."""
    return await self._cmd("GET", key)

set(key, value) async

SET a key to a value.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
111
112
113
async def set(self, key: str, value: str) -> Optional[str]:
    """SET a key to a value."""
    return await self._cmd("SET", key, value)

incr(key) async

Increment a key's integer value by 1.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
115
116
117
async def incr(self, key: str) -> Optional[str]:
    """Increment a key's integer value by 1."""
    return await self._cmd("INCR", key)

ping(message=None) async

PING the server.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
119
120
121
122
123
async def ping(self, message: Optional[str] = None) -> Optional[str]:
    """PING the server."""
    if message:
        return await self._cmd("PING", message)
    return await self._cmd("PING")

select(db) async

SELECT a database by index.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
125
126
127
async def select(self, db: int) -> Optional[str]:
    """SELECT a database by index."""
    return await self._cmd("SELECT", str(db))

execute_command(command, *args) async

Execute an arbitrary command on this scope.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
129
130
131
async def execute_command(self, command: str, *args: str) -> Optional[str]:
    """Execute an arbitrary command on this scope."""
    return await self._cmd(command, *args)

close() async

Release the scope back to the pool.

Source code in doc-gen/valkey-glide/python/glide-async/python/glide/isolated_scope.py
196
197
198
199
200
async def close(self):
    """Release the scope back to the pool."""
    if not self._released:
        self._released = True
        self._lib.glide_scope_release(self._scope_id, self._client_id)