chore: Document how tasklets work (#690)

Jim Fulton · web-flow · commit 2eeea4dee229 · 2021-07-22T14:03:34.000-04:00
Tasklets are confusing because they rely on special event-loop
behavior that was undocumented.  Added a comment to work through the
example in more detail.
diff --git a/packages/google-cloud-ndb/google/cloud/ndb/tasklets.py b/packages/google-cloud-ndb/google/cloud/ndb/tasklets.py
@@ -25,17 +25,40 @@
 the tasklet, any yield of a Future waits for and returns the Future's result.
 For example::
 
+    from from google.cloud.ndb.tasklets import tasklet
+
     @tasklet
     def foo():
-        a = yield <some Future>
-        b = yield <another Future>
+        a = yield <AFuture>
+        b = yield <BFuture>
         return a + b
 
     def main():
         f = foo()
         x = f.result()
         print x
 
+In this example, `foo` needs the results of two futures, `AFuture` and
+`BFuture`, which it gets somehow, for example as results of calls.
+Rather than waiting for their values and blocking, it yields. First,
+the tasklet yields `AFuture`.  The event loop gets `AFuture` and takes
+care of waiting for its result.  When the event loop gets the result
+of `AFuture`, it sends it to the tasklet by calling `send` on the
+iterator returned by calling the tasklet.  The tasklet assigns the
+value sent to `a` and then yields `BFuture`.  Again the event loop
+waits for the result of `BFuture` and sends it to the tasklet.  The
+tasklet then has what it needs to compute a result.
+
+The tasklet simply returns its result. (Behind the scenes, when you
+return a value from a generator in Python 3, a `StopIteration`
+exception is raised with the return value as its argument. The event
+loop catches the exception and uses the exception argument as the
+result of the tasklet.  This won't work for Python 2. If you need to
+support Python 2, as the library itself does, you'll need to raise a
+`google.cloud.ndb.tasklets.Return` exception, with the return value as
+the exception argument, as in `google.cloud.ndb.tasklets.Return(a +
+b)`.)
+
 Note that blocking until the Future's result is available using result() is
 somewhat inefficient (though not vastly -- it is not busy-waiting). In most
 cases such code should be rewritten as a tasklet instead::
