Merge pull request #2678 from davidbrochart/debounce

Added sections on debouncing and throttling

Author: jasongrout

docs/source/examples/Widget Events.ipynb

@@ -27,15 +27,6 @@
     "## Special events"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from __future__ import print_function"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -363,6 +354,150 @@
     "Sliders, `Text`, and `Textarea` controls default to `continuous_update=True`. `IntText` and other text boxes for entering integer or float numbers default to `continuous_update=False` (since often you'll want to type an entire number before submitting the value by pressing enter or navigating out of the box)."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Debouncing\n",
+    "\n",
+    "When trait changes trigger a callback that performs a heavy computation, you may want to not do the computation as often as the value is updated. For instance, if the trait is driven by a slider which has its `continuous_update` set to `True`, the user will trigger a bunch of computations in rapid succession.\n",
+    "\n",
+    "Debouncing solves this problem by delaying callback execution until the value has not changed for a certain time, after which the callback is called with the latest value. The effect is that the callback is only called when the trait pauses changing for a certain amount of time.\n",
+    "\n",
+    "Debouncing can be implemented using an asynchronous loop or threads. We show an asynchronous solution below, which is more suited for ipywidgets. If you would like to instead use threads to do the debouncing, replace the `Timer` class with `from threading import Timer`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import asyncio\n",
+    "\n",
+    "class Timer:\n",
+    "    def __init__(self, timeout, callback):\n",
+    "        self._timeout = timeout\n",
+    "        self._callback = callback\n",
+    "        self._task = asyncio.ensure_future(self._job())\n",
+    "\n",
+    "    async def _job(self):\n",
+    "        await asyncio.sleep(self._timeout)\n",
+    "        self._callback()\n",
+    "\n",
+    "    def cancel(self):\n",
+    "        self._task.cancel()\n",
+    "\n",
+    "def debounce(wait):\n",
+    "    \"\"\" Decorator that will postpone a function's\n",
+    "        execution until after `wait` seconds\n",
+    "        have elapsed since the last time it was invoked. \"\"\"\n",
+    "    def decorator(fn):\n",
+    "        timer = None\n",
+    "        def debounced(*args, **kwargs):\n",
+    "            nonlocal timer\n",
+    "            def call_it():\n",
+    "                fn(*args, **kwargs)\n",
+    "            if timer is not None:\n",
+    "                timer.cancel()\n",
+    "            timer = Timer(wait, call_it)\n",
+    "        return debounced\n",
+    "    return decorator"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here is how we use the `debounce` function as a decorator. Try changing the value of the slider. The text box will only update after the slider has paused for about 0.2 seconds."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "slider = widgets.IntSlider()\n",
+    "text = widgets.IntText()\n",
+    "\n",
+    "@debounce(0.2)\n",
+    "def value_changed(change):\n",
+    "    text.value = change.new\n",
+    "slider.observe(value_changed, 'value')\n",
+    "\n",
+    "widgets.VBox([slider, text])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Throttling\n",
+    "\n",
+    "Throttling is another technique that can be used to limit callbacks. Whereas debouncing ignores calls to a function if a certain amount of time has not passed since the last (attempt of) call to the function, throttling will just limit the rate of calls. This ensures that the function is regularly called.\n",
+    "\n",
+    "We show an synchronous solution below. Likewise, you can replace the `Timer` class with `from threading import Timer` if you want to use threads instead of asynchronous programming."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import asyncio\n",
+    "from time import time\n",
+    "\n",
+    "def throttle(wait):\n",
+    "    \"\"\" Decorator that prevents a function from being called\n",
+    "        more than once every wait period. \"\"\"\n",
+    "    def decorator(fn):\n",
+    "        time_of_last_call = 0\n",
+    "        scheduled = False\n",
+    "        new_args, new_kwargs = None, None\n",
+    "        def throttled(*args, **kwargs):\n",
+    "            nonlocal new_args, new_kwargs, time_of_last_call, scheduled\n",
+    "            def call_it():\n",
+    "                nonlocal new_args, new_kwargs, time_of_last_call, scheduled\n",
+    "                time_of_last_call = time()\n",
+    "                fn(*new_args, **new_kwargs)\n",
+    "                scheduled = False\n",
+    "            time_since_last_call = time() - time_of_last_call\n",
+    "            new_args = args\n",
+    "            new_kwargs = kwargs\n",
+    "            if not scheduled:\n",
+    "                new_wait = max(0, wait - time_since_last_call)\n",
+    "                Timer(new_wait, call_it)\n",
+    "                scheduled = True\n",
+    "        return throttled\n",
+    "    return decorator"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To see how different it behaves compared to the debouncer, here is the same slider example with its throttled value displayed in the text box. Notice how much more interactive it is, while still limiting the callback rate."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "slider = widgets.IntSlider()\n",
+    "text = widgets.IntText()\n",
+    "\n",
+    "@throttle(0.2)\n",
+    "def value_changed(change):\n",
+    "    text.value = change.new\n",
+    "slider.observe(value_changed, 'value')\n",
+    "\n",
+    "widgets.VBox([slider, text])"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -395,7 +530,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.4"
+   "version": "3.7.3"
   }
  },
  "nbformat": 4,