From 0ecc373517b29e4c69c6fc689a37a7a017c813e7 Mon Sep 17 00:00:00 2001
From: Ryan Williams <breath@alum.mit.edu>
Date: Wed, 11 Aug 2010 11:54:44 -0700
Subject: [PATCH] Adding more clarity on send_exception, thanks to creiht and
 termie for illustrating the need for it.

---
 doc/testing.rst   |  2 +-
 eventlet/event.py | 40 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/doc/testing.rst b/doc/testing.rst
index 596bc5a..d63d8d2 100644
--- a/doc/testing.rst
+++ b/doc/testing.rst
@@ -34,7 +34,7 @@ To run the doctests included in many of the eventlet modules, use this command:
 
   $ nosetests --with-doctest eventlet/*.py
   
-Currently there are 14 doctests.
+Currently there are 16 doctests.
 
 Standard Library Tests
 ----------------------
diff --git a/eventlet/event.py b/eventlet/event.py
index 0ec9077..37bfdd1 100644
--- a/eventlet/event.py
+++ b/eventlet/event.py
@@ -167,6 +167,44 @@ class Event(object):
                     waiter.throw(*exc)
 
     def send_exception(self, *args):
-        """Same as :meth:`send`, but sends an exception to waiters."""
+        """Same as :meth:`send`, but sends an exception to waiters.
+        
+        The arguments to send_exception are the same as the arguments
+        to ``raise``.  If a single exception object is passed in, it
+        will be re-raised when :meth:`wait` is called, generating a
+        new stacktrace.  
+        
+           >>> from eventlet import event
+           >>> evt = event.Event()
+           >>> evt.send_exception(RuntimeError())
+           >>> evt.wait()
+           Traceback (most recent call last):
+             File "<stdin>", line 1, in <module>
+             File "eventlet/event.py", line 120, in wait
+               current.throw(*self._exc)
+           RuntimeError
+        
+        If it's important to preserve the entire original stack trace,
+        you must pass in the entire :func:`sys.exc_info` tuple.
+
+           >>> import sys
+           >>> evt = event.Event()
+           >>> try:
+           ...     raise RuntimeError()
+           ... except RuntimeError:
+           ...     evt.send_exception(*sys.exc_info())
+           ... 
+           >>> evt.wait()
+           Traceback (most recent call last):
+             File "<stdin>", line 1, in <module>
+             File "eventlet/event.py", line 120, in wait
+               current.throw(*self._exc)
+             File "<stdin>", line 2, in <module>
+           RuntimeError
+           
+        Note that doing so stores a traceback object directly on the
+        Event object, which may cause reference cycles. See the
+        :func:`sys.exc_info` documentation.
+        """
         # the arguments and the same as for greenlet.throw
         return self.send(None, args)