twisted.internet.asyncioreactor.AsyncioSelectorReactor(PosixReactorBase) class documentation

Compensate for a bug in asyncio where it will not unregister a FD that it cannot handle in the epoll loop. It touches internal asyncio code.

A description of the bug by markrwilliams:

The add_writer method of asyncio event loops isn't atomic because all the Selector classes in the selector module internally record a file object before passing it to the platform's selector implementation. If the platform's selector decides the file object isn't acceptable, the resulting exception doesn't cause the Selector to un-track the file object.

The failing/hanging stdio test goes through the following sequence of events (roughly):

* The first connection.write(intToByte(value)) call hits the asyncio reactor's addWriter method.

* addWriter calls the asyncio loop's add_writer method, which happens to live on _BaseSelectorEventLoop.

* The asyncio loop's add_writer method checks if the file object has been registered before via the selector's get_key method.

* It hasn't, so the KeyError block runs and calls the selector's register method

* Code examples that follow use EpollSelector, but the code flow holds true for any other selector implementation. The selector's register method first calls through to the next register method in the MRO

* That next method is always _BaseSelectorImpl.register which creates a SelectorKey instance for the file object, stores it under the file object's file descriptor, and then returns it.

* Control returns to the concrete selector implementation, which asks the operating system to track the file descriptor using the right API.

* The operating system refuses! An exception is raised that, in this case, the asyncio reactor handles by creating a _ContinuousPolling object to watch the file descriptor.

* The second connection.write(intToByte(value)) call hits the asyncio reactor's addWriter method, which hits the add_writer method. But the loop's selector's get_key method now returns a SelectorKey! Now the asyncio reactor's addWriter method thinks the asyncio loop will watch the file descriptor, even though it won't.