File: index.rst

package info (click to toggle)
python-greenlet 3.1.0-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 1,032 kB
  • sloc: cpp: 5,045; python: 3,160; ansic: 1,125; makefile: 155; asm: 120; sh: 42
file content (156 lines) | stat: -rw-r--r-- 5,431 bytes parent folder | download | duplicates (2)
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
==============================================
 greenlet: Lightweight concurrent programming
==============================================

..
   TODO: Divide into a few different kinds of documentation
   (https://documentation.divio.com/explanation/):

   - Tutorial,
   - API reference
   - how-to.
   - Explanation.

   Each document should identify what role it fulfills.

.. |--| unicode:: U+2013   .. en dash
.. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
   :trim:

.. sidebar:: Contents

   If this page has piqued your interest in greenlets,
   continue reading by seeing :ref:`an example transforming an
   asynchronous GUI into a simple synchronous loop <gui_example>`.

   To get started building your own code with greenlets, read
   :doc:`greenlet`, and then :doc:`creating_executing_greenlets`.

   .. toctree::
      :caption: Getting Started
      :maxdepth: 2

      gui_example
      greenlet
      creating_executing_greenlets
      switching

   .. toctree::
      :maxdepth: 1
      :caption: Reference Material

      api
      c_api
      changes
      development
      history

   .. toctree::
      :maxdepth: 1
      :caption: Advanced Usage

      python_threads
      contextvars
      greenlet_gc
      tracing
      caveats

.. rubric:: What are greenlets?

greenlets are lightweight coroutines for in-process sequential concurrent
programming.

greenlets can be used on their own, but they are frequently used with
frameworks such as `gevent`_ to provide higher-level abstractions and
asynchronous I/O.

greenlets are frequently defined by analogy to :mod:`threads
<threading>` or Python's built-in coroutines (generators and ``async
def`` functions). The rest of this section will explore those
analogies. For a more precise introduction, see :ref:`what_is_greenlet`.

See :doc:`history` for how the greenlet library was created, and its
relation to other similar concepts.

.. rubric:: Are greenlets similar to threads?

For many purposes, you can usually think of greenlets as cooperatively
scheduled :mod:`threads <threading>`. The major differences are
that since they're cooperatively scheduled, you are in control of
when they execute, and since they are coroutines, many greenlets can
exist in a single native thread.

.. rubric:: How are greenlets different from threads?

Threads (in theory) are preemptive and parallel [#f1]_, meaning that multiple
threads can be processing work at the same time, and it's impossible
to say in what order different threads will proceed or see the effects
of other threads. This necessitates careful programming using
:class:`locks <threading.Lock>`, :class:`queues <queue.Queue>`, or
other approaches to avoid `race conditions`_, `deadlocks`_, or other
bugs.

In contrast, greenlets are cooperative and sequential. This means that
when one greenlet is running, no other greenlet can be running; the
programmer is fully in control of when execution switches between
greenlets. This can eliminate race conditions and greatly simplify the
programming task.

Also, threads require resources from the operating system (the thread
stack, and bookkeeping in the kernel). Because greenlets are
implemented entirely without involving the operating system, they can
require fewer resources; it is often practical to have many more
greenlets than it is threads.

.. _race conditions: https://en.wikipedia.org/wiki/Race_condition
.. _deadlocks: https://docs.microsoft.com/en-us/troubleshoot/dotnet/visual-basic/race-conditions-deadlocks#when-deadlocks-occur

.. rubric:: How else can greenlets be used?

greenlets have many uses:

- They can be treated like cooperative threads. You can implement any
  scheduling policy you desire.
- Because greenlets work well with C libraries (greenlets can switch
  even with C functions in the call stack), they are well suited for
  integrating with GUIs or other event loops.

  `gevent`_ is an example of using greenlets to integrate with IO
  event loops (`libev`_ and `libuv`_) to provide a complete
  asynchronous environment using familiar programming patterns.
- Similar to the above, greenlets can be used to transform apparently
  asynchronous tasks into a simple synchronous style. See
  :ref:`gui_example` for an example of writing an asynchronous event-driven GUI app
  in a simple synchronous style.
- In general, greenlets can be used for advanced control flow. For
  example, you can :doc:`create generators <history>` |---| without
  the use of the ``yield`` keyword!


.. _gevent: https://www.gevent.org
.. _libev: http://software.schmorp.de/pkg/libev.html
.. _libuv: http://libuv.org/

.. rubric:: Are greenlets similar to generators? What about asyncio?

All three of greenlets, generators, and asyncio use a concept of
coroutines. However, greenlets, unlike the other two, require no
special keywords or support from the Python language. In addition,
greenlets are capable of switching between stacks that feature C
libraries, whereas the other two are not.


.. rubric:: Footnotes

.. [#f1] In CPython, the `global interpreter lock (GIL)
         <https://wiki.python.org/moin/GlobalInterpreterLock>`_
         generally prevents two threads from executing Python code at
         the same time. Parallelism is thus limited to code sections
         that release the GIL, i.e., C code.

Indices and tables
==================

* :ref:`search`
* :ref:`genindex`
* :ref:`modindex`