doc,poll: add notes (repeated cb & cancel pending cb)

Added notes to documentation of `uv_poll_t`:
- The callback will be called over-and-over again as long as the socket
remains readable/writable.
- uv_poll_stop() cancels pending callbacks of already happened events.

Fixes: https://github.com/libuv/libuv/issues/1078
PR-URL: https://github.com/libuv/libuv/pull/1100
Co-authored-by: Jameson Nash <vtjnash@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

1 files changed, 44 insertions, 17 deletions

diff --git a/docs/src/poll.rst b/docs/src/poll.rst
index aba89158..93a101ec 100644
--- a/docs/src/poll.rst
+++ b/docs/src/poll.rst
@@ -86,36 +86,63 @@ API
 .. c:function:: int uv_poll_start(uv_poll_t* handle, int events, uv_poll_cb cb)
 
     Starts polling the file descriptor. `events` is a bitmask made up of
-    UV_READABLE, UV_WRITABLE, UV_PRIORITIZED and UV_DISCONNECT. As soon as an
-    event is detected the callback will be called with `status` set to 0, and the
-    detected events set on the `events` field.
+    `UV_READABLE`, `UV_WRITABLE`, `UV_PRIORITIZED` and `UV_DISCONNECT`. As soon
+    as an event is detected the callback will be called with `status` set to 0,
+    and the detected events set on the `events` field.
 
-    The UV_PRIORITIZED event is used to watch for sysfs interrupts or TCP out-of-band
-    messages.
+    The `UV_PRIORITIZED` event is used to watch for sysfs interrupts or TCP
+    out-of-band messages.
 
-    The UV_DISCONNECT event is optional in the sense that it may not be
-    reported and the user is free to ignore it, but it can help optimize the shutdown
-    path because an extra read or write call might be avoided.
+    The `UV_DISCONNECT` event is optional in the sense that it may not be
+    reported and the user is free to ignore it, but it can help optimize the
+    shutdown path because an extra read or write call might be avoided.
 
     If an error happens while polling, `status` will be < 0 and corresponds
-    with one of the UV_E* error codes (see :ref:`errors`). The user should
+    with one of the `UV_E*` error codes (see :ref:`errors`). The user should
     not close the socket while the handle is active. If the user does that
-    anyway, the callback *may* be called reporting an error status, but this
-    is **not** guaranteed.
+    anyway, the callback *may* be called reporting an error status, but this is
+    **not** guaranteed.
 
     .. note::
-        Calling :c:func:`uv_poll_start` on a handle that is already active is fine. Doing so
-        will update the events mask that is being watched for.
+        Calling :c:func:`uv_poll_start` on a handle that is already active is
+        fine. Doing so will update the events mask that is being watched for.
 
     .. note::
-        Though UV_DISCONNECT can be set, it is unsupported on AIX and as such will not be set
-        on the `events` field in the callback.
+        Though `UV_DISCONNECT` can be set, it is unsupported on AIX and as such
+        will not be set on the `events` field in the callback.
 
-    .. versionchanged:: 1.9.0 Added the UV_DISCONNECT event.
-    .. versionchanged:: 1.14.0 Added the UV_PRIORITIZED event.
+    .. note::
+        If one of the events `UV_READABLE` or `UV_WRITABLE` are set, the
+        callback will be called again, as long as the given fd/socket remains
+        readable or writable accordingly. Particularly in each of the following
+        scenarios:
+
+        * The callback has been called because the socket became
+          readable/writable and the callback did not conduct a read/write on
+          this socket at all.
+        * The callback committed a read on the socket, and has not read all the
+          available data (when `UV_READABLE` is set).
+        * The callback committed a write on the socket, but it remained
+          writable afterwards (when `UV_WRITABLE` is set).
+        * The socket has already became readable/writable before calling
+          :c:func:`uv_poll_start` on a poll handle associated with this socket,
+          and since then the state of the socket did not changed.
+
+        In all of the above listed scenarios, the socket remains readable or
+        writable and hence the callback will be called again (depending on the
+        events set in the bitmask). This behaviour is known as level
+        triggering.
+
+    .. versionchanged:: 1.9.0 Added the `UV_DISCONNECT` event.
+    .. versionchanged:: 1.14.0 Added the `UV_PRIORITIZED` event.
 
 .. c:function:: int uv_poll_stop(uv_poll_t* poll)
 
     Stop polling the file descriptor, the callback will no longer be called.
 
+    .. note::
+        Calling :c:func:`uv_poll_stop` is effective immediately: any pending
+        callback is also canceled, even if the socket state change notification
+        was already pending.
+
 .. seealso:: The :c:type:`uv_handle_t` API functions also apply.