From d9d91992438d919cd7e9ffc7eb861a20154c671e Mon Sep 17 00:00:00 2001 From: Brianna Major Date: Thu, 30 Nov 2023 14:46:57 -0500 Subject: [PATCH 1/2] DOC: Add documentation about current getters support --- docs/advanced.md | 29 +++++++++++++++++++++++++++++ docs/index.md | 1 + 2 files changed, 30 insertions(+) create mode 100644 docs/advanced.md diff --git a/docs/advanced.md b/docs/advanced.md new file mode 100644 index 00000000..c2c39a18 --- /dev/null +++ b/docs/advanced.md @@ -0,0 +1,29 @@ +# Advanced +---------- + +## Returning Values + +Communication with the IPython Kernel is asynchronous, which means that running Python code blocks any comm messages until the Python code is done. With regards to ITKWidgets this means that getter functions do not "just work" - the Python code cannot complete until the comm message has resolved with the response and the message cannot resolve until the code has completed. This creates a deadlock that prevents the kernel from progressing. This has been a [documented issue](https://github.com/ipython/ipykernel/issues/65) for many years. + +Libraries like [ipython_blocking](https://github.com/kafonek/ipython_blocking) and [jupyter-ui-poll](https://github.com/Kirill888/jupyter-ui-poll) have made efforts to address this issue and their approaches have been a great source of inspiration for the custom solution that we have chosen for ITKWidgets. + +Our current solution prevents deadlocks but requires that getters be requested in one cell and resolved in another. For example: + +```python +viewer = view(image) +``` +```python +bg_color = viewer.get_background_color() +print(bg_color) +``` +would simply become: + +```python +viewer = view(image) +``` +```python +bg_color = viewer.get_background_color() +``` +```python +print(bg_color) +``` diff --git a/docs/index.md b/docs/index.md index dfd99cc5..0ba35107 100644 --- a/docs/index.md +++ b/docs/index.md @@ -23,4 +23,5 @@ quick_start_guide.rst deployments.rst integrations.rst development.rst +advanced.rst ``` From 71b6be1dce03f849a67f1b96ddef44950d9ea7f6 Mon Sep 17 00:00:00 2001 From: Brianna Major Date: Thu, 30 Nov 2023 15:21:07 -0500 Subject: [PATCH 2/2] DOC: Improve wording --- docs/advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced.md b/docs/advanced.md index c2c39a18..ff6cfc88 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -3,7 +3,7 @@ ## Returning Values -Communication with the IPython Kernel is asynchronous, which means that running Python code blocks any comm messages until the Python code is done. With regards to ITKWidgets this means that getter functions do not "just work" - the Python code cannot complete until the comm message has resolved with the response and the message cannot resolve until the code has completed. This creates a deadlock that prevents the kernel from progressing. This has been a [documented issue](https://github.com/ipython/ipykernel/issues/65) for many years. +Communication with the IPython Kernel is asynchronous, which causes challenges with Python code blocks in Jupyter cells that run synchronously. Multiple comm messages cannot be awaited during the synchronous Python code block execution. With regards to ITKWidgets this means that getter functions do not "just work" - the Python code cannot complete until the comm message has resolved with the response and the message cannot resolve until the code has completed. This creates a deadlock that prevents the kernel from progressing. This has been a [documented issue for the Jupyter ipykernel](https://github.com/ipython/ipykernel/issues/65) for many years. Libraries like [ipython_blocking](https://github.com/kafonek/ipython_blocking) and [jupyter-ui-poll](https://github.com/Kirill888/jupyter-ui-poll) have made efforts to address this issue and their approaches have been a great source of inspiration for the custom solution that we have chosen for ITKWidgets.