|
86 | 86 | .. c:function:: int uv_poll_start(uv_poll_t* handle, int events, uv_poll_cb cb) |
87 | 87 |
|
88 | 88 | Starts polling the file descriptor. `events` is a bitmask made up of |
89 | | - UV_READABLE, UV_WRITABLE, UV_PRIORITIZED and UV_DISCONNECT. As soon as an |
90 | | - event is detected the callback will be called with `status` set to 0, and the |
91 | | - detected events set on the `events` field. |
| 89 | + `UV_READABLE`, `UV_WRITABLE`, `UV_PRIORITIZED` and `UV_DISCONNECT`. As soon |
| 90 | + as an event is detected the callback will be called with `status` set to 0, |
| 91 | + and the detected events set on the `events` field. |
92 | 92 |
|
93 | | - The UV_PRIORITIZED event is used to watch for sysfs interrupts or TCP out-of-band |
94 | | - messages. |
| 93 | + The `UV_PRIORITIZED` event is used to watch for sysfs interrupts or TCP |
| 94 | + out-of-band messages. |
95 | 95 |
|
96 | | - The UV_DISCONNECT event is optional in the sense that it may not be |
97 | | - reported and the user is free to ignore it, but it can help optimize the shutdown |
98 | | - path because an extra read or write call might be avoided. |
| 96 | + The `UV_DISCONNECT` event is optional in the sense that it may not be |
| 97 | + reported and the user is free to ignore it, but it can help optimize the |
| 98 | + shutdown path because an extra read or write call might be avoided. |
99 | 99 |
|
100 | 100 | If an error happens while polling, `status` will be < 0 and corresponds |
101 | | - with one of the UV_E* error codes (see :ref:`errors`). The user should |
| 101 | + with one of the `UV_E*` error codes (see :ref:`errors`). The user should |
102 | 102 | not close the socket while the handle is active. If the user does that |
103 | | - anyway, the callback *may* be called reporting an error status, but this |
104 | | - is **not** guaranteed. |
| 103 | + anyway, the callback *may* be called reporting an error status, but this is |
| 104 | + **not** guaranteed. |
105 | 105 |
|
106 | 106 | .. note:: |
107 | | - Calling :c:func:`uv_poll_start` on a handle that is already active is fine. Doing so |
108 | | - will update the events mask that is being watched for. |
| 107 | + Calling :c:func:`uv_poll_start` on a handle that is already active is |
| 108 | + fine. Doing so will update the events mask that is being watched for. |
109 | 109 |
|
110 | 110 | .. note:: |
111 | | - Though UV_DISCONNECT can be set, it is unsupported on AIX and as such will not be set |
112 | | - on the `events` field in the callback. |
| 111 | + Though `UV_DISCONNECT` can be set, it is unsupported on AIX and as such |
| 112 | + will not be set on the `events` field in the callback. |
113 | 113 |
|
114 | | - .. versionchanged:: 1.9.0 Added the UV_DISCONNECT event. |
115 | | - .. versionchanged:: 1.14.0 Added the UV_PRIORITIZED event. |
| 114 | + .. note:: |
| 115 | + If one of the events `UV_READABLE` or `UV_WRITABLE` are set, the |
| 116 | + callback will be called again, as long as the given fd/socket remains |
| 117 | + readable or writable accordingly. Particularly in each of the following |
| 118 | + scenarios: |
| 119 | +
|
| 120 | + * The callback has been called because the socket became |
| 121 | + readable/writable and the callback did not conduct a read/write on |
| 122 | + this socket at all. |
| 123 | + * The callback committed a read on the socket, and has not read all the |
| 124 | + available data (when `UV_READABLE` is set). |
| 125 | + * The callback committed a write on the socket, but it remained |
| 126 | + writable afterwards (when `UV_WRITABLE` is set). |
| 127 | + * The socket has already became readable/writable before calling |
| 128 | + :c:func:`uv_poll_start` on a poll handle associated with this socket, |
| 129 | + and since then the state of the socket did not changed. |
| 130 | +
|
| 131 | + In all of the above listed scenarios, the socket remains readable or |
| 132 | + writable and hence the callback will be called again (depending on the |
| 133 | + events set in the bitmask). This behaviour is known as level |
| 134 | + triggering. |
| 135 | +
|
| 136 | + .. versionchanged:: 1.9.0 Added the `UV_DISCONNECT` event. |
| 137 | + .. versionchanged:: 1.14.0 Added the `UV_PRIORITIZED` event. |
116 | 138 |
|
117 | 139 | .. c:function:: int uv_poll_stop(uv_poll_t* poll) |
118 | 140 |
|
119 | 141 | Stop polling the file descriptor, the callback will no longer be called. |
120 | 142 |
|
| 143 | + .. note:: |
| 144 | + Calling :c:func:`uv_poll_stop` is effective immediately: any pending |
| 145 | + callback is also canceled, even if the socket state change notification |
| 146 | + was already pending. |
| 147 | +
|
121 | 148 | .. seealso:: The :c:type:`uv_handle_t` API functions also apply. |