Add throttling section

Author: davidbrochart

docs/source/examples/Widget Events.ipynb

@@ -427,12 +427,56 @@
     "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": []
+   "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 = time()\n",
+    "        first_time = True\n",
+    "        def throttled(*args, **kwargs):\n",
+    "            def call_it():\n",
+    "                fn(*args, **kwargs)\n",
+    "            try:\n",
+    "                throttled.t.cancel()\n",
+    "            except(AttributeError):\n",
+    "                pass\n",
+    "            throttled.t = Timer(wait, call_it)\n",
+    "            nonlocal time_of_last_call, first_time\n",
+    "            now = time()\n",
+    "            if first_time or (now - time_of_last_call > wait):\n",
+    "                first_time = False\n",
+    "                time_of_last_call = now\n",
+    "                return fn(*args, **kwargs)\n",
+    "        return throttled\n",
+    "    return decorator"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To see how different it behaves compared to the debouncer, you can decorate the `value_changed` function above with `throttle(0.2)` instead of `debounce(0.2)`. Note that both decorators should not be used together."
+   ]
   },
   {
    "cell_type": "markdown",
@@ -466,7 +510,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.8.1"
   }
  },
  "nbformat": 4,