More restructuring of the docs.docs

1 files changed, 44 insertions, 0 deletions

diff --git a/docs/python_threads.rst b/docs/python_threads.rst
new file mode 100644
index 0000000..7389d3d
--- /dev/null
+++ b/docs/python_threads.rst
@@ -0,0 +1,44 @@
+==============================
+ Greenlets and Python Threads
+==============================
+
+Greenlets can be combined with Python threads; in this case, each thread
+contains an independent "main" greenlet with a tree of sub-greenlets. It
+is not possible to mix or switch between greenlets belonging to different
+threads.
+
+.. doctest::
+
+   >>> from greenlet import getcurrent
+   >>> from threading import Thread
+   >>> from threading import Event
+   >>> started = Event()
+   >>> switched = Event()
+   >>> class T(Thread):
+   ...     def run(self):
+   ...         self.glet = getcurrent()
+   ...         started.set()
+   ...         switched.wait()
+   >>> t = T()
+   >>> t.start()
+   >>> _ = started.wait()
+   >>> t.glet.switch()
+   Traceback (most recent call last):
+   ...
+   greenlet.error: cannot switch to a different thread
+   >>> switched.set()
+   >>> t.join()
+
+Note that when a thread dies, the thread's main greenlet is not
+considered to be dead.
+
+.. doctest::
+
+   >>> t.glet.dead
+   False
+
+.. caution::
+
+   For these reasons, it's best to not pass references to a greenlet
+   running in one thread to another thread. If you do, take caution to
+   carefully manage the lifetime of the references.