Document QWinOverlappedIoNotifier restrictions

Change-Id: I13cd14c29ddaf4c7423d672b0551081f87d8726b
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@theqtcompany.com>

1 files changed, 16 insertions, 0 deletions

diff --git a/src/corelib/io/qwinoverlappedionotifier.cpp b/src/corelib/io/qwinoverlappedionotifier.cpp
index 0cefa374fa..dee263c664 100644
--- a/src/corelib/io/qwinoverlappedionotifier.cpp
+++ b/src/corelib/io/qwinoverlappedionotifier.cpp
@@ -75,6 +75,22 @@ QT_BEGIN_NAMESPACE
     or WriteFile() is ignored and can be used for other purposes.
 
     \warning This class is only available on Windows.
+
+    Due to peculiarities of the Windows I/O completion port API, users of
+    QWinOverlappedIoNotifier must pay attention to the following restrictions:
+    \list
+    \li File handles with a QWinOverlappedIoNotifer are assigned to an I/O
+        completion port until the handle is closed. It is impossible to
+        disassociate the file handle from the I/O completion port.
+    \li There can be only one QWinOverlappedIoNotifer per file handle. Creating
+        another QWinOverlappedIoNotifier for that file, even with a duplicated
+        handle, will fail.
+    \li Certain Windows API functions are unavailable for file handles that are
+        assigned to an I/O completion port. This includes the functions
+        \c{ReadFileEx} and \c{WriteFileEx}.
+    \endlist
+    See also the remarks in the MSDN documentation for the
+    \c{CreateIoCompletionPort} function.
 */
 
 struct IOResult