Update comments to clarify the impact of the AFD_IOCTL_POLL bug

njsmith · njsmith · commit 7818f5893262 · 2019-10-29T12:00:10.000-07:00
diff --git a/notes-to-self/afd-lab.py b/notes-to-self/afd-lab.py
@@ -14,6 +14,9 @@
 #
 # ...then the SEND poll operation completes with the RECEIVE flag set.
 #
+# (This bug is why our Windows backend jumps through hoops to avoid ever
+# issuing multiple polls simultaneously for the same socket.)
+#
 # This script's output on my machine:
 #
 # -- Iteration start --
diff --git a/trio/_core/_io_windows.py b/trio/_core/_io_windows.py
@@ -125,9 +125,12 @@
 # which events happened, and uses IOCP as normal to notify us that this
 # operation has completed.
 #
-# There's some trickiness required to handle multiple tasks that are waiting
-# on the same socket simultaneously, so instead of using the wait_overlapped
-# machinery, we have some dedicated code to handle these operations, and a
+# Unfortunately, the Windows kernel seems to have bugs if you try to issue
+# multiple simultaneous IOCTL_AFD_POLL operations on the same socket (see
+# notes-to-self/afd-lab.py). So if a user calls wait_readable and
+# wait_writable at the same time, we have to combine those into a single
+# IOCTL_AFD_POLL. This means we can't just use the wait_overlapped machinery.
+# Instead we have some dedicated code to handle these operations, and a
 # dedicated completion key CKeys.AFD_POLL.
 #
 # Sources of information:
@@ -139,7 +142,8 @@
 #   https://github.com/pustladi/Windows-2000/blob/661d000d50637ed6fab2329d30e31775046588a9/private/net/sockets/winsock2/wsp/msafd/select.c#L59-L655
 #   https://github.com/metoo10987/WinNT4/blob/f5c14e6b42c8f45c20fe88d14c61f9d6e0386b8e/private/ntos/afd/poll.c#L68-L707
 # - The WSAEventSelect docs (this exposes a finer-grained set of events than
-#   select())
+#   select(), so if you squint you can treat it as a source of information on
+#   the fine-grained AFD poll types)
 #
 #
 # == Everything else ==

Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,9 @@`
`14`	`14`	`#`
`15`	`15`	`# ...then the SEND poll operation completes with the RECEIVE flag set.`
`16`	`16`	`#`
	`17`	`+# (This bug is why our Windows backend jumps through hoops to avoid ever`
	`18`	`+# issuing multiple polls simultaneously for the same socket.)`
	`19`	`+#`
`17`	`20`	`# This script's output on my machine:`
`18`	`21`	`#`
`19`	`22`	`# -- Iteration start --`