docs/source/examples/Futures.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Futures in IPython Parallel\n",
    "\n",
    "The IPython Parallel AsyncResult object extends `concurrent.futures.Future`,\n",
    "which makes it compatible with most async frameworks in Python.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Starting 4 engines with <class 'ipyparallel.cluster.launcher.LocalEngineSetLauncher'>\n",
      "100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 4/4 [00:01<00:00,  3.96engine/s]\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<DirectView [0, 1, 2, 3]>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "I got PID: 64955\n"
     ]
    }
   ],
   "source": [
    "import ipyparallel as ipp\n",
    "\n",
    "rc = ipp.Cluster(n=4).start_and_connect_sync()\n",
    "\n",
    "dv = rc[:]\n",
    "dv.activate()\n",
    "dv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Do some imports everywhere"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%px --local --block\n",
    "import os\n",
    "import time\n",
    "\n",
    "import numpy as np\n",
    "from numpy.linalg import norm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def random_norm(n):\n",
    "    \"\"\"Generates a 1xN array and computes its 2-norm\"\"\"\n",
    "    A = np.random.random(n)\n",
    "    return norm(A, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The basic async API hasn't changed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<AsyncResult(random_norm): pending>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f = rc[-1].apply(random_norm, 100)\n",
    "f"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "np.float64(5.916785808055198)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f.get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But the full Futures API is now available:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "np.float64(5.916785808055198)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f.result()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The standard futures API has methods for registering callbackes, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "64955"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f = rc[-1].apply(os.getpid)\n",
    "f.add_done_callback(lambda _: print(f\"I got PID: {_.result()}\"))\n",
    "f.result()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A more complex example shows us how AsyncResults can be integrated into existing async applications, now that they are Futures:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      ". [64952, 64953, 64954, 64955]\n",
      ". . [64952, 64953, 64954, 64955]\n",
      ". . . [64952, 64953, 64954, 64955]\n",
      ". . . . [64952, 64953, 64954, 64955]\n"
     ]
    }
   ],
   "source": [
    "import asyncio\n",
    "import sys\n",
    "\n",
    "\n",
    "def sleep_task(t):\n",
    "    time.sleep(t)\n",
    "    return os.getpid()\n",
    "\n",
    "\n",
    "async def background():\n",
    "    \"\"\"A backgorund coroutine to demonstrate that we aren't blocking\"\"\"\n",
    "    while True:\n",
    "        await asyncio.sleep(1)\n",
    "        print('.', end=' ')\n",
    "        sys.stdout.flush()  # not needed after ipykernel 4.3\n",
    "\n",
    "\n",
    "async def work():\n",
    "    \"\"\"Submit some work and print the results when complete\"\"\"\n",
    "    for t in [1, 2, 3, 4]:\n",
    "        ar = rc[:].apply(sleep_task, t)\n",
    "        result = await asyncio.wrap_future(ar)  # this waits\n",
    "        print(result)\n",
    "\n",
    "\n",
    "bg = asyncio.Task(background())\n",
    "await work()\n",
    "bg.cancel();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So if you have an existing async application using coroutines and/or Futures,\n",
    "you can now integrate IPython Parallel as a standard async component for submitting work and waiting for its results."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Executors\n",
    "\n",
    "Executors are a standard Python API provided by various job-submission tools.\n",
    "A standard API such as Executor is useful for different libraries to expose this common API for asynchronous execution,\n",
    "because it means different implementations can be easily swapped out for each other and compared,\n",
    "or the best one for a given context can be used without having to change the code.\n",
    "\n",
    "With IPython Parallel, every View has an `.executor` property, to provide the Executor API for the given View.\n",
    "Just like Views, the assignment of work for an Executor depends on the View from which it was created.\n",
    "\n",
    "You can get an Executor for any View by accessing `View.executor`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 2, 3]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ex_all = rc[:].executor\n",
    "ex_all.view.targets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "64954\n",
      "64952\n",
      "64954\n",
      "64952\n",
      "64954\n",
      "64952\n",
      "64954\n",
      "64952\n",
      "64954\n",
      "64952\n"
     ]
    }
   ],
   "source": [
    "even_lbview = rc.load_balanced_view(targets=rc.ids[::2])\n",
    "ex_even = even_lbview.executor\n",
    "for pid in ex_even.map(lambda x: os.getpid(), range(10)):\n",
    "    print(pid)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Typically, though, one will want an Executor for a LoadBalancedView on all the engines.\n",
    "This is what the top-level `Client.executor()` method will return:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<LoadBalancedView None>"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ex = rc.executor()\n",
    "ex.view"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's create a few compatible Executor instances"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Comparing Executors\n",
    "\n",
    "Let's make a few Executors. Aside: [dask.distributed][] is a great library. Any IPython Parallel cluster can be bootstrapped into a dask cluster.\n",
    "\n",
    "[dask.distributed]: https://distributed.readthedocs.io\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There *can* be serialization differences, especially for interactively defined functions (i.e. those in defined in a notebook itself).\n",
    "That's why we define our task function in a local module,\n",
    "rather than here. ProcessPoolExecutor doesn't serialize interactively defined functions.\n",
    "But for the most part working with functions defined in modules works consistently across implementations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[0;32mimport\u001b[0m \u001b[0mnumpy\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;32mfrom\u001b[0m \u001b[0mnumpy\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mlinalg\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mnorm\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;32mdef\u001b[0m \u001b[0mtask\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mn\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m    \u001b[0;34m\"\"\"Generates a 1xN array and computes its 2-norm\"\"\"\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m    \u001b[0mA\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mnumpy\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mones\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mn\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m    \u001b[0;32mreturn\u001b[0m \u001b[0mnorm\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mA\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m2\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%pycat task_mod.py\n",
    "from task_mod import task"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def interactive_task(n):\n",
    "    \"\"\"Generates a 1xN array and computes its 2-norm\"\"\"\n",
    "    import numpy\n",
    "    from numpy.linalg import norm\n",
    "\n",
    "    A = numpy.ones(n)\n",
    "    return norm(A, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor\n",
    "\n",
    "distributed_client = rc.become_dask()\n",
    "dist_ex = distributed_client.get_executor()\n",
    "\n",
    "N = 4\n",
    "ip_ex = rc.executor(targets=range(N))\n",
    "thread_ex = ThreadPoolExecutor(N)\n",
    "process_ex = ProcessPoolExecutor(N)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "executors = [process_ex, thread_ex, ip_ex, dist_ex]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can submit the same work with the same API,\n",
    "using four different mechanisms for distributing work.\n",
    "The results will be the same:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ProcessPoolExecutor\n",
      "['0', '1', '2', '3', '4']\n",
      "ThreadPoolExecutor\n",
      "['0', '1', '2', '3', '4']\n",
      "ViewExecutor\n",
      "['0', '1', '2', '3', '4']\n",
      "ClientExecutor\n",
      "['0', '1', '2', '3', '4']\n"
     ]
    }
   ],
   "source": [
    "for executor in executors:\n",
    "    print(executor.__class__.__name__)\n",
    "    it = executor.map(str, range(5))\n",
    "    print(list(it))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This makes it easy to compare the different implementations. We are going to submit some dummy work—allocate and compute 2-norms of arrays of various sizes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1048576,  1261463,  1517571,  1825676,  2196334,  2642245,\n",
       "        3178688,  3824041,  4600417,  5534417,  6658042,  8009791,\n",
       "        9635980, 11592325, 13945857, 16777216])"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sizes = np.logspace(20, 24, 16, base=2, dtype=int)\n",
    "sizes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Run the work locally, to get a reference:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Local time:\n",
      "CPU times: user 65.8 ms, sys: 107 ms, total: 173 ms\n",
      "Wall time: 268 ms\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "ref = list(map(task, sizes))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then run again with the various Executors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for executor in executors:\n",
    "    print(executor.__class__.__name__)\n",
    "    result = executor.map(task, sizes)\n",
    "    rlist = list(result)\n",
    "    assert rlist == ref, f\"{rlist} != {ref}\"\n",
    "    # time the task assignment\n",
    "    %timeit list(executor.map(task, sizes))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For this toy work, the stdlib ThreadPoolExecutor appears to perform the best.\n",
    "That's useful info, and likely to be true for most workloads that release the GIL and fit comfortably into memory.\n",
    "When the GIL is involved, ProcessPoolExecutor is often best for simple workloads.\n",
    "\n",
    "One benefit of IPython Parallel or Distributed Executors over the stdlib Executors is that they do not have to be confined to a single machine.\n",
    "This means the standard Executor API lets you develop small-scale parallel tools that run locally in threads or processes,\n",
    "and then extend the *exact same code* to make use of multiple machines,\n",
    "just by selecting a different Executor.\n",
    "\n",
    "That seems pretty useful. [joblib][] is another package to implement standardized APIs for parallel backends,\n",
    "which IPython Parallel [also supports](joblib.ipynb).\n",
    "\n",
    "[joblib]: https://joblib.readthedocs.io"
   ]
  }
 ],
 "metadata": {
  "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.11.10"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}