|
11 | 11 |
|
12 | 12 | libtmux provides two complementary async patterns: |
13 | 13 |
|
14 | | -**Pattern A**: `.acmd()` methods on Server/Session/Window/Pane objects: |
| 14 | +**Pattern A**: `.acmd()` methods on Server/Session/Window/Pane objects:: |
15 | 15 |
|
16 | | ->>> import asyncio |
17 | | ->>> async def example(): |
18 | | -... server = libtmux.Server() |
19 | | -... result = await server.acmd('list-sessions') |
20 | | -... return result.stdout |
21 | | ->>> asyncio.run(example()) # doctest: +SKIP |
22 | | -[...] |
| 16 | + import asyncio |
| 17 | + import libtmux |
23 | 18 |
|
24 | | -**Pattern B**: Direct async execution with `tmux_cmd_async()`: |
| 19 | + async def example(): |
| 20 | + server = libtmux.Server() |
| 21 | + result = await server.acmd('list-sessions') |
| 22 | + return result.stdout |
25 | 23 |
|
26 | | ->>> import asyncio |
27 | | ->>> async def example(): |
28 | | -... result = await tmux_cmd_async('list-sessions') |
29 | | -... return result.stdout |
30 | | ->>> asyncio.run(example()) # doctest: +SKIP |
31 | | -[...] |
| 24 | + asyncio.run(example()) |
| 25 | + # Returns: [...] |
| 26 | +
|
| 27 | +**Pattern B**: Direct async execution with `tmux_cmd_async()`:: |
| 28 | +
|
| 29 | + import asyncio |
| 30 | + from libtmux.common_async import tmux_cmd_async |
| 31 | +
|
| 32 | + async def example(): |
| 33 | + result = await tmux_cmd_async('list-sessions') |
| 34 | + return result.stdout |
| 35 | +
|
| 36 | + asyncio.run(example()) |
| 37 | + # Returns: [...] |
32 | 38 |
|
33 | 39 | Both patterns preserve 100% of the synchronous API. See the quickstart guide |
34 | 40 | for more information: https://libtmux.git-pull.com/quickstart_async.html |
35 | 41 |
|
36 | 42 | Performance |
37 | 43 | ----------- |
38 | 44 |
|
39 | | -Async provides significant performance benefits for concurrent operations: |
| 45 | +Async provides significant performance benefits for concurrent operations:: |
| 46 | +
|
| 47 | + import asyncio |
| 48 | + from libtmux.common_async import tmux_cmd_async |
| 49 | +
|
| 50 | + async def concurrent(): |
| 51 | + # 2-3x faster than sequential execution |
| 52 | + results = await asyncio.gather( |
| 53 | + tmux_cmd_async('list-sessions'), |
| 54 | + tmux_cmd_async('list-windows'), |
| 55 | + tmux_cmd_async('list-panes'), |
| 56 | + ) |
| 57 | + return results |
40 | 58 |
|
41 | | ->>> import asyncio |
42 | | ->>> async def concurrent(): |
43 | | -... # 2-3x faster than sequential execution |
44 | | -... results = await asyncio.gather( |
45 | | -... tmux_cmd_async('list-sessions'), |
46 | | -... tmux_cmd_async('list-windows'), |
47 | | -... tmux_cmd_async('list-panes'), |
48 | | -... ) |
49 | | ->>> asyncio.run(concurrent()) # doctest: +SKIP |
| 59 | + asyncio.run(concurrent()) |
50 | 60 |
|
51 | 61 | See Also |
52 | 62 | -------- |
@@ -261,29 +271,37 @@ class tmux_cmd_async: |
261 | 271 | >>> asyncio.run(main()) |
262 | 272 | tmux command returned 2 |
263 | 273 |
|
264 | | - **Concurrent Operations**: Execute multiple commands in parallel for 2-3x speedup: |
265 | | -
|
266 | | - >>> async def concurrent_example(): |
267 | | - ... # All commands run concurrently |
268 | | - ... results = await asyncio.gather( |
269 | | - ... tmux_cmd_async('list-sessions'), |
270 | | - ... tmux_cmd_async('list-windows'), |
271 | | - ... tmux_cmd_async('list-panes'), |
272 | | - ... ) |
273 | | - ... return [len(r.stdout) for r in results] |
274 | | - >>> asyncio.run(concurrent_example()) # doctest: +SKIP |
275 | | - [...] |
276 | | -
|
277 | | - **Error Handling**: Check return codes and stderr: |
278 | | -
|
279 | | - >>> async def check_session(): |
280 | | - ... result = await tmux_cmd_async('has-session', '-t', 'my_session') |
281 | | - ... if result.returncode != 0: |
282 | | - ... print("Session doesn't exist") |
283 | | - ... return False |
284 | | - ... return True |
285 | | - >>> asyncio.run(check_session()) # doctest: +SKIP |
286 | | - False |
| 274 | + **Concurrent Operations**: Execute multiple commands in parallel for 2-3x speedup:: |
| 275 | +
|
| 276 | + import asyncio |
| 277 | + from libtmux.common_async import tmux_cmd_async |
| 278 | +
|
| 279 | + async def concurrent_example(): |
| 280 | + # All commands run concurrently |
| 281 | + results = await asyncio.gather( |
| 282 | + tmux_cmd_async('list-sessions'), |
| 283 | + tmux_cmd_async('list-windows'), |
| 284 | + tmux_cmd_async('list-panes'), |
| 285 | + ) |
| 286 | + return [len(r.stdout) for r in results] |
| 287 | +
|
| 288 | + asyncio.run(concurrent_example()) |
| 289 | + # Returns: [...] |
| 290 | +
|
| 291 | + **Error Handling**: Check return codes and stderr:: |
| 292 | +
|
| 293 | + import asyncio |
| 294 | + from libtmux.common_async import tmux_cmd_async |
| 295 | +
|
| 296 | + async def check_session(): |
| 297 | + result = await tmux_cmd_async('has-session', '-t', 'my_session') |
| 298 | + if result.returncode != 0: |
| 299 | + print("Session doesn't exist") |
| 300 | + return False |
| 301 | + return True |
| 302 | +
|
| 303 | + asyncio.run(check_session()) |
| 304 | + # Returns: False |
287 | 305 |
|
288 | 306 | Equivalent to: |
289 | 307 |
|
@@ -407,25 +425,32 @@ async def get_version() -> LooseVersion: |
407 | 425 |
|
408 | 426 | Examples |
409 | 427 | -------- |
410 | | - Get tmux version asynchronously: |
| 428 | + Get tmux version asynchronously:: |
411 | 429 |
|
412 | | - >>> import asyncio |
413 | | - >>> async def check_version(): |
414 | | - ... version = await get_version() |
415 | | - ... print(f"tmux version: {version}") |
416 | | - >>> asyncio.run(check_version()) # doctest: +SKIP |
417 | | - tmux version: ... |
418 | | -
|
419 | | - Use in concurrent operations: |
420 | | -
|
421 | | - >>> async def check_all(): |
422 | | - ... version, sessions = await asyncio.gather( |
423 | | - ... get_version(), |
424 | | - ... tmux_cmd_async('list-sessions'), |
425 | | - ... ) |
426 | | - ... return version, len(sessions.stdout) |
427 | | - >>> asyncio.run(check_all()) # doctest: +SKIP |
428 | | - (..., ...) |
| 430 | + import asyncio |
| 431 | + from libtmux.common_async import get_version |
| 432 | +
|
| 433 | + async def check_version(): |
| 434 | + version = await get_version() |
| 435 | + print(f"tmux version: {version}") |
| 436 | +
|
| 437 | + asyncio.run(check_version()) |
| 438 | + # Prints: tmux version: 3.4 |
| 439 | +
|
| 440 | + Use in concurrent operations:: |
| 441 | +
|
| 442 | + import asyncio |
| 443 | + from libtmux.common_async import get_version, tmux_cmd_async |
| 444 | +
|
| 445 | + async def check_all(): |
| 446 | + version, sessions = await asyncio.gather( |
| 447 | + get_version(), |
| 448 | + tmux_cmd_async('list-sessions'), |
| 449 | + ) |
| 450 | + return version, len(sessions.stdout) |
| 451 | +
|
| 452 | + asyncio.run(check_all()) |
| 453 | + # Returns: (LooseVersion('3.4'), 2) |
429 | 454 |
|
430 | 455 | Returns |
431 | 456 | ------- |
|
0 commit comments