Update docs layout

* Explain these docs are for trunk (copied from ironic)
* All the docs in this repo are meant to be developer docs, so having a
  devref inside of the docs is redundant and just makes the docs more
  complicated to navigate. Move everything out of the devref folder and
  link to everything from main index.
* Move man pages into separate section. The man pages are pretty sparse
* right now, we should either make them useful or just delete them
* Remove dead docs from unused_docs list in doc/source/conf.py
* Shuffle docs landing page, move common referees to the top (API,
  hypervisor support matrix), Add a introduction section and more. The
  hope is the updated layout makes this document easier to navigate.
* Use maxdepth of 1
* Rename a few sections with what are hopefully better names

The next step is to prune out outdated documents and further cleanup
this page.

Change-Id: Iff453e47ccc902a0e72b1a5f6ce1ee939ff3a1a0

doc/source/threading.rst

@@ -0,0 +1,51 @@
+Threading model
+===============
+
+All OpenStack services use *green thread* model of threading, implemented
+through using the Python `eventlet <http://eventlet.net/>`_ and
+`greenlet <http://packages.python.org/greenlet/>`_ libraries.
+
+Green threads use a cooperative model of threading: thread context
+switches can only occur when specific eventlet or greenlet library calls are
+made (e.g., sleep, certain I/O calls). From the operating system's point of
+view, each OpenStack service runs in a single thread.
+
+The use of green threads reduces the likelihood of race conditions, but does
+not completely eliminate them. In some cases, you may need to use the
+``@lockutils.synchronized(...)`` decorator to avoid races.
+
+In addition, since there is only one operating system thread, a call that
+blocks that main thread will block the entire process.
+
+Yielding the thread in long-running tasks
+-----------------------------------------
+If a code path takes a long time to execute and does not contain any methods
+that trigger an eventlet context switch, the long-running thread will block
+any pending threads.
+
+This scenario can be avoided by adding calls to the eventlet sleep method
+in the long-running code path. The sleep call will trigger a context switch
+if there are pending threads, and using an argument of 0 will avoid introducing
+delays in the case that there is only a single green thread::
+
+	from eventlet import greenthread
+	...
+	greenthread.sleep(0)
+
+
+MySQL access and eventlet
+-------------------------
+Queries to the MySQL database will block the main thread of a service. This is
+because OpenStack services use an external C library for accessing the MySQL
+database. Since eventlet cannot use monkey-patching to intercept blocking
+calls in a C library, the resulting database query blocks the thread.
+
+The Diablo release contained a thread-pooling implementation that did not
+block, but this implementation resulted in a `bug`_ and was removed.
+
+See this `mailing list thread`_ for a discussion of this issue, including
+a discussion of the `impact on performance`_.
+
+.. _bug: https://bugs.launchpad.net/nova/+bug/838581
+.. _mailing list thread: https://lists.launchpad.net/openstack/msg08118.html
+.. _impact on performance: https://lists.launchpad.net/openstack/msg08217.html