Merge branches/quickjs to trunk. This is the way.

git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@3621 ed5197a5-7fde-0310-b194-c3ffbd925b24

deps/libuv/docs/src/poll.rst

@@ -0,0 +1,121 @@
+
+.. _poll:
+
+:c:type:`uv_poll_t` --- Poll handle
+===================================
+
+Poll handles are used to watch file descriptors for readability,
+writability and disconnection similar to the purpose of :man:`poll(2)`.
+
+The purpose of poll handles is to enable integrating external libraries that
+rely on the event loop to signal it about the socket status changes, like
+c-ares or libssh2. Using uv_poll_t for any other purpose is not recommended;
+:c:type:`uv_tcp_t`, :c:type:`uv_udp_t`, etc. provide an implementation that is faster and
+more scalable than what can be achieved with :c:type:`uv_poll_t`, especially on
+Windows.
+
+It is possible that poll handles occasionally signal that a file descriptor is
+readable or writable even when it isn't. The user should therefore always
+be prepared to handle EAGAIN or equivalent when it attempts to read from or
+write to the fd.
+
+It is not okay to have multiple active poll handles for the same socket, this
+can cause libuv to busyloop or otherwise malfunction.
+
+The user should not close a file descriptor while it is being polled by an
+active poll handle. This can cause the handle to report an error,
+but it might also start polling another socket. However the fd can be safely
+closed immediately after a call to :c:func:`uv_poll_stop` or :c:func:`uv_close`.
+
+.. note::
+    On windows only sockets can be polled with poll handles. On Unix any file
+    descriptor that would be accepted by :man:`poll(2)` can be used.
+
+.. note::
+    On AIX, watching for disconnection is not supported.
+
+Data types
+----------
+
+.. c:type:: uv_poll_t
+
+    Poll handle type.
+
+.. c:type:: void (*uv_poll_cb)(uv_poll_t* handle, int status, int events)
+
+    Type definition for callback passed to :c:func:`uv_poll_start`.
+
+.. c:type:: uv_poll_event
+
+    Poll event types
+
+    ::
+
+        enum uv_poll_event {
+            UV_READABLE = 1,
+            UV_WRITABLE = 2,
+            UV_DISCONNECT = 4,
+            UV_PRIORITIZED = 8
+        };
+
+
+Public members
+^^^^^^^^^^^^^^
+
+N/A
+
+.. seealso:: The :c:type:`uv_handle_t` members also apply.
+
+
+API
+---
+
+.. c:function:: int uv_poll_init(uv_loop_t* loop, uv_poll_t* handle, int fd)
+
+    Initialize the handle using a file descriptor.
+
+    .. versionchanged:: 1.2.2 the file descriptor is set to non-blocking mode.
+
+.. c:function:: int uv_poll_init_socket(uv_loop_t* loop, uv_poll_t* handle, uv_os_sock_t socket)
+
+    Initialize the handle using a socket descriptor. On Unix this is identical
+    to :c:func:`uv_poll_init`. On windows it takes a SOCKET handle.
+
+    .. versionchanged:: 1.2.2 the socket is set to non-blocking mode.
+
+.. 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.
+
+    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.
+
+    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
+    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.
+
+    .. 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.
+
+    .. 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.
+
+    .. 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.
+
+.. seealso:: The :c:type:`uv_handle_t` API functions also apply.