notebooks/threading.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Threading: Overview\n",
    "By nature, Python is a linear language, but the threading module comes in handy when you want a little more processing power. While threading in Python cannot be used for parallel CPU computation, it's perfect for I/O operations such as web scraping where the processor sits idle waiting for data.\n",
    "\n",
    "Threading is game-changing because many scripts related to network/data I/O spend the majority of their time waiting for data from a remote source. Because downloads might not be linked (i.e., scraping separate websites), the processor can download from different data sources in parallel and combine the result at the end. For CPU intensive processes, there is little benefit to using the threading module.\n",
    "\n",
    "\n",
    "### Basic Use\n",
    "Threading is included in the Python standard library, so we need not install any package. We simply impor the threading library:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import threading\n",
    "#from queue import Queue\n",
    "import time"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can use `target` as the callable object, `args` to pass parameters to the function, and `start` to start the thread"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n",
      "32\n",
      "\n",
      "4\n"
     ]
    }
   ],
   "source": [
    "def testThread(num):\n",
    "    print(num)\n",
    "\n",
    "if __name__ == '__main__':\n",
    "    for i in range(5):\n",
    "        t = threading.Thread(target=testThread, args=(i,))\n",
    "        t.start()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If calling this as a script you'll want to embed the threading below the  `if __name__ == '__main__':` statement to make sure the code that's nested inside it will only run if the script is run directly (not imported). We don't need to do this in this notebook. \n",
    "\n",
    "We see that the way we create and begin a thread process is with the `start()` call."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Worker: 0\n",
      "Worker: 1\n",
      "Worker: 2\n",
      "Worker: 3\n",
      "Worker: 4\n"
     ]
    }
   ],
   "source": [
    "def worker(num):\n",
    "    \"\"\"thread worker function\"\"\"\n",
    "    print('Worker: %s' % num)\n",
    "    return\n",
    "\n",
    "threads = []\n",
    "for i in range(5):\n",
    "    t = threading.Thread(target=worker, args=(i,))\n",
    "    threads.append(t)\n",
    "    t.start()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Locks\n",
    "\n",
    "You'll often want your threads to be able to use or modify variables common between threads but to do that you'll have to use something known as a lock. Whenever a function wants to modify a variable, it locks that variable. When another function wants to use a variable, it must wait until that variable is unlocked.\n",
    "\n",
    "Imagine two functions which both iterate a variable by 1. The lock allows you to ensure that one function can access the variable, perform calculations, and write back to that variable before another function can access the same variable.\n",
    "\n",
    "When using the threading module, this can also happen when you're printing because the text can get jumbled up (and cause data corruption). You can use a print lock to ensure that only one thread can print at a time.\n",
    "\n",
    "Locks are the simplest synchronization primitives in Python. A Lock has only two states — locked and unlocked (surprise). It is created in the unlocked state and has two principal methods — acquire() and release(). The acquire() method locks the Lock and blocks execution until the release() method in some other coroutine sets it to unlocked. Then it locks the Lock again and returns True. The release() method should only be called in the locked state, it sets the state to unlocked and returns immediately. If release() is called in the unlocked state, a RunTimeError is raised.\n",
    "\n",
    "Here’s the code which uses a Lock primitive for securely accessing a shared variable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3\n"
     ]
    }
   ],
   "source": [
    "\n",
    "from threading import Lock, Thread\n",
    "lock = Lock()\n",
    "g = 0\n",
    "\n",
    "def add_one():\n",
    "   \"\"\"\n",
    "   Just used for demonstration. It’s bad to use the ‘global’\n",
    "   statement in general.\n",
    "   \"\"\"\n",
    "   \n",
    "   global g\n",
    "   lock.acquire()\n",
    "   g += 1\n",
    "   lock.release()\n",
    "\n",
    "def add_two():\n",
    "   global g\n",
    "   lock.acquire()\n",
    "   g += 2\n",
    "   lock.release()\n",
    "\n",
    "threads = []\n",
    "for func in [add_one, add_two]:\n",
    "   threads.append(Thread(target=func))\n",
    "   threads[-1].start()\n",
    "\n",
    "for thread in threads:\n",
    "   \"\"\"\n",
    "   Waits for threads to complete before moving on with the main\n",
    "   script.\n",
    "   \"\"\"\n",
    "   thread.join()\n",
    "\n",
    "print(g)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This simply gives an output of 3, but now we are sure that the two functions are not changing the value of the global variable `g` simultaneously although they run on two different threads. Thus, Locks can be used to avoid inconsistent output by allowing only one thread to modify data at a time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting the thread level on cPython C extension libraries\n",
    "\n",
    "One can control the number of threads used by the C extension libraries that employ threads. Think here numpy and scipy and anything that calls on them. \n",
    "\n",
    "We can set the number of threads external prior to launching python or internal within python prior to loading the package which has threading enabled. \n",
    "\n",
    "### External setting of threads: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "# we would do this from the shell environment (bash here)\n",
    "# for example we set the total thread count to 2 below\n",
    "export OMP_NUM_THREADS=2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Internal setting of threads: (done within python)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "os.environ[\"OMP_NUM_THREADS\"] = \"1\"\n",
    "import numpy as np"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}