{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "696b3c3a",
   "metadata": {},
   "source": [
    "# Timeouts\n",
    "\n",
    "Timeouts play an important role in Cicada networking, because they're the primary mechanism for detecting failures among players.  Consider the following example of a player waiting for a message that never arrives:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "978d8658",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:root:Player 0 timeout: 5\n",
      "INFO:root:Player 1 timeout: 5\n",
      "ERROR:root:Player 0 exception: Tag 42 from player 1 timed-out after 5s\n"
     ]
    }
   ],
   "source": [
    "import logging\n",
    "\n",
    "from cicada.communicator import SocketCommunicator\n",
    "from cicada.logger import Logger\n",
    "\n",
    "logging.basicConfig(level=logging.INFO)\n",
    "\n",
    "def main(communicator):\n",
    "    log = Logger(logging.getLogger(), communicator)\n",
    "    \n",
    "    log.info(f\"Player {communicator.rank} timeout: {communicator.timeout}\")\n",
    "    if communicator.rank == 0:\n",
    "        try:\n",
    "            communicator.recv(src=1, tag=42)\n",
    "        except Exception as e:\n",
    "            logging.error(f\"Player {communicator.rank} exception: {e}\")\n",
    "    \n",
    "SocketCommunicator.run(world_size=2, fn=main);"
   ]
  },
  {
   "cell_type": "raw",
   "id": "5fb7767e",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Each player prints their default timeout, which is five seconds, then player 0 waits for a message from player 1, who has already exited.  After five seconds, :meth:`~cicada.communicator.socket.SocketCommunicator.recv` raises an exception that reports the timeout.\n",
    "\n",
    "If you need a different default timeout, you can specify it at the point where your communicator is created (:meth:`~cicada.communicator.socket.SocketCommunicator.run` in this case):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "7ab02f2c",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:root:Player 0 timeout: 10\n",
      "INFO:root:Player 1 timeout: 10\n",
      "ERROR:root:Player 0 exception: Tag 42 from player 1 timed-out after 10s\n"
     ]
    }
   ],
   "source": [
    "def main(communicator):\n",
    "    log = Logger(logging.getLogger(), communicator)\n",
    "    \n",
    "    log.info(f\"Player {communicator.rank} timeout: {communicator.timeout}\")\n",
    "    if communicator.rank == 0:\n",
    "        try:\n",
    "            communicator.recv(src=1, tag=42)\n",
    "        except Exception as e:\n",
    "            logging.error(f\"Player {communicator.rank} exception: {e}\")\n",
    "    \n",
    "SocketCommunicator.run(world_size=2, fn=main, timeout=10);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03789409",
   "metadata": {},
   "source": [
    "... here, we set the timeout to ten seconds.\n",
    "\n",
    "You can also change the timeout at any time after the communicator has been created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "297071d0",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:root:Player 0 original timeout: 5\n",
      "INFO:root:Player 1 original timeout: 5\n",
      "INFO:root:Player 0 new timeout: 8\n",
      "INFO:root:Player 1 new timeout: 8\n",
      "ERROR:root:Player 0 exception: Tag 42 from player 1 timed-out after 8s\n"
     ]
    }
   ],
   "source": [
    "def main(communicator):\n",
    "    log = Logger(logging.getLogger(), communicator)\n",
    "    \n",
    "    log.info(f\"Player {communicator.rank} original timeout: {communicator.timeout}\")\n",
    "    communicator.timeout = 8\n",
    "    log.info(f\"Player {communicator.rank} new timeout: {communicator.timeout}\")\n",
    "    \n",
    "    if communicator.rank == 0:\n",
    "        try:\n",
    "            communicator.recv(src=1, tag=42)\n",
    "        except Exception as e:\n",
    "            logging.error(f\"Player {communicator.rank} exception: {e}\")\n",
    "    \n",
    "SocketCommunicator.run(world_size=2, fn=main);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a9f6f82",
   "metadata": {},
   "source": [
    "You can also change timeouts temporarily using a context manager:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "ed1cee3d",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:root:Player 0 original timeout: 5\n",
      "INFO:root:Player 1 original timeout: 5\n",
      "INFO:root:Player 0 new timeout: 8\n",
      "INFO:root:Player 1 new timeout: 8\n",
      "INFO:root:Player 1 restored timeout: 5\n",
      "ERROR:root:Player 0 exception: Tag 42 from player 1 timed-out after 8s\n",
      "INFO:root:Player 0 restored timeout: 5\n"
     ]
    }
   ],
   "source": [
    "def main(communicator):\n",
    "    log = Logger(logging.getLogger(), communicator)\n",
    "    \n",
    "    log.info(f\"Player {communicator.rank} original timeout: {communicator.timeout}\")\n",
    "    with communicator.override(timeout=8):\n",
    "        log.info(f\"Player {communicator.rank} new timeout: {communicator.timeout}\")\n",
    "\n",
    "        if communicator.rank == 0:\n",
    "            try:\n",
    "                communicator.recv(src=1, tag=42)\n",
    "            except Exception as e:\n",
    "                logging.error(f\"Player {communicator.rank} exception: {e}\")\n",
    "    logging.info(f\"Player {communicator.rank} restored timeout: {communicator.timeout}\")\n",
    "    \n",
    "SocketCommunicator.run(world_size=2, fn=main);"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}