{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "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
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "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"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Synopsis\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",
    "**Note**: The examples in this section only work after the rest of the cells have been executed.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:23.331968Z",
     "iopub.status.busy": "2025-10-26T17:22:23.331896Z",
     "iopub.status.idle": "2025-10-26T17:22:23.538500Z",
     "shell.execute_reply": "2025-10-26T17:22:23.538226Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Timeout!\n"
     ]
    }
   ],
   "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": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "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": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Measuring Time\n",
    "\n",
    "The class `Timeout` allows interrupting some code execution after a given time interval."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:22.159184Z",
     "iopub.status.busy": "2025-10-26T17:22:22.159013Z",
     "iopub.status.idle": "2025-10-26T17:22:22.873083Z",
     "shell.execute_reply": "2025-10-26T17:22:22.872747Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "import bookutils.setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:22.875149Z",
     "iopub.status.busy": "2025-10-26T17:22:22.875025Z",
     "iopub.status.idle": "2025-10-26T17:22:22.876664Z",
     "shell.execute_reply": "2025-10-26T17:22:22.876431Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "import time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:22.878065Z",
     "iopub.status.busy": "2025-10-26T17:22:22.877976Z",
     "iopub.status.idle": "2025-10-26T17:22:22.879540Z",
     "shell.execute_reply": "2025-10-26T17:22:22.879331Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": [
     "remove-input"
    ]
   },
   "outputs": [],
   "source": [
    "# ignore\n",
    "from typing import Type, Any, Callable, Union, Optional"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:22.880854Z",
     "iopub.status.busy": "2025-10-26T17:22:22.880761Z",
     "iopub.status.idle": "2025-10-26T17:22:22.882229Z",
     "shell.execute_reply": "2025-10-26T17:22:22.882028Z"
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from types import FrameType, TracebackType"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Variant 1: Unix (using signals, efficient)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:22.883511Z",
     "iopub.status.busy": "2025-10-26T17:22:22.883430Z",
     "iopub.status.idle": "2025-10-26T17:22:22.884895Z",
     "shell.execute_reply": "2025-10-26T17:22:22.884615Z"
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "import signal"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:22.886137Z",
     "iopub.status.busy": "2025-10-26T17:22:22.886059Z",
     "iopub.status.idle": "2025-10-26T17:22:22.888761Z",
     "shell.execute_reply": "2025-10-26T17:22:22.888516Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "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
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Here's an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:22.890100Z",
     "iopub.status.busy": "2025-10-26T17:22:22.890022Z",
     "iopub.status.idle": "2025-10-26T17:22:22.891573Z",
     "shell.execute_reply": "2025-10-26T17:22:22.891347Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def some_long_running_function() -> None:\n",
    "    i = 10000000\n",
    "    while i > 0:\n",
    "        i -= 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:22.892785Z",
     "iopub.status.busy": "2025-10-26T17:22:22.892705Z",
     "iopub.status.idle": "2025-10-26T17:22:23.097921Z",
     "shell.execute_reply": "2025-10-26T17:22:23.097680Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Timeout!\n"
     ]
    }
   ],
   "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": {
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Variant 2: Generic / Windows (using trace, not very efficient)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:23.118696Z",
     "iopub.status.busy": "2025-10-26T17:22:23.118561Z",
     "iopub.status.idle": "2025-10-26T17:22:23.120210Z",
     "shell.execute_reply": "2025-10-26T17:22:23.119974Z"
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "import sys"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:23.121426Z",
     "iopub.status.busy": "2025-10-26T17:22:23.121348Z",
     "iopub.status.idle": "2025-10-26T17:22:23.124384Z",
     "shell.execute_reply": "2025-10-26T17:22:23.124057Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "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": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Again, our example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:23.125644Z",
     "iopub.status.busy": "2025-10-26T17:22:23.125548Z",
     "iopub.status.idle": "2025-10-26T17:22:23.327594Z",
     "shell.execute_reply": "2025-10-26T17:22:23.327294Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Timeout!\n"
     ]
    }
   ],
   "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": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Choosing the right variant"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T17:22:23.329111Z",
     "iopub.status.busy": "2025-10-26T17:22:23.329030Z",
     "iopub.status.idle": "2025-10-26T17:22:23.330783Z",
     "shell.execute_reply": "2025-10-26T17:22:23.330549Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "Timeout: Type[SignalTimeout] = SignalTimeout if hasattr(signal, 'SIGALRM') else GenericTimeout  # type: ignore"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Exercises"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "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.13.4"
  },
  "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
}