Motivation: Treating an Asynchronous GUI Like a Synchronous Loop

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.

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:

>>> 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():

>>> 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 sys.stdin, or by something more complex such as 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)).

>>> 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 threads [1], 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).

>>> 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 greenlet.switch().

>>> 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:

>>> 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:

>>> 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.

>>> 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

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 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.

See also

For the interactions between contextvars and greenlets.

Context Variables (asyncio)

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 greenlet Concepts.

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 Greenlet Parents.

Footnotes

[1]

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 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.