More restructuring of the docs.docs

1 files changed, 239 insertions, 0 deletions

diff --git a/docs/gui_example.rst b/docs/gui_example.rst
new file mode 100644
index 0000000..047ed10
--- /dev/null
+++ b/docs/gui_example.rst
@@ -0,0 +1,239 @@
+
+.. _gui_example:
+
+==================================================================
+ Motivation: Treating an Asynchronous GUI Like a Synchronous Loop
+==================================================================
+
+.. currentmodule:: greenlet
+
+In this document, we'll demonstrate how greenlet can be used to
+connect synchronous and asynchronous operations, without introducing
+any additional threads or race conditions. We'll use the example of
+transforming a "pull"-based console application into an asynchronous
+"push"-based GUI application *while still maintaining the simple
+pull-based structure*.
+
+Similar techniques work with XML expat parsers; in general, it can be
+framework that issues asynchronous callbacks.
+
+.. |--| unicode:: U+2013   .. en dash
+.. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
+   :trim:
+
+
+A Simple Terminal App
+=====================
+
+Let's consider a system controlled by a terminal-like console, where
+the user types commands. Assume that the input comes character by
+character. In such a system, there will typically be a loop like the
+following one:
+
+.. doctest::
+
+    >>> def echo_user_input(user_input):
+    ...     print('    <<< ' + user_input.strip())
+    ...     return user_input
+    >>> def process_commands():
+    ...    while True:
+    ...        line = ''
+    ...        while not line.endswith('\n'):
+    ...            line += read_next_char()
+    ...        echo_user_input(line)
+    ...        if line == 'quit\n':
+    ...            print("Are you sure?")
+    ...            if echo_user_input(read_next_char()) != 'y':
+    ...                continue    # ignore the command
+    ...            print("(Exiting loop.)")
+    ...            break # stop the command loop
+    ...        process_command(line)
+
+Here, we have an infinite loop. The job of the loop is to read characters
+that the user types, accumulate that into a command line, and then
+execute the command. The heart of the loop is around ``read_next_char()``:
+
+.. doctest::
+
+    >>> def read_next_char():
+    ...    """
+    ...    Called from `process_commands`;
+    ...    blocks until a character has been typed and returns it.
+    ...    """
+
+This function might be implemented by simply reading from
+:obj:`sys.stdin`, or by something more complex such as
+:meth:`curses.window.getch`, but in any case, it doesn't return until
+a key has been read from the user.
+
+Competing Event Loops
+=====================
+
+Now assume that you want to plug this program into a GUI. Most GUI
+toolkits are event-based. Internally, they run their own infinite loop
+much like the one we wrote above, invoking a call-back for each
+character the user presses (``event_keydown(key)``).
+
+.. doctest::
+
+    >>> def event_keydown(key):
+    ...    "Called by the event system *asynchronously*."
+
+
+In this setting, it is difficult to implement the ``read_next_char()``
+function needed by the code above. We have two incompatible functions.
+First, there's the function the GUI will call asynchronously to notify
+about an event; it's important to stress that we're not in control of
+when this function is called |---| in fact, our code isn't in the call
+stack at all, the GUI's loop is the only thing running. But that
+doesn't fit with our second function, ``read_next_char()`` which itself
+is supposed to be blocking and called from the middle of its own loop.
+
+How can we fit this asynchronous delivery mechanism together with our
+synchronous, blocking function that reads the next character the user
+types?
+
+Enter greenlets: Dual Infinite Loops
+====================================
+
+You might consider doing that with :class:`threads <threading.Thread>`
+[#f1]_, but that can get complicated rather quickly. greenlets are an
+alternate solution that don't have the related locking and other
+problems threads introduce.
+
+By introducing a greenlet to run ``process_commands``, and having it
+communicate with the greenlet running the GUI event loop, we can
+effectively have a single thread be *in the middle of two infinite
+loops at once* and switch between them as desired. Pretty cool.
+
+It's even cooler when you consider that the GUI's loop is likely to be
+implemented in C, not Python, so we'll be switching between infinite
+loops both in native code and in the Python interpreter.
+
+First, let's create a greenlet to run the ``process_commands`` function
+(note that we're not starting it just yet, only defining it).
+
+.. doctest::
+
+    >>> from greenlet import greenlet
+    >>> g_processor = greenlet(process_commands)
+
+Now, we need to arrange for the communication between the GUI's event
+loop and its callback ``event_keydown`` (running in the implicit main
+greenlet) and this new greenlet. The changes to ``event_keydown`` are
+pretty simple: just send the key the GUI gives us into the loop that
+``process_commands`` is in using :meth:`greenlet.switch`.
+
+.. doctest::
+
+    >>> main_greenlet = greenlet.getcurrent()
+    >>> def event_keydown(key): # running in main_greenlet
+    ...     # jump into g_processor, sending it the key
+    ...     g_processor.switch(key)
+
+The other side of the coin is to define ``read_next_char`` to accept
+this key event. We do this by letting the main greenlet run the GUI
+loop until the GUI loop jumps back to is from ``event_keydown``:
+
+.. doctest::
+
+    >>> def read_next_char(): # running in g_processor
+    ...     # jump to the main greenlet, where the GUI event
+    ...     # loop is running, and wait for the next key
+    ...     next_char = main_greenlet.switch('blocking in read_next_char')
+    ...     return next_char
+
+Having defined both functions, we can start the ``process_commands``
+greenlet, which will make it to ``read_next_char()`` and immediately
+switch back to the main greenlet:
+
+.. doctest::
+
+    >>> g_processor.switch()
+    'blocking in read_next_char'
+
+Now we can hand control over to the main event loop of the GUI. Of
+course, in documentation we don't have a GUI, so we'll fake one that
+feeds keys to ``event_keydown``; for demonstration purposes we'll also
+fake a ``process_command`` function that just prints the line it got.
+
+.. doctest::
+
+   >>> def process_command(line):
+   ...     print('(Processing command: ' + line.strip() + ')')
+
+   >>> def gui_mainloop():
+   ...    # The user types "hello"
+   ...    for c in 'hello\n':
+   ...        event_keydown(c)
+   ...    # The user types "quit"
+   ...    for c in 'quit\n':
+   ...        event_keydown(c)
+   ...    # The user responds to the prompt with 'y'
+   ...    event_keydown('y')
+
+   >>> gui_mainloop()
+       <<< hello
+   (Processing command: hello)
+       <<< quit
+   Are you sure?
+       <<< y
+   (Exiting loop.)
+   >>> g_processor.dead
+   True
+
+.. sidebar:: Switching Isn't Contagious
+
+   Notice how a single call to ``gui_mainloop`` successfully switched
+   back and forth between two greenlets without the caller or author of
+   ``gui_mainloop`` needing to be aware of that.
+
+   Contrast this with :mod:`asyncio`, where the keywords ``async def`` and
+   ``await`` often spread throughout the codebase once introduced.
+
+   In fact, greenlets can be used to put a halt to that spread and
+   execute ``async def`` code in a synchronous fashion.
+
+   .. seealso::
+
+      For the interactions between :mod:`contextvars` and greenlets.
+          :doc:`contextvars`
+
+In this example, the execution flow is: when ``read_next_char()`` is called, it
+is part of the ``g_processor`` greenlet, so when it switches to its parent
+greenlet, it resumes execution in the top-level main loop (the GUI). When
+the GUI calls ``event_keydown()``, it switches to ``g_processor``, which means that
+the execution jumps back wherever it was suspended in that greenlet |---| in
+this case, to the ``switch()`` instruction in ``read_next_char()`` |---| and the ``key``
+argument in ``event_keydown()`` is passed as the return value of the switch() in
+``read_next_char()``.
+
+Note that ``read_next_char()`` will be suspended and resumed with its call stack
+preserved, so that it will itself return to different positions in
+``process_commands()`` depending on where it was originally called from. This
+allows the logic of the program to be kept in a nice control-flow way; we
+don't have to completely rewrite ``process_commands()`` to turn it into a state
+machine.
+
+Further Reading
+===============
+
+Continue reading with :doc:`greenlet`.
+
+Curious how execution resumed in the main greenlet after
+``process_commands`` exited its loop (and never explicitly switched
+back to the main greenlet)? Read about :ref:`greenlet_parents`.
+
+.. rubric:: Footnotes
+
+.. [#f1]  You might try to run the GUI event loop in one thread, and
+          the ``process_commands`` function in another thread. You
+          could then use a thread-safe :class:`queue.Queue` to
+          exchange keypresses between the two: write to the queue in
+          ``event_keydown``, read from it in ``read_next_char``. One
+          problem with this, though, is that many GUI toolkits are
+          single-threaded and only run in the main thread, so we'd
+          also need a way to communicate any results of
+          ``process_command`` back to the main thread in order to
+          update the GUI. We're now significantly diverging from our
+          simple console-based application.