Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 8b28c01

Browse files
tacaswelltacaswell
committed
DOC/WIP: updates to docs on how event loops work
1 parent fa36c95 commit 8b28c01

File tree

1 file changed

+104
-12
lines changed

1 file changed

+104
-12
lines changed

‎doc/users/interactive_guide.rst

Lines changed: 104 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _plotting-guide-interactive:
22

3-
*******************
4-
Interactive Figures
5-
*******************
3+
************************************************
4+
Interactive Figures and Asynchronous Programming
5+
************************************************
66

77
One of the most powerful uses of matplotlib is interactive
88
figures. At the most basic matplotlib has the ability to zoom and pan
@@ -15,9 +15,51 @@ of integrating the matplotlib with a GUI event loop. For further
1515
details see `Interactive Applications using Matplotlib
1616
<http://www.amazon.com/Interactive-Applications-using-Matplotlib-Benjamin/dp/1783988843>`__.
1717

18+
Fundamentally, all user interaction (and networking) is implemented as
19+
an infinite loop waiting for events from the OS and then doing
20+
something about it. For example, a minimal Read Evaluate Print Loop
21+
(REPL) is ::
22+
23+
exec_count = 0
24+
while True:
25+
inp = input(f"[{exec_count}] > ") # Read
26+
ret = eval(inp) # Evaluate
27+
print(ret) # Print
28+
exec_count += 1 # Loop
29+
30+
31+
This is missing many niceties (for example, it exits on the first
32+
exception!), but is representative of the event loops that underlie
33+
all terminals, GUIs, and servers [#f1]_. In general the *Read* step is
34+
waiting on some sort of I/O, be it user input from a keyboard or mouse
35+
or the network while the *Evaluate* and *Print* are responsible for
36+
interpreting the input and then doing something about it.
37+
38+
In practice most users do not work directly with these loops, and
39+
instead framework that provides a mechanism to register callbacks
40+
[#2]_. This allows users to write reactive, event-driven, programs
41+
without having to delve into the nity-grity [#f3]_ details of I/O.
42+
Examples include ``observe`` and friends in `traitlets`, the
43+
``Signal`` / ``Slot`` framework in Qt and the analogs in Gtk / Tk /
44+
Wx, the request functions in web frameworks, or Matplotlib's
45+
native :ref:`event handling system <event-handling-tutorial>`.
46+
47+
48+
49+
references to trackdown:
50+
- link to cpython REPL loop
51+
- curio / trio / asycio / twisted / tornado event loops
52+
- Beazly talk or two on asyncio
1853

19-
The GUI event loop
20-
------------------
54+
55+
GUI to Matplotlib Bridge
56+
------------------------
57+
58+
When using
59+
60+
61+
Command Prompt
62+
--------------
2163

2264
To handle asynchronous user input every GUI framework has an event
2365
loop. At the most basic this is a stack that can have events to be
@@ -27,11 +69,38 @@ run. To manage this in python there are two basic methods:
2769
1. let the GUI main loop block the python process
2870
2. intermittently run the GUI loop for a period of time
2971

30-
Going with option 1 is going down the route of writing a bespoke GUI
31-
application. In this case, commonly refereed to as 'embedding', the
32-
GUI event loop is running the show and you should not use the `pyplot`
33-
layer. Doing anything short of writing a full GUI application
34-
requires option 2.
72+
73+
Blocking
74+
********
75+
76+
77+
Interactive
78+
***********
79+
80+
Scripts
81+
-------
82+
83+
- if you want always reactive figures while the script runs, you have to
84+
call `flush_event`
85+
- if you want to have reactive figures that block the script until they are closed (ex for
86+
collecting user input before continuing use
87+
88+
89+
Full embedding
90+
--------------
91+
92+
- just let the underlying GUI event loop handle eve
93+
94+
Web
95+
---
96+
97+
The Weeds
98+
=========
99+
100+
101+
The GUI event loop
102+
------------------
103+
35104

36105
The python capi provides a hook, `PyOS_InputHook`, to register a
37106
function to be run "The function will be called when Python's
@@ -68,7 +137,7 @@ rendering of the figure until the GUI is ready to update its
68137
on-screen representation.
69138

70139
Stale Artists
71-
-------------
140+
=============
72141

73142
Artists (as of 1.5) have a ``stale`` attribute which is `True` if the
74143
internal state of the artist has changed since the last time it was
@@ -85,4 +154,27 @@ Interactive Mode
85154

86155

87156
Blitting
88-
--------
157+
========
158+
159+
160+
.. ruberic:: Fotenotes
161+
162+
.. [#f1] A limitation of this design is that you can only wait for one
163+
input, if there is a need to multiplex between multiple sources
164+
then the loop would look something like ::
165+
166+
fds = [...]
167+
while True: # Loop
168+
inp = select(fds) # Read
169+
eval(inp) # Evaluate / Print
170+
171+
172+
.. [#f2] asyncio has a fundamentally different paradigm that uses
173+
coroutines instead of callbacks as the user-facing interface,
174+
however at the core there is a select loop like the above
175+
footnote the multiplexes between the running tasks.
176+
177+
.. [#f3] These examples are agressively dropping many of the
178+
complexities that must be dealt with in the real world such as
179+
keyboard interupts [link], timeouts, bad input, resource
180+
allocation and cleanup, etc.

0 commit comments

Comments
 (0)