notebooks/shared/Timeout.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    }
   },
   "source": [
    "# Timeout\n",
    "\n",
    "The code in this notebook helps in interrupting execution after a given time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    }
   },
   "source": [
    "**Prerequisites**\n",
    "\n",
    "* This notebook needs some understanding on advanced concepts in Python, notably \n",
    "    * classes\n",
    "    * the Python `with` statement\n",
    "    * the Python `signal` functions\n",
    "    * measuring time"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "source": [
    "## Synopsis\n",
    "<!-- Automatically generated. Do not edit. -->\n",
    "\n",
    "To [use the code provided in this chapter](Importing.ipynb), write\n",
    "\n",
    "```python\n",
    ">>> from debuggingbook.Timeout import <identifier>\n",
    "```\n",
    "\n",
    "and then make use of the following features.\n",
    "\n",
    "\n",
    "The `Timeout` class throws a `TimeoutError` exception after a given timeout has expired.\n",
    "Its typical usage is in conjunction with a `with` clause:\n",
    "\n",
    "```python\n",
    ">>> try:\n",
    ">>>     with Timeout(0.2):\n",
    ">>>         some_long_running_function()\n",
    ">>>     print(\"complete!\")\n",
    ">>> except TimeoutError:\n",
    ">>>     print(\"Timeout!\")\n",
    "Timeout!\n",
    "\n",
    "```\n",
    "Note: On Unix/Linux systems, the `Timeout` class uses [`SIGALRM` signals](https://docs.python.org/3.10/library/signal.html) (interrupts) to implement timeouts; this has no effect on performance of the tracked code. On other systems (notably Windows), `Timeout` uses the [`sys.settrace()`](https://docs.python.org/3.10/library/sys.html?highlight=settrace#sys.settrace) function to check the timer after each line of code, which affects performance of the tracked code.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    }
   },
   "source": [
    "## Measuring Time\n",
    "\n",
    "The class `Timeout` allows interrupting some code execution after a given time interval."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "import bookutils.setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    }
   },
   "outputs": [],
   "source": [
    "import time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ignore\n",
    "from typing import Type, Any, Callable, Union, Optional"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from types import FrameType, TracebackType"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Variant 1: Unix (using signals, efficient)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import signal"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    }
   },
   "outputs": [],
   "source": [
    "class SignalTimeout:\n",
    "    \"\"\"Execute a code block raising a timeout.\"\"\"\n",
    "\n",
    "    def __init__(self, timeout: Union[int, float]) -> None:\n",
    "        \"\"\"\n",
    "        Constructor. Interrupt execution after `timeout` seconds.\n",
    "        \"\"\"\n",
    "        self.timeout = timeout\n",
    "        self.old_handler: Any = signal.SIG_DFL\n",
    "        self.old_timeout = 0.0\n",
    "\n",
    "    def __enter__(self) -> Any:\n",
    "        \"\"\"Begin of `with` block\"\"\"\n",
    "        # Register timeout() as handler for signal 'SIGALRM'\"\n",
    "        self.old_handler = signal.signal(signal.SIGALRM, self.timeout_handler)\n",
    "        self.old_timeout, _ = signal.setitimer(signal.ITIMER_REAL, self.timeout)\n",
    "        return self\n",
    "\n",
    "    def __exit__(self, exc_type: Type, exc_value: BaseException,\n",
    "                 tb: TracebackType) -> None:\n",
    "        \"\"\"End of `with` block\"\"\"\n",
    "        self.cancel()\n",
    "        return  # re-raise exception, if any\n",
    "\n",
    "    def cancel(self) -> None:\n",
    "        \"\"\"Cancel timeout\"\"\"\n",
    "        signal.signal(signal.SIGALRM, self.old_handler)\n",
    "        signal.setitimer(signal.ITIMER_REAL, self.old_timeout)\n",
    "\n",
    "    def timeout_handler(self, signum: int, frame: Optional[FrameType]) -> None:\n",
    "        \"\"\"Handle timeout (SIGALRM) signal\"\"\"\n",
    "        raise TimeoutError()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    }
   },
   "source": [
    "Here's an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def some_long_running_function() -> None:\n",
    "    i = 10000000\n",
    "    while i > 0:\n",
    "        i -= 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    with SignalTimeout(0.2):\n",
    "        some_long_running_function()\n",
    "        print(\"Complete!\")\n",
    "except TimeoutError:\n",
    "    print(\"Timeout!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Variant 2: Generic / Windows (using trace, not very efficient)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class GenericTimeout:\n",
    "    \"\"\"Execute a code block raising a timeout.\"\"\"\n",
    "\n",
    "    def __init__(self, timeout: Union[int, float]) -> None:\n",
    "        \"\"\"\n",
    "        Constructor. Interrupt execution after `timeout` seconds.\n",
    "        \"\"\"\n",
    "\n",
    "        self.seconds_before_timeout = timeout\n",
    "        self.original_trace_function: Optional[Callable] = None\n",
    "        self.end_time: Optional[float] = None\n",
    "\n",
    "    def check_time(self, frame: FrameType, event: str, arg: Any) -> Callable:\n",
    "        \"\"\"Tracing function\"\"\"\n",
    "        if self.original_trace_function is not None:\n",
    "            self.original_trace_function(frame, event, arg)\n",
    "\n",
    "        current_time = time.time()\n",
    "        if self.end_time and current_time >= self.end_time:\n",
    "            raise TimeoutError\n",
    "\n",
    "        return self.check_time\n",
    "\n",
    "    def __enter__(self) -> Any:\n",
    "        \"\"\"Begin of `with` block\"\"\"\n",
    "        start_time = time.time()\n",
    "        self.end_time = start_time + self.seconds_before_timeout\n",
    "\n",
    "        self.original_trace_function = sys.gettrace()\n",
    "        sys.settrace(self.check_time)\n",
    "        return self\n",
    "\n",
    "    def __exit__(self, exc_type: type, \n",
    "                 exc_value: BaseException, tb: TracebackType) -> Optional[bool]:\n",
    "        \"\"\"End of `with` block\"\"\"\n",
    "        self.cancel()\n",
    "        return None  # re-raise exception, if any\n",
    "\n",
    "    def cancel(self) -> None:\n",
    "        \"\"\"Cancel timeout\"\"\"\n",
    "        sys.settrace(self.original_trace_function)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, our example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    with GenericTimeout(0.2):\n",
    "        some_long_running_function()\n",
    "        print(\"Complete!\")\n",
    "except TimeoutError:\n",
    "    print(\"Timeout!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Choosing the right variant"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Timeout: Type[SignalTimeout] = SignalTimeout if hasattr(signal, 'SIGALRM') else GenericTimeout  # type: ignore"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Synopsis\n",
    "\n",
    "The `Timeout` class throws a `TimeoutError` exception after a given timeout has expired.\n",
    "Its typical usage is in conjunction with a `with` clause:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    with Timeout(0.2):\n",
    "        some_long_running_function()\n",
    "    print(\"complete!\")\n",
    "except TimeoutError:\n",
    "    print(\"Timeout!\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note: On Unix/Linux systems, the `Timeout` class uses [`SIGALRM` signals](https://docs.python.org/3.10/library/signal.html) (interrupts) to implement timeouts; this has no effect on performance of the tracked code. On other systems (notably Windows), `Timeout` uses the [`sys.settrace()`](https://docs.python.org/3.10/library/sys.html?highlight=settrace#sys.settrace) function to check the timer after each line of code, which affects performance of the tracked code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercises"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a `Timeout` variant that works efficiently on Windows. Note that how to do this a long debated issue in programming forums."
   ]
  }
 ],
 "metadata": {
  "ipub": {
   "bibliography": "fuzzingbook.bib",
   "toc": true
  },
  "kernelspec": {
   "display_name": "venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.10 (main, Jan 15 2022, 11:48:04) \n[Clang 13.0.0 (clang-1300.0.29.3)]"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": true,
   "title_cell": "",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  },
  "toc-autonumbering": false,
  "vscode": {
   "interpreter": {
    "hash": "0af4f07dd039d1b4e562c7a7d0340393b1c66f50605ac6af30beb81aa23b7ef5"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}