greenlet.txt 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384
  1. =====================================================
  2. greenlet: Lightweight concurrent programming
  3. =====================================================
  4. .. contents::
  5. .. sectnum::
  6. Motivation
  7. ==========
  8. The "greenlet" package is a spin-off of `Stackless`_, a version of CPython
  9. that supports micro-threads called "tasklets". Tasklets run
  10. pseudo-concurrently (typically in a single or a few OS-level threads) and
  11. are synchronized with data exchanges on "channels".
  12. A "greenlet", on the other hand, is a still more primitive notion of
  13. micro-thread with no implicit scheduling; coroutines, in other words.
  14. This is useful when you want to
  15. control exactly when your code runs. You can build custom scheduled
  16. micro-threads on top of greenlet; however, it seems that greenlets are
  17. useful on their own as a way to make advanced control flow structures.
  18. For example, we can recreate generators; the difference with Python's own
  19. generators is that our generators can call nested functions and the nested
  20. functions can yield values too. (Additionally, you don't need a "yield"
  21. keyword. See the example in ``test/test_generator.py``).
  22. Greenlets are provided as a C extension module for the regular unmodified
  23. interpreter.
  24. .. _`Stackless`: http://www.stackless.com
  25. Example
  26. -------
  27. Let's consider a system controlled by a terminal-like console, where the user
  28. types commands. Assume that the input comes character by character. In such
  29. a system, there will typically be a loop like the following one::
  30. def process_commands(*args):
  31. while True:
  32. line = ''
  33. while not line.endswith('\n'):
  34. line += read_next_char()
  35. if line == 'quit\n':
  36. print "are you sure?"
  37. if read_next_char() != 'y':
  38. continue # ignore the command
  39. process_command(line)
  40. Now assume that you want to plug this program into a GUI. Most GUI toolkits
  41. are event-based. They will invoke a call-back for each character the user
  42. presses. [Replace "GUI" with "XML expat parser" if that rings more bells to
  43. you ``:-)``] In this setting, it is difficult to implement the
  44. read_next_char() function needed by the code above. We have two incompatible
  45. functions::
  46. def event_keydown(key):
  47. ??
  48. def read_next_char():
  49. ?? should wait for the next event_keydown() call
  50. You might consider doing that with threads. Greenlets are an alternate
  51. solution that don't have the related locking and shutdown problems. You
  52. start the process_commands() function in its own, separate greenlet, and
  53. then you exchange the keypresses with it as follows::
  54. def event_keydown(key):
  55. # jump into g_processor, sending it the key
  56. g_processor.switch(key)
  57. def read_next_char():
  58. # g_self is g_processor in this simple example
  59. g_self = greenlet.getcurrent()
  60. # jump to the parent (main) greenlet, waiting for the next key
  61. next_char = g_self.parent.switch()
  62. return next_char
  63. g_processor = greenlet(process_commands)
  64. g_processor.switch(*args) # input arguments to process_commands()
  65. gui.mainloop()
  66. In this example, the execution flow is: when read_next_char() is called, it
  67. is part of the g_processor greenlet, so when it switches to its parent
  68. greenlet, it resumes execution in the top-level main loop (the GUI). When
  69. the GUI calls event_keydown(), it switches to g_processor, which means that
  70. the execution jumps back wherever it was suspended in that greenlet -- in
  71. this case, to the switch() instruction in read_next_char() -- and the ``key``
  72. argument in event_keydown() is passed as the return value of the switch() in
  73. read_next_char().
  74. Note that read_next_char() will be suspended and resumed with its call stack
  75. preserved, so that it will itself return to different positions in
  76. process_commands() depending on where it was originally called from. This
  77. allows the logic of the program to be kept in a nice control-flow way; we
  78. don't have to completely rewrite process_commands() to turn it into a state
  79. machine.
  80. Usage
  81. =====
  82. Introduction
  83. ------------
  84. A "greenlet" is a small independent pseudo-thread. Think about it as a
  85. small stack of frames; the outermost (bottom) frame is the initial
  86. function you called, and the innermost frame is the one in which the
  87. greenlet is currently paused. You work with greenlets by creating a
  88. number of such stacks and jumping execution between them. Jumps are never
  89. implicit: a greenlet must choose to jump to another greenlet, which will
  90. cause the former to suspend and the latter to resume where it was
  91. suspended. Jumping between greenlets is called "switching".
  92. When you create a greenlet, it gets an initially empty stack; when you
  93. first switch to it, it starts the run a specified function, which may call
  94. other functions, switch out of the greenlet, etc. When eventually the
  95. outermost function finishes its execution, the greenlet's stack becomes
  96. empty again and the greenlet is "dead". Greenlets can also die of an
  97. uncaught exception.
  98. For example::
  99. from greenlet import greenlet
  100. def test1():
  101. print 12
  102. gr2.switch()
  103. print 34
  104. def test2():
  105. print 56
  106. gr1.switch()
  107. print 78
  108. gr1 = greenlet(test1)
  109. gr2 = greenlet(test2)
  110. gr1.switch()
  111. The last line jumps to test1, which prints 12, jumps to test2, prints 56,
  112. jumps back into test1, prints 34; and then test1 finishes and gr1 dies.
  113. At this point, the execution comes back to the original ``gr1.switch()``
  114. call. Note that 78 is never printed.
  115. Parents
  116. -------
  117. Let's see where execution goes when a greenlet dies. Every greenlet has a
  118. "parent" greenlet. The parent greenlet is initially the one in which the
  119. greenlet was created (this can be changed at any time). The parent is
  120. where execution continues when a greenlet dies. This way, greenlets are
  121. organized in a tree. Top-level code that doesn't run in a user-created
  122. greenlet runs in the implicit "main" greenlet, which is the root of the
  123. tree.
  124. In the above example, both gr1 and gr2 have the main greenlet as a parent.
  125. Whenever one of them dies, the execution comes back to "main".
  126. Uncaught exceptions are propagated into the parent, too. For example, if
  127. the above test2() contained a typo, it would generate a NameError that
  128. would kill gr2, and the exception would go back directly into "main".
  129. The traceback would show test2, but not test1. Remember, switches are not
  130. calls, but transfer of execution between parallel "stack containers", and
  131. the "parent" defines which stack logically comes "below" the current one.
  132. Instantiation
  133. -------------
  134. ``greenlet.greenlet`` is the greenlet type, which supports the following
  135. operations:
  136. ``greenlet(run=None, parent=None)``
  137. Create a new greenlet object (without running it). ``run`` is the
  138. callable to invoke, and ``parent`` is the parent greenlet, which
  139. defaults to the current greenlet.
  140. ``greenlet.getcurrent()``
  141. Returns the current greenlet (i.e. the one which called this
  142. function).
  143. ``greenlet.GreenletExit``
  144. This special exception does not propagate to the parent greenlet; it
  145. can be used to kill a single greenlet.
  146. The ``greenlet`` type can be subclassed, too. A greenlet runs by calling
  147. its ``run`` attribute, which is normally set when the greenlet is
  148. created; but for subclasses it also makes sense to define a ``run`` method
  149. instead of giving a ``run`` argument to the constructor.
  150. Switching
  151. ---------
  152. Switches between greenlets occur when the method switch() of a greenlet is
  153. called, in which case execution jumps to the greenlet whose switch() is
  154. called, or when a greenlet dies, in which case execution jumps to the
  155. parent greenlet. During a switch, an object or an exception is "sent" to
  156. the target greenlet; this can be used as a convenient way to pass
  157. information between greenlets. For example::
  158. def test1(x, y):
  159. z = gr2.switch(x+y)
  160. print z
  161. def test2(u):
  162. print u
  163. gr1.switch(42)
  164. gr1 = greenlet(test1)
  165. gr2 = greenlet(test2)
  166. gr1.switch("hello", " world")
  167. This prints "hello world" and 42, with the same order of execution as the
  168. previous example. Note that the arguments of test1() and test2() are not
  169. provided when the greenlet is created, but only the first time someone
  170. switches to it.
  171. Here are the precise rules for sending objects around:
  172. ``g.switch(*args, **kwargs)``
  173. Switches execution to the greenlet ``g``, sending it the given
  174. arguments. As a special case, if ``g`` did not start yet, then it
  175. will start to run now.
  176. Dying greenlet
  177. If a greenlet's ``run()`` finishes, its return value is the object
  178. sent to its parent. If ``run()`` terminates with an exception, the
  179. exception is propagated to its parent (unless it is a
  180. ``greenlet.GreenletExit`` exception, in which case the exception
  181. object is caught and *returned* to the parent).
  182. Apart from the cases described above, the target greenlet normally
  183. receives the object as the return value of the call to ``switch()`` in
  184. which it was previously suspended. Indeed, although a call to
  185. ``switch()`` does not return immediately, it will still return at some
  186. point in the future, when some other greenlet switches back. When this
  187. occurs, then execution resumes just after the ``switch()`` where it was
  188. suspended, and the ``switch()`` itself appears to return the object that
  189. was just sent. This means that ``x = g.switch(y)`` will send the object
  190. ``y`` to ``g``, and will later put the (unrelated) object that some
  191. (unrelated) greenlet passes back to us into ``x``.
  192. Note that any attempt to switch to a dead greenlet actually goes to the
  193. dead greenlet's parent, or its parent's parent, and so on. (The final
  194. parent is the "main" greenlet, which is never dead.)
  195. Methods and attributes of greenlets
  196. -----------------------------------
  197. ``g.switch(*args, **kwargs)``
  198. Switches execution to the greenlet ``g``. See above.
  199. ``g.run``
  200. The callable that ``g`` will run when it starts. After ``g`` started,
  201. this attribute no longer exists.
  202. ``g.parent``
  203. The parent greenlet. This is writeable, but it is not allowed to
  204. create cycles of parents.
  205. ``g.gr_frame``
  206. The current top frame, or None.
  207. ``g.dead``
  208. True if ``g`` is dead (i.e. it finished its execution).
  209. ``bool(g)``
  210. True if ``g`` is active, False if it is dead or not yet started.
  211. ``g.throw([typ, [val, [tb]]])``
  212. Switches execution to the greenlet ``g``, but immediately raises the
  213. given exception in ``g``. If no argument is provided, the exception
  214. defaults to ``greenlet.GreenletExit``. The normal exception
  215. propagation rules apply, as described above. Note that calling this
  216. method is almost equivalent to the following::
  217. def raiser():
  218. raise typ, val, tb
  219. g_raiser = greenlet(raiser, parent=g)
  220. g_raiser.switch()
  221. except that this trick does not work for the
  222. ``greenlet.GreenletExit`` exception, which would not propagate
  223. from ``g_raiser`` to ``g``.
  224. Greenlets and Python threads
  225. ----------------------------
  226. Greenlets can be combined with Python threads; in this case, each thread
  227. contains an independent "main" greenlet with a tree of sub-greenlets. It
  228. is not possible to mix or switch between greenlets belonging to different
  229. threads.
  230. Garbage-collecting live greenlets
  231. ---------------------------------
  232. If all the references to a greenlet object go away (including the
  233. references from the parent attribute of other greenlets), then there is no
  234. way to ever switch back to this greenlet. In this case, a GreenletExit
  235. exception is generated into the greenlet. This is the only case where a
  236. greenlet receives the execution asynchronously. This gives
  237. ``try:finally:`` blocks a chance to clean up resources held by the
  238. greenlet. This feature also enables a programming style in which
  239. greenlets are infinite loops waiting for data and processing it. Such
  240. loops are automatically interrupted when the last reference to the
  241. greenlet goes away.
  242. The greenlet is expected to either die or be resurrected by having a new
  243. reference to it stored somewhere; just catching and ignoring the
  244. GreenletExit is likely to lead to an infinite loop.
  245. Greenlets do not participate in garbage collection; cycles involving data
  246. that is present in a greenlet's frames will not be detected. Storing
  247. references to other greenlets cyclically may lead to leaks.
  248. C API Reference
  249. ===============
  250. Greenlets can be created and manipulated from extension modules written in C or
  251. C++, or from applications that embed Python. The ``greenlet.h`` header is
  252. provided, and exposes the entire API available to pure Python modules.
  253. Types
  254. -----
  255. +--------------------+-------------------+
  256. | Type name | Python name |
  257. +====================+===================+
  258. | PyGreenlet | greenlet.greenlet |
  259. +--------------------+-------------------+
  260. Exceptions
  261. ----------
  262. +---------------------+-----------------------+
  263. | Type name | Python name |
  264. +=====================+=======================+
  265. | PyExc_GreenletError | greenlet.error |
  266. +---------------------+-----------------------+
  267. | PyExc_GreenletExit | greenlet.GreenletExit |
  268. +---------------------+-----------------------+
  269. Reference
  270. ---------
  271. ``PyGreenlet_Import()``
  272. A macro that imports the greenlet module and initializes the C API. This
  273. must be called once for each extension module that uses the greenlet C API.
  274. ``int PyGreenlet_Check(PyObject *p)``
  275. Macro that returns true if the argument is a PyGreenlet.
  276. ``int PyGreenlet_STARTED(PyGreenlet *g)``
  277. Macro that returns true if the greenlet ``g`` has started.
  278. ``int PyGreenlet_ACTIVE(PyGreenlet *g)``
  279. Macro that returns true if the greenlet ``g`` has started and has not died.
  280. ``PyGreenlet *PyGreenlet_GET_PARENT(PyGreenlet *g)``
  281. Macro that returns the parent greenlet of ``g``.
  282. ``PyGreenlet *PyGreenlet_SetParent(PyGreenlet *g)``
  283. Set the parent greenlet of ``g``. Returns 0 for success. If -1 is returned,
  284. then ``g`` is not a pointer to a PyGreenlet, and an AttributeError will
  285. be raised.
  286. ``PyGreenlet *PyGreenlet_GetCurrent(void)``
  287. Returns the currently active greenlet object.
  288. ``PyGreenlet *PyGreenlet_New(PyObject *run, PyObject *parent)``
  289. Creates a new greenlet object with the callable ``run`` and parent
  290. ``parent``. Both parameters are optional. If ``run`` is NULL, then the
  291. greenlet will be created, but will fail if switched in. If ``parent`` is
  292. NULL, the parent is automatically set to the current greenlet.
  293. ``PyGreenlet *PyGreenlet_Switch(PyGreenlet *g, PyObject *args, PyObject *kwargs)``
  294. Switches to the greenlet ``g``. ``args`` and ``kwargs`` are optional and
  295. can be NULL. If ``args`` is NULL, an empty tuple is passed to the target
  296. greenlet. If kwargs is NULL, no keyword arguments are passed to the target
  297. greenlet. If arguments are specified, ``args`` should be a tuple and
  298. ``kwargs`` should be a dict.
  299. ``PyObject *PyGreenlet_Throw(PyGreenlet *g, PyObject *typ, PyObject *val, PyObject *tb)``
  300. Switches to greenlet ``g``, but immediately raise an exception of type
  301. ``typ`` with the value ``val``, and optionally, the traceback object
  302. ``tb``. ``tb`` can be NULL.