From 063b1aa07ab593508efc3de01a05b3637da9fdf1 Mon Sep 17 00:00:00 2001 From: Brianna Major Date: Thu, 30 Nov 2023 14:46:57 -0500 Subject: [PATCH] DOC: Add documentation about current getters support --- docs/advanced.md | 27 +++++++++++++++++++++++++++ docs/index.md | 1 + 2 files changed, 28 insertions(+) create mode 100644 docs/advanced.md diff --git a/docs/advanced.md b/docs/advanced.md new file mode 100644 index 00000000..2e3ac229 --- /dev/null +++ b/docs/advanced.md @@ -0,0 +1,27 @@ +# Returning Values +------------------ + +Communication with the IPython Kernel is asynchronous, which means that running Python code blocks any widget messages from the frontend until the Python code is done. With regards to ITKWidgets this means that getter functions do not "just work". Instead we get stuck in 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 ```