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
>>> 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 (
>>> def event_keydown(key): ... "Called by the event system *asynchronously*."
In this setting, it is difficult to implement the
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
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
(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
pretty simple: just send the key the GUI gives us into the loop that
process_commands is in using
>>> 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
>>> 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
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
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
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
event_keydown() is passed as the return value of the switch() in
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
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.
You might try to run the GUI event loop in one thread, and the
process_commandsfunction in another thread. You could then use a thread-safe
queue.Queueto 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_commandback to the main thread in order to update the GUI. We’re now significantly diverging from our simple console-based application.