1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
.. _switching:
==========================================================
Switching Between Greenlets: Passing Objects and Control
==========================================================
.. This is an "explanation" document.
.. currentmodule:: greenlet
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:
.. doctest::
>>> 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 :class:`tuple`, and keyword arguments will be a
:class:`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:
.. doctest::
>>> 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'})
.. _switch_to_dead:
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.)
.. doctest::
>>> 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.
.. doctest::
>>> 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()
()
|
