Skip to content
Back to top
View this page

# Switching Between Greenlets: Passing Objects and Control

Switches between greenlets occur when:

- The method `greenlet.switch` of a greenlet is called, in which case execution jumps to the greenlet whose `switch()` is called; or

- When the method `greenlet.throw` is used to raise an exception in the target greenlet, in which case execution jumps to the greenlet whose `throw` was called; or

- When a greenlet dies, in which case execution jumps to the parent greenlet.

During a switch, an object or an exception is “sent” to the target greenlet; this can be used as a convenient way to pass information between greenlets. For example:

    >>> from greenlet import greenlet
    >>> def test1(x, y):
    ...     z = gr2.switch(x + y)
    ...     print(z)

    >>> def test2(u):
    ...     print(u)
    ...     gr1.switch(42)

    >>> gr1 = greenlet(test1)
    >>> gr2 = greenlet(test2)
    >>> gr1.switch("hello", " world")
    hello world
    42

This prints “hello world” and 42. Note that the arguments of `test1()` and `test2()` are not provided when the greenlet is created, but only the first time someone switches to it.

Here are the precise rules for sending objects around:

`g.switch(*args, **kwargs)`

  Switches execution to the greenlet `g`, sending it the given arguments. As a special case, if `g` did not start yet, then it will start to run now; `args` and `kwargs` are passed to the greenlet’s `run()` function as its arguments.

Dying greenlet

  If a greenlet’s `run()` finishes, its return value is the object sent to its parent. If `run()` terminates with an exception, the exception is propagated to its parent (unless it is a `greenlet.GreenletExit` exception, in which case the exception object is caught and returned to the parent).

Apart from the cases described above, the target greenlet normally receives the object as the return value of the call to `switch()` in which it was previously suspended. Indeed, although a call to `switch()` does not return immediately, it will still return at some point in the future, when some other greenlet switches back. When this occurs, then execution resumes just after the `switch()` where it was suspended, and the `switch()` itself appears to return the object that was just sent. This means that `x = g.switch(y)` will send the object `y` to `g`, and will later put the (unrelated) object that some (unrelated) greenlet passes back to us into `x`.

## Multiple And Keyword Arguments

You can pass multiple or keyword arguments to `switch()`. If the greenlet hasn’t begun running, those are passed as function arguments to `run` as usual in Python. If the greenlet was running, multiple arguments will be a `tuple`, and keyword arguments will be a `dict`; any number of positional arguments with keyword arguments will have the entire set in a tuple, with positional arguments in their own nested tuple, and keyword arguments as a `dict` in the the last element of the tuple:

    >>> def test1(x, y, **kwargs):
    ...     while 1:
    ...         z = gr2.switch(x + y + ' ' + str(kwargs))
    ...         if not z: break
    ...         print(z)

    >>> def test2(u):
    ...     print(u)
    ...     # A single argument -> itself
    ...     gr1.switch(42)
    ...     # Multiple positional args -> a tuple
    ...     gr1.switch("how", "are", "you")
    ...     # Only keyword arguments -> a dict
    ...     gr1.switch(language='en')
    ...     # one positional and keywords -> ((tuple,), dict)
    ...     gr1.switch("howdy", language='en_US')
    ...     # multiple positional and keywords -> ((tuple,), dict)
    ...     gr1.switch("all", "y'all", language='en_US_OK')
    ...     gr1.switch(None) # terminate

    >>> gr1 = greenlet(test1)
    >>> gr2 = greenlet(test2)
    >>> gr1.switch("hello", " world", language='en')
    hello world {'language': 'en'}
    42
    ('how', 'are', 'you')
    {'language': 'en'}
    (('howdy',), {'language': 'en_US'})
    (('all', "y'all"), {'language': 'en_US_OK'})

## Switching To Dead Greenlets

Note that any attempt to switch to a dead greenlet actually goes to the dead greenlet’s parent, or its parent’s parent, and so on. (The final parent is the “main” greenlet, which is never dead.)

    >>> def inner():
    ...     print("Entering inner.")
    ...     print("Returning from inner.")
    ...     return 42
    >>> def outer():
    ...     print("Entering outer and spawning inner.")
    ...     inner_glet = greenlet(inner)
    ...     print("Switching to inner.")
    ...     result = inner_glet.switch()
    ...     print("Got from inner value: %s" % (result,))
    ...     print("Switching to inner again.")
    ...     result = inner_glet.switch()
    ...     print("Got from inner value: %s" % (result,))
    ...     return inner_glet
    >>> outer_glet = greenlet(outer)

Here, our main greenlet has created another greenlet (`outer`), which in turn creates a greenlet (`inner`). The outer greenlet switches to the inner greenlet, which immediately finishes and dies; the outer greenlet attempts to switch back to the inner greenlet, but since the inner greenlet is dead, it just switches…to itself (since it was the parent). Note how the second switch (to the dead greenlet) returns an empty tuple.

    >>> inner_glet = outer_glet.switch()
    Entering outer and spawning inner.
    Switching to inner.
    Entering inner.
    Returning from inner.
    Got from inner value: 42
    Switching to inner again.
    Got from inner value: ()

We can similarly ask the main greenlet to switch to the (dead) inner greenlet and its (dead) parent and wind up still in the main greenlet.

    >>> inner_glet.switch()
    ()