diff --git a/doc/internals/polling-states.fig b/doc/internals/polling-states.fig
new file mode 100644
index 0000000000..a2230161d3
--- /dev/null
+++ b/doc/internals/polling-states.fig
@@ -0,0 +1,114 @@
+#FIG 3.2
+Portrait
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 1125 1350 1125 1800
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 1125 2250 1125 2700
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 1125 3150 1125 3600
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 2925 3150 2925 3600
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 2925 2250 2925 2700
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 2925 1350 2925 1800
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 1575 1800 1575 1350
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 1575 3600 1575 3150
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 3375 2700 3375 2250
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 3375 1800 3375 1350
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 2700 1125 1800 1125
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 2700 3825 1800 3825
+2 4 0 1 0 7 51 -1 20 0.000 0 0 7 0 0 5
+	 3600 1350 2700 1350 2700 900 3600 900 3600 1350
+2 4 0 1 0 7 51 -1 20 0.000 0 0 7 0 0 5
+	 1800 1350 900 1350 900 900 1800 900 1800 1350
+2 4 0 1 0 7 51 -1 20 0.000 0 0 7 0 0 5
+	 1800 2250 900 2250 900 1800 1800 1800 1800 2250
+2 4 0 1 0 7 51 -1 20 0.000 0 0 7 0 0 5
+	 3600 2250 2700 2250 2700 1800 3600 1800 3600 2250
+2 4 0 1 0 7 51 -1 20 0.000 0 0 7 0 0 5
+	 3600 3150 2700 3150 2700 2700 3600 2700 3600 3150
+2 4 0 1 0 7 51 -1 20 0.000 0 0 7 0 0 5
+	 3600 4050 2700 4050 2700 3600 3600 3600 3600 4050
+2 4 0 1 0 7 51 -1 20 0.000 0 0 7 0 0 5
+	 1800 4050 900 4050 900 3600 1800 3600 1800 4050
+2 4 0 1 0 7 51 -1 20 0.000 0 0 7 0 0 5
+	 1800 3150 900 3150 900 2700 1800 2700 1800 3150
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 1800 2925 2700 2925
+2 1 0 1 0 7 50 -1 -1 0.000 1 0 -1 1 0 2
+	1 1 1.00 90.00 180.00
+	 1350 450 1350 900
+4 1 0 50 -1 16 8 0.0000 4 120 330 2250 1080 update\001
+4 1 0 50 -1 16 8 0.0000 4 120 330 2250 3780 update\001
+4 2 0 50 -1 16 8 0.0000 4 75 240 2880 1485 want\001
+4 0 0 50 -1 16 8 0.0000 4 105 210 3420 1755 stop\001
+4 0 0 50 -1 16 8 0.0000 4 120 585 3420 2610 poll()=>rdy\001
+4 2 0 50 -1 16 8 0.0000 4 75 210 2835 2385 cant\001
+4 2 0 50 -1 16 8 0.0000 4 90 285 2835 2655 done*\001
+4 2 0 50 -1 16 8 0.0000 4 90 255 2835 2520 wait*\001
+4 2 0 50 -1 16 8 0.0000 4 75 240 1080 1485 want\001
+4 0 0 50 -1 16 8 0.0000 4 105 210 1665 1755 stop\001
+4 0 0 50 -1 16 8 0.0000 4 90 240 1665 1620 done\001
+4 2 0 50 -1 16 8 0.0000 4 75 210 1035 2385 cant\001
+4 2 0 50 -1 16 8 0.0000 4 90 255 1035 2520 wait*\001
+4 2 0 50 -1 16 8 0.0000 4 105 210 1035 3285 stop\001
+4 0 0 50 -1 16 8 0.0000 4 75 240 1665 3510 want\001
+4 2 0 50 -1 16 8 0.0000 4 105 210 2835 3285 stop\001
+4 1 0 50 -1 16 10 0.0000 4 105 735 1350 1080 STOPPED\001
+4 1 0 50 -1 16 10 0.0000 4 105 630 3150 1080 PAUSED\001
+4 1 0 50 -1 16 10 0.0000 4 105 555 1350 1980 ACTIVE\001
+4 1 0 50 -1 16 10 0.0000 4 105 525 3150 1980 READY\001
+4 1 0 50 -1 16 10 0.0000 4 105 825 1350 2880 MUSTPOLL\001
+4 1 0 50 -1 16 10 0.0000 4 105 615 3150 2880 POLLED\001
+4 1 0 50 -1 16 10 0.0000 4 105 765 1350 3780 DISABLED\001
+4 1 0 50 -1 16 10 0.0000 4 105 525 3150 3780 ABORT\001
+4 1 0 50 -1 16 8 0.0000 4 105 360 1350 1260 R,!A,!P\001
+4 1 0 50 -1 16 8 0.0000 4 105 330 1350 2160 R,A,!P\001
+4 1 0 50 -1 16 8 0.0000 4 105 330 3150 1260 R,!A,P\001
+4 1 0 50 -1 16 8 0.0000 4 105 300 3150 2160 R,A,P\001
+4 1 0 50 -1 16 8 0.0000 4 105 330 3150 3060 !R,A,P\001
+4 1 0 50 -1 16 8 0.0000 4 105 360 1350 3060 !R,A,!P\001
+4 1 0 50 -1 16 8 0.0000 4 105 390 1350 3960 !R,!A,!P\001
+4 1 0 50 -1 16 8 0.0000 4 105 360 3150 3960 !R,!A,P\001
+4 1 0 50 -1 16 8 0.0000 4 120 330 2250 2880 update\001
+4 0 0 50 -1 16 10 0.0000 4 135 885 4275 1125 R=ready flag\001
+4 0 0 50 -1 16 10 0.0000 4 135 900 4275 1290 A=active flag\001
+4 0 0 50 -1 16 10 0.0000 4 135 915 4275 1455 P=polled flag\001
+4 0 0 50 -1 16 10 0.0000 4 135 2250 4275 1785 Transitions marked with a star (*)\001
+4 0 0 50 -1 16 10 0.0000 4 135 2505 4275 1950 are only possible with level-triggered\001
+4 0 0 50 -1 16 10 0.0000 4 135 495 4275 2115 pollers.\001
+4 0 0 50 -1 16 10 0.0000 4 135 1335 4275 2475 fd_want sets A flag\001
+4 0 0 50 -1 16 10 0.0000 4 135 1425 4275 2640 fd_stop clears A flag\001
+4 0 0 50 -1 16 10 0.0000 4 135 2340 4275 2805 fd_wait clears R flag on LT pollers\001
+4 0 0 50 -1 16 10 0.0000 4 135 1980 4275 3465 fd_done does what's best to\001
+4 0 0 50 -1 16 10 0.0000 4 105 2010 4455 3630 minimize the amount of work.\001
+4 0 0 50 -1 16 10 0.0000 4 135 1935 4275 3300 update() updates the poller.\001
+4 0 0 50 -1 16 10 0.0000 4 135 2145 4275 2970 fd_cant clears R flag (EAGAIN)\001
+4 0 0 50 -1 16 10 0.0000 4 135 2040 4275 3135 fd_rdy sets R flag (poll return)\001