unix: support SO_REUSEPORT with load balancing for TCP

1 files changed, 46 insertions, 7 deletions

diff --git a/docs/src/tcp.rst b/docs/src/tcp.rst
index f351214f..5b5453b0 100644
--- a/docs/src/tcp.rst
+++ b/docs/src/tcp.rst
@@ -16,6 +16,28 @@ Data types
 
     TCP handle type.
 
+.. c:type:: uv_tcp_flags
+
+    Flags used in :c:func:`uv_tcp_bind`.
+
+    ::
+
+        enum uv_tcp_flags {
+            /* Used with uv_tcp_bind, when an IPv6 address is used. */
+            UV_TCP_IPV6ONLY = 1,
+
+            /* Enable SO_REUSEPORT socket option when binding the handle.
+             * This allows completely duplicate bindings by multiple processes
+             * or threads if they all set SO_REUSEPORT before binding the port.
+             * Incoming connections are distributed across the participating
+             * listener sockets.
+             *
+             * This flag is available only on Linux 3.9+, DragonFlyBSD 3.6+,
+             * FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ for now.
+             */
+            UV_TCP_REUSEPORT = 2,
+        };
+
 
 Public members
 ^^^^^^^^^^^^^^
@@ -81,16 +103,33 @@ API
 
 .. c:function:: int uv_tcp_bind(uv_tcp_t* handle, const struct sockaddr* addr, unsigned int flags)
 
-    Bind the handle to an address and port. `addr` should point to an
-    initialized ``struct sockaddr_in`` or ``struct sockaddr_in6``.
+    Bind the handle to an address and port.
 
     When the port is already taken, you can expect to see an ``UV_EADDRINUSE``
-    error from :c:func:`uv_listen` or :c:func:`uv_tcp_connect`. That is,
-    a successful call to this function does not guarantee that the call
-    to :c:func:`uv_listen` or :c:func:`uv_tcp_connect` will succeed as well.
+    error from :c:func:`uv_listen` or :c:func:`uv_tcp_connect` unless you specify
+    ``UV_TCP_REUSEPORT`` in `flags` for all the binding sockets. That is, a successful
+    call to this function does not guarantee that the call to :c:func:`uv_listen` or
+    :c:func:`uv_tcp_connect` will succeed as well.
 
-    `flags` can contain ``UV_TCP_IPV6ONLY``, in which case dual-stack support
-    is disabled and only IPv6 is used.
+    :param handle: TCP handle. It should have been initialized with :c:func:`uv_tcp_init`.
+
+    :param addr: Address to bind to. It should point to an initialized ``struct sockaddr_in``
+        or ``struct sockaddr_in6``.
+
+    :param flags: Flags that control the behavior of binding the socket.
+        ``UV_TCP_IPV6ONLY`` can be contained in `flags` to disable dual-stack
+        support and only use IPv6. 
+        ``UV_TCP_REUSEPORT`` can be contained in `flags` to enable the socket option
+        `SO_REUSEPORT` with the capability of load balancing that distribute incoming
+        connections across all listening sockets in multiple processes or threads. 
+
+    :returns: 0 on success, or an error code < 0 on failure.
+
+    .. versionchanged:: 1.49.0 added the ``UV_TCP_REUSEPORT`` flag.
+
+    .. note::
+        ``UV_TCP_REUSEPORT`` flag is available only on Linux 3.9+, DragonFlyBSD 3.6+,
+        FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ at the moment.
 
 .. c:function:: int uv_tcp_getsockname(const uv_tcp_t* handle, struct sockaddr* name, int* namelen)