async-kernel 0.21.0__tar.gz → 0.22.1__tar.gz

{async_kernel-0.21.0 → async_kernel-0.22.1}/.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
 
       - name: Type checking with basedpyright
         run: |
@@ -45,7 +45,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
           python-version: ${{ matrix.python-version }}
@@ -87,7 +87,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
           python-version: "3.13"
@@ -116,7 +116,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
 

{async_kernel-0.21.0 → async_kernel-0.22.1}/.github/workflows/new_release.yml

@@ -31,7 +31,7 @@ jobs:
           fetch-depth: 0
           ref: main
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
 

{async_kernel-0.21.0 → async_kernel-0.22.1}/.github/workflows/pre-commit.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v7
         with:
           python-version: 3.x
       - uses: pre-commit/action@v3.0.1

{async_kernel-0.21.0 → async_kernel-0.22.1}/.github/workflows/publish-docs.yml

@@ -27,7 +27,7 @@ jobs:
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
 

{async_kernel-0.21.0 → async_kernel-0.22.1}/.github/workflows/publish-to-pypi.yml

@@ -31,7 +31,7 @@ jobs:
           # Fetch full history for setuptools-scm
           fetch-depth: 0
           ref: main
-      - uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version-file: "pyproject.toml"
 

{async_kernel-0.21.0 → async_kernel-0.22.1}/.pre-commit-config.yaml

@@ -28,15 +28,15 @@ repos:
       - id: check-json5
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.37.4
+    rev: 0.38.0
     hooks:
       - id: check-github-workflows
 
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.9.5
+    rev: v3.9.6
     hooks:
       - id: prettier
-        types_or: [yaml, html, json]
+        types_or: [yaml, html, json, toml]
       - id: prettier
         types_or: [markdown]
         args: ["--tab-width", "4"]
@@ -59,7 +59,7 @@ repos:
       - id: python-use-type-annotations
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.22
+    rev: v0.16.3
     hooks:
       - id: ruff-check
         types_or: [python, jupyter]
@@ -68,7 +68,7 @@ repos:
         types_or: [python, jupyter]
 
   - repo: https://github.com/scientific-python/cookie
-    rev: 2026.06.18
+    rev: 2026.08.14
     hooks:
       - id: sp-repo-review
         additional_dependencies: ["repo-review[cli]"]

{async_kernel-0.21.0 → async_kernel-0.22.1}/.vscode/settings.json

@@ -18,5 +18,8 @@
     "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
   ],
   "spellright.language": ["en"],
-  "spellright.documentTypes": ["markdown", "plaintext"]
+  "spellright.documentTypes": ["markdown", "plaintext"],
+  "[toml]": {
+    "editor.defaultFormatter": "tamasfe.even-better-toml"
+  }
 }

{async_kernel-0.21.0 → async_kernel-0.22.1}/CHANGELOG.md

@@ -5,7 +5,97 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.21.0] - 2026-07-18
+## [0.22.1] - 2026-08-18
+
+### <!-- 0 --> 🏗️ Breaking changes
+
+- Update zmq_poll docstrings. [#567](https://github.com/fleming79/async-kernel/pull/567)
+
+### <!-- 5 --> 📝 Documentation
+
+- ZMQPoll typing and doc fixes. [#568](https://github.com/fleming79/async-kernel/pull/568)
+
+### <!-- 6 --> 🌀 Miscellaneous
+
+- Refactor create_interface_messge_callback_handler to only use one connection [#569](https://github.com/fleming79/async-kernel/pull/569)
+
+## [0.22.0] - 2026-08-17
+
+### <!-- 0 --> 🏗️ Breaking changes
+
+- Major interface refactoring, new features and capabilities [#538](https://github.com/fleming79/async-kernel/pull/538)
+
+### <!-- 1 --> 🚀 Features
+
+- Add ShieldedTask. [#553](https://github.com/fleming79/async-kernel/pull/553)
+
+- Change caller async context manager to be first in last out, intermediate contexts are not managed. [#549](https://github.com/fleming79/async-kernel/pull/549)
+
+- Add ProtectedPending to prevent accidental propagation of cancellation of a cancelled waiter. [#546](https://github.com/fleming79/async-kernel/pull/546)
+
+- Add cancellation support in ZMQPoll. [#541](https://github.com/fleming79/async-kernel/pull/541)
+
+- Rename Poll to ZMQPoll and add ZMQPollSocket [#539](https://github.com/fleming79/async-kernel/pull/539)
+
+- Caller async context management changes [#537](https://github.com/fleming79/async-kernel/pull/537)
+
+- Split BaseInterface into BaseMessageApplication [#536](https://github.com/fleming79/async-kernel/pull/536)
+
+### <!-- 2 --> 🐛 Fixes
+
+- Fix heartbeat [#532](https://github.com/fleming79/async-kernel/pull/532)
+
+### <!-- 5 --> 📝 Documentation
+
+- Use Ruff lint pydocstyle [#531](https://github.com/fleming79/async-kernel/pull/531)
+
+### <!-- 6 --> 🌀 Miscellaneous
+
+- Prepare for release v0.22.0 [#566](https://github.com/fleming79/async-kernel/pull/566)
+
+- Bump uv from 0.11.32 to 0.12.4 [#562](https://github.com/fleming79/async-kernel/pull/562)
+
+- Bump astral-sh/setup-uv from 9.0.0 to 10.0.1 in the actions group [#559](https://github.com/fleming79/async-kernel/pull/559)
+
+- Pre-commit autoupdate and update uv.lock. [#565](https://github.com/fleming79/async-kernel/pull/565)
+
+- Fix pyright type hinting of NoValue. [#564](https://github.com/fleming79/async-kernel/pull/564)
+
+- Rename ShieldedTask to StartStopTask. [#557](https://github.com/fleming79/async-kernel/pull/557)
+
+- More features fro ShieldedTask. [#556](https://github.com/fleming79/async-kernel/pull/556)
+
+- Compatibility fix with ipython. [#555](https://github.com/fleming79/async-kernel/pull/555)
+
+- Change ShieldedTask to use set_task_function to set the function and caller to avoid clashing when used as a mixin. [#554](https://github.com/fleming79/async-kernel/pull/554)
+
+- Refactor Pending._set_done. [#552](https://github.com/fleming79/async-kernel/pull/552)
+
+- Refactor Pending._set_done. [#551](https://github.com/fleming79/async-kernel/pull/551)
+
+- Improve Caller auto shutdown support [#550](https://github.com/fleming79/async-kernel/pull/550)
+
+- Make Caller a bit safer for shutdown where it's context is held inside a pending task. [#548](https://github.com/fleming79/async-kernel/pull/548)
+
+- Improve caller shutdown management and tests [#547](https://github.com/fleming79/async-kernel/pull/547)
+
+- Bump astral-sh/setup-uv from 8.3.2 to 9.0.0 in the actions group [#544](https://github.com/fleming79/async-kernel/pull/544)
+
+- ZMQPoll support multiple context entry and re-entry. [#545](https://github.com/fleming79/async-kernel/pull/545)
+
+- Improve kernel shutdown. [#543](https://github.com/fleming79/async-kernel/pull/543)
+
+- More Messge types and general fixes. [#542](https://github.com/fleming79/async-kernel/pull/542)
+
+- Improve ZMQPollSocket autoclose. [#540](https://github.com/fleming79/async-kernel/pull/540)
+
+- Fix the ident of input request messages. [#535](https://github.com/fleming79/async-kernel/pull/535)
+
+- Bump the actions group with 2 updates [#533](https://github.com/fleming79/async-kernel/pull/533)
+
+- Improve uv magic. [#534](https://github.com/fleming79/async-kernel/pull/534)
+
+## [0.21.0] - 2026-07-19
 
 ### <!-- 1 --> 🚀 Features
 
@@ -17,6 +107,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### <!-- 6 --> 🌀 Miscellaneous
 
+- Prepare for release v0.21.0 [#530](https://github.com/fleming79/async-kernel/pull/530)
+
 - Poll maintenance [#529](https://github.com/fleming79/async-kernel/pull/529)
 
 - Add threadsafe option to Poll.socket [#528](https://github.com/fleming79/async-kernel/pull/528)
@@ -1453,6 +1545,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Bump the actions group across 1 directory with 2 updates [#3](https://github.com/fleming79/async-kernel/pull/3)
 
+[0.22.1]: https://github.com/fleming79/async-kernel/compare/v0.22.0..v0.22.1
+[0.22.0]: https://github.com/fleming79/async-kernel/compare/v0.21.0..v0.22.0
 [0.21.0]: https://github.com/fleming79/async-kernel/compare/v0.20.2..v0.21.0
 [0.20.2]: https://github.com/fleming79/async-kernel/compare/v0.20.1..v0.20.2
 [0.20.1]: https://github.com/fleming79/async-kernel/compare/v0.20.0..v0.20.1

{async_kernel-0.21.0 → async_kernel-0.22.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: async-kernel
-Version: 0.21.0
+Version: 0.22.1
 Summary: A concurrent python kernel for Jupyter supporting AnyIO, AsyncIO and Trio.
 Project-URL: Homepage, https://fleming79.github.io/async-kernel
 Project-URL: Documentation, https://fleming79.github.io/async-kernel
@@ -36,7 +36,7 @@ Requires-Python: >=3.11
 Requires-Dist: aiologic>=0.17.0
 Requires-Dist: anyio>=4.12
 Requires-Dist: comm>=0.2
-Requires-Dist: ipython>=9.0
+Requires-Dist: ipython>=9.16.1
 Requires-Dist: jupyter-client>=8.9.1; sys_platform != 'emscripten'
 Requires-Dist: jupyter-core>=5.9.1
 Requires-Dist: matplotlib-inline>0.1
@@ -62,22 +62,24 @@ Description-Content-Type: text/markdown
 
 ![logo-svg](https://github.com/user-attachments/assets/6781ec08-94e9-4640-b8f9-bb07a08e9587)
 
-async-kernel is a Python kernel for [Jupyter](https://docs.jupyter.org/en/latest/projects/kernels.html#kernels-programming-languages)
-that provides concurrent message handling via an asynchronous backend (asyncio or trio).
+async-kernel provides Python [Jupyter](https://docs.jupyter.org/en/latest/projects/kernels.html#kernels-programming-languages) kernels and clients
+compatible with CPython (Jupyter & VS code) and Pyodide (Jupyterlite).
 
-The kernel provides two external interfaces:
+The kernel interface supports multiple connections including:
 
-1. Direct ZMQ socket messaging via a configuration file and kernel spec - (Jupyter, VS Code, etc).
-2. An experimental callback style interface (Jupyterlite).
+1. Messaging via ZMQ sockets (Jupyter, VS Code, etc).
+2. Same-process local client enabling (Jupyterlite) and user access.
 
 ## Highlights
 
+- Built using [aiologic](https://aiologic.readthedocs.io/latest/) thread-safe synchronisation primitives.
+- The [`Caller`](https://fleming79.github.io/async-kernel/latest/reference/caller/#async_kernel.caller.Caller)
+  class provides a powerful but simple interface for cross-thread code execution in asyncio and trio
+  backends, with guest event loop support built in.
+- A zmq poll event loop for thread-safe zmq sockets.
 - [IPython shell](https://ipython.readthedocs.io/en/stable/overview.html#enhanced-interactive-python-shell)
     - top-level await ('asyncio' or 'trio' backend) in cells
     - async magic function support in cells
-- [anyio](https://pypi.org/project/anyio/) compatible asynchronous backend ([`asyncio`](https://docs.python.org/3/library/asyncio.html) (default) or [`trio`](https://pypi.org/project/trio/))
-- [aiologic](https://aiologic.readthedocs.io/latest/) thread-safe synchronisation primitives
-- [Backend agnostic multi-thread / multi-event loop management](https://fleming79.github.io/async-kernel/latest/reference/caller/#async_kernel.caller.Caller)
 - Per-subshell user_ns
 - GUI event loops [^1]
     - [x] inline
@@ -88,6 +90,8 @@ The kernel provides two external interfaces:
   [Jupyterlite](https://github.com/jupyterlite/jupyterlite) (try it online [here](https://fleming79.github.io/echo-kernel/) 👈)
     - `%pip install` magic (using micropip)
 - [Debugger client](https://jupyterlab.readthedocs.io/en/latest/user/debugger.html#debugger)
+- Local client.
+- ZMQ client.
 
 [^1]:
     A gui (_host_) enabled kernel interface starts a gui's mainloop (host) which starts
@@ -100,55 +104,6 @@ The kernel provides two external interfaces:
 
 [^3]: trio's [start_guest_run](https://trio.readthedocs.io/en/stable/reference-lowlevel.html#trio.lowlevel.start_guest_run).
 
-### Avoid deadlocks
-
-The standard (synchronous) kernel implementation processes messages sequentially irrespective
-of the message type. The problem being that long running execute requests make the kernel non-responsive.
-
-Another problem exists when an asynchronous execute request awaits a result that is delivered
-via a kernel message - this will cause a deadlock because the message will be stuck in the queue behind
-the _blocking_ execute request[^5].
-
-async-kernel handles messages according to the channel and message type. So widget com message
-will get processed in a separate queue to an execute request. Further detail is given in the [concurrency notebook](https://fleming79.github.io/async-kernel/latest/notebooks/concurrency/), a Jupyterlite version is available [here](https://fleming79.github.io/echo-kernel/).
-
-#### Example
-
-Make a blocking call in a Jupyter lab notebook or console.
-
-```python
-# Make the shell's thread busy
-import time
-
-time.sleep(1e6)
-```
-
-While the above is _blocking_ (the kernel is _busy_).
-
-```python
-dir()  # try code completion (tab) or view the docstring (shift tab)
-```
-
-Interrupt the kernel.
-
-It also works for awaitables.
-
-```python
-import ipywidgets as ipw
-from aiologic import Event
-
-b = ipw.Button(description="Click me")
-event = Event()
-b.on_click(lambda _: event.set())
-display(b)
-await event
-```
-
-[^5]:
-    IPyKernel _solves_ this issue specifically for widgets by using the concept of
-    'widget coms over subshells'. Widget messages arrive in a different thread which on
-    occasion can cause unexpected behaviour, especially when using asynchronous libraries.
-
 ## Installation
 
 ```bash

{async_kernel-0.21.0 → async_kernel-0.22.1}/README.md

@@ -11,22 +11,24 @@
 
 ![logo-svg](https://github.com/user-attachments/assets/6781ec08-94e9-4640-b8f9-bb07a08e9587)
 
-async-kernel is a Python kernel for [Jupyter](https://docs.jupyter.org/en/latest/projects/kernels.html#kernels-programming-languages)
-that provides concurrent message handling via an asynchronous backend (asyncio or trio).
+async-kernel provides Python [Jupyter](https://docs.jupyter.org/en/latest/projects/kernels.html#kernels-programming-languages) kernels and clients
+compatible with CPython (Jupyter & VS code) and Pyodide (Jupyterlite).
 
-The kernel provides two external interfaces:
+The kernel interface supports multiple connections including:
 
-1. Direct ZMQ socket messaging via a configuration file and kernel spec - (Jupyter, VS Code, etc).
-2. An experimental callback style interface (Jupyterlite).
+1. Messaging via ZMQ sockets (Jupyter, VS Code, etc).
+2. Same-process local client enabling (Jupyterlite) and user access.
 
 ## Highlights
 
+- Built using [aiologic](https://aiologic.readthedocs.io/latest/) thread-safe synchronisation primitives.
+- The [`Caller`](https://fleming79.github.io/async-kernel/latest/reference/caller/#async_kernel.caller.Caller)
+  class provides a powerful but simple interface for cross-thread code execution in asyncio and trio
+  backends, with guest event loop support built in.
+- A zmq poll event loop for thread-safe zmq sockets.
 - [IPython shell](https://ipython.readthedocs.io/en/stable/overview.html#enhanced-interactive-python-shell)
     - top-level await ('asyncio' or 'trio' backend) in cells
     - async magic function support in cells
-- [anyio](https://pypi.org/project/anyio/) compatible asynchronous backend ([`asyncio`](https://docs.python.org/3/library/asyncio.html) (default) or [`trio`](https://pypi.org/project/trio/))
-- [aiologic](https://aiologic.readthedocs.io/latest/) thread-safe synchronisation primitives
-- [Backend agnostic multi-thread / multi-event loop management](https://fleming79.github.io/async-kernel/latest/reference/caller/#async_kernel.caller.Caller)
 - Per-subshell user_ns
 - GUI event loops [^1]
     - [x] inline
@@ -37,6 +39,8 @@ The kernel provides two external interfaces:
   [Jupyterlite](https://github.com/jupyterlite/jupyterlite) (try it online [here](https://fleming79.github.io/echo-kernel/) 👈)
     - `%pip install` magic (using micropip)
 - [Debugger client](https://jupyterlab.readthedocs.io/en/latest/user/debugger.html#debugger)
+- Local client.
+- ZMQ client.
 
 [^1]:
     A gui (_host_) enabled kernel interface starts a gui's mainloop (host) which starts
@@ -49,55 +53,6 @@ The kernel provides two external interfaces:
 
 [^3]: trio's [start_guest_run](https://trio.readthedocs.io/en/stable/reference-lowlevel.html#trio.lowlevel.start_guest_run).
 
-### Avoid deadlocks
-
-The standard (synchronous) kernel implementation processes messages sequentially irrespective
-of the message type. The problem being that long running execute requests make the kernel non-responsive.
-
-Another problem exists when an asynchronous execute request awaits a result that is delivered
-via a kernel message - this will cause a deadlock because the message will be stuck in the queue behind
-the _blocking_ execute request[^5].
-
-async-kernel handles messages according to the channel and message type. So widget com message
-will get processed in a separate queue to an execute request. Further detail is given in the [concurrency notebook](https://fleming79.github.io/async-kernel/latest/notebooks/concurrency/), a Jupyterlite version is available [here](https://fleming79.github.io/echo-kernel/).
-
-#### Example
-
-Make a blocking call in a Jupyter lab notebook or console.
-
-```python
-# Make the shell's thread busy
-import time
-
-time.sleep(1e6)
-```
-
-While the above is _blocking_ (the kernel is _busy_).
-
-```python
-dir()  # try code completion (tab) or view the docstring (shift tab)
-```
-
-Interrupt the kernel.
-
-It also works for awaitables.
-
-```python
-import ipywidgets as ipw
-from aiologic import Event
-
-b = ipw.Button(description="Click me")
-event = Event()
-b.on_click(lambda _: event.set())
-display(b)
-await event
-```
-
-[^5]:
-    IPyKernel _solves_ this issue specifically for widgets by using the concept of
-    'widget coms over subshells'. Widget messages arrive in a different thread which on
-    occasion can cause unexpected behaviour, especially when using asynchronous libraries.
-
 ## Installation
 
 ```bash

{async_kernel-0.21.0 → async_kernel-0.22.1}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.21.0'
-__version_tuple__ = version_tuple = (0, 21, 0)
+__version__ = version = '0.22.1'
+__version_tuple__ = version_tuple = (0, 22, 1)
 
 __commit_id__ = commit_id = None

{async_kernel-0.21.0 → async_kernel-0.22.1}/docs/notebooks/caller.ipynb

@@ -13,9 +13,9 @@
    "source": [
     "# Caller: A backend agnostic executor (notebook)\n",
     "\n",
-    "_This notebook has the Python dependencies: `trio`, `matplotlib`_\n",
+    "_This notebook uses `trio` in some cells._\n",
     "\n",
-    "`Caller` is a thread-local class that coordinates the execution of functions and coroutines in the event loop of a `asyncio` or `trio` backend."
+    "`Caller` is a thread-local object that coordinates the execution of functions and coroutines in the event loop of an `asyncio` or `trio` backend."
    ]
   },
   {
@@ -36,13 +36,13 @@
    "source": [
     "A `Caller` instance can be started with one gui as a host to one backend started as a guest. \n",
     "\n",
-    "A second backend can also be started in the same thread with or without a host gui event loop.\n",
+    "A second backend can also be started in the same thread/caller with or without a host gui event loop.\n",
     "Potentially the same thread could have up to:\n",
     "\n",
     "- One host gui event loop (`tk`, `qt`, `...`)\n",
     "- Two asynchronous backends (`asyncio`, `trio`)\n",
     "\n",
-    "It should be noted that gui's generally assume/require their mainloop runs in the main thread."
+    "It should be noted that gui's generally assume/require that their mainloop runs in the main thread."
    ]
   },
   {
@@ -74,7 +74,7 @@
    "id": "5",
    "metadata": {},
    "source": [
-    "There are two caller instances associated with the Kernel:\n",
+    "There are two caller instances associated with the kernel interface:\n",
     "\n",
     "- Shell: The caller for the shell channel (normally the MainThread).\n",
     "- Control: The caller for the control channel (a child of the shell)."
@@ -109,12 +109,11 @@
    "source": [
     "## Modifiers\n",
     "\n",
-    "There are four modifiers that determine which instance is returned when calling `Caller`.\n",
+    "There are three modifiers that can change the instance that is returned when calling `Caller`.\n",
     "\n",
     "- `CurrentThread` (default): Access the caller that belongs to the current thread (or context with Pyodide).\n",
     "- `MainThread`: Access main thread for the Caller.\n",
-    "- `NewThread`: Create a new thread.\n",
-    "- `manual`: Manually create a new instance for the current thread (must be started manually)."
+    "- `NewThread`: Create a new thread."
    ]
   },
   {
@@ -186,9 +185,11 @@
    "source": [
     "## Caller.get\n",
     "\n",
-    "`Caller.get` is a method to get an instance of a `Caller` by name, passing the same name will return the same caller on subsequent calls.\n",
-    "The same [options](#caller-creation-options) for creation of a new `Caller` can be specified. Calling `caller.get()` with no `name` will always return a\n",
-    "new instance of a `Caller`."
+    "`Caller.get` is a method to obtain a _child_ instance of a `Caller` by name. \n",
+    "Passing the same name on the same caller will return the same child caller on subsequent calls.\n",
+    "The same [options](#caller-creation-options) for creation of a new `Caller` can be specified. \n",
+    "Calling `caller.get()` with no `name` will always return a new instance of a `Caller`. All children\n",
+    "of a caller will stop when the parent stops."
    ]
   },
   {
@@ -319,7 +320,7 @@
     "\n",
     "### Caller.queue_call\n",
     "\n",
-    "This method is used extensively by the kernel for message handling. Each time the `queue_call` is called with the same function the function and call arguments are appended to a queue. On the first call a task is started in the backend to process the queue as items are added. The task remains alive until the function is deleted or the queue is stopped. Any exceptions that occur are logged."
+    "This method is used extensively by the kernel for message handling. Each time the `queue_call` is called with the same function, the function and call arguments are appended to a queue. On the first call a task is started in the backend to process the queue as items are added. The task remains alive until the function is deleted or the queue is stopped. Any exceptions that occur are logged."
    ]
   },
   {
@@ -338,7 +339,7 @@
     "def f(n):\n",
     "    float(n)\n",
     "    done.down()\n",
-    "    print(done)\n",
+    "    print(done.value, \"Pending id:\", id(Caller.current_pending()))\n",
     "\n",
     "\n",
     "for i in range(N):\n",
@@ -413,13 +414,11 @@
     "import random\n",
     "import time\n",
     "\n",
-    "import anyio\n",
     "import ipywidgets as ipw\n",
     "\n",
     "outputs = {}\n",
     "stop = ipw.RadioButtons(value=None, options=[\"Stop\"])\n",
     "box = ipw.VBox([stop])\n",
-    "await anyio.sleep(0.2)\n",
     "display(box)\n",
     "\n",
     "\n",
@@ -476,13 +475,14 @@
    "source": [
     "## Caller.create_pending_group\n",
     "\n",
-    "A `PendingGroup` is an asynchronous context manager for for `Pending`. All pending that 'opt-in' when created are added to the pending group (`Caller` methods that return `Pending` 'opt-in').\n",
+    "A `PendingGroup` is an asynchronous context manager for `Pending`. All pending that 'opt-in' when created are added to the pending group (`Caller` methods that return `Pending` 'opt-in').\n",
     "\n",
     "The `PendingGroup` has different modes:\n",
     "\n",
-    "- 0: Ignore cancellation of pending.\n",
+    "- 0: Ignore cancellation of pending, if any pending is cancelled - exit quietly.\n",
     "- 1: Cancel if any pending is cancelled - raise PendingCancelled on exit.\n",
-    "- 2: Cancel if any pending is cancelled - exit quietly."
+    "- 2: Cancel if any pending is cancelled - exit quietly.\n",
+    "- 3: Ignore cancellation of pending, if any pending is cancelled - raise PendingCancelled on exit."
    ]
   },
   {

{async_kernel-0.21.0 → async_kernel-0.22.1}/docs/notebooks/concurrency.ipynb

@@ -13,32 +13,41 @@
    "source": [
     "# Concurrent message handling (notebook)\n",
     "\n",
-    "async-kernel is capable of concurrent message handling. It provides a separate message handler for each channel and msg_type.\n",
-    "\n",
-    "As messages are received they are queued for execution by the message handler.\n",
+    "async-kernel provides concurrent message handling with a separate message handler queue for each channel and msg_type.\n",
+    "Execute requests also provide a separate queue per subshell.\n",
     "\n",
     "## Callers\n",
     "\n",
     "async-kernel provides two `Callers` for the _shell_ and _control_ channels. The shell's `Caller` is \n",
     "associated with the thread where the kernel is started, normally this is the _MainThread_. \n",
-    "In CPython, the `Caller` for the _control_ channel is started as a child of the shell caller with \n",
-    "it's own thread and asynchronous backend ('asyncio' or 'trio').\n",
     "\n",
-    "## ZMQ message handling (CPython)\n",
+    "## Interface\n",
+    "\n",
+    "The interface is a singleton which provides configuration for all classes that subclass from `HasInterface`.\n",
+    "The interface coordinates the startup and shutdown of the kernel and connections to communicate with the\n",
+    "kernel.\n",
+    "\n",
+    "In CPython the interface can be started from the command line with a connection file. The interface\n",
+    "is configurable via settings defined in the kernel spec, or by using the traitlets style configuration\n",
+    "files. Multiple connections are allow on the connection. \n",
+    "\n",
+    "## Connections \n",
+    "Connections are provided to communicate with the kernel in the same thread. There is\n",
+    "no limit to the number of connections, however increasing the number of connections will slow\n",
+    "down the interface because all iopub messages are sent on every connection. Additional connection\n",
+    "subclasses can created by subclassing from Connection.\n",
+    "\n",
+    "\n",
+    "## ZMQ Socket Based connection\n",
     "\n",
-    "The kernel interface also starts two additional threads dedicated to receive the messages on \n",
-    "the  _shell_ and _control_ channels, the specific function call is `session.recv(socket, mode=zmq.BLOCKY, copy=False)`. \n",
+    "Currently zmq sockets are the only _external_ connection provided. A ZMQConnection is automatically\n",
+    "started when the interface is started in CPython.\n",
     "\n",
-    "Each thread blocks until a new message is received on the zmq socket. When a message is received, \n",
-    "the kernel's `message_handler` is called with detail of the message (Job), the channel and a function\n",
-    "that is to be used to send the response corresponding to the message. The `message_handler` obtains \n",
-    "the dedicated handler according to the `message_type`, `run_mode`, `channel` and `subshell_id` and \n",
-    "schedules execution of the dedicated message handler in `Caller's` thread. \n",
     "\n",
     "## Shell messaging\n",
     "\n",
-    "Both `execute_request` and `com_msg` are always run in the shell's thread (normally the _MainThread_).\n",
-    "All other messages on the shell channel are run in the control thread.\n",
+    "Both `execute_request` and `com_msg` are always handled in the shell's thread (normally the _MainThread_).\n",
+    "All other messages on the shell channel are handled in the control thread.\n",
     "\n",
     "## Control messaging\n",
     "\n",
@@ -401,7 +410,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python (async)",
+   "display_name": "Python 3 (async)",
    "language": "python",
    "name": "async"
   },
@@ -415,7 +424,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.12"
+   "version": "3.11.15"
   }
  },
  "nbformat": 4,