unix: support SO_REUSEPORT with load balancing for UDP (#4419)

Signed-off-by: Andy Pan <i@andypan.me>

2 files changed, 44 insertions, 16 deletions

diff --git a/docs/src/tcp.rst b/docs/src/tcp.rst
index 5b5453b0..571b2930 100644
--- a/docs/src/tcp.rst
+++ b/docs/src/tcp.rst
@@ -129,7 +129,8 @@ API
 
     .. 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.
+        FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ at the moment. On other platforms
+        this function will return an UV_ENOTSUP error.
 
 .. c:function:: int uv_tcp_getsockname(const uv_tcp_t* handle, struct sockaddr* name, int* namelen)
 
diff --git a/docs/src/udp.rst b/docs/src/udp.rst
index 9e075d7b..57d4c77e 100644
--- a/docs/src/udp.rst
+++ b/docs/src/udp.rst
@@ -28,19 +28,21 @@ Data types
             /* Disables dual stack mode. */
             UV_UDP_IPV6ONLY = 1,
             /*
-            * Indicates message was truncated because read buffer was too small. The
-            * remainder was discarded by the OS. Used in uv_udp_recv_cb.
-            */
+             * Indicates message was truncated because read buffer was too small. The
+             * remainder was discarded by the OS. Used in uv_udp_recv_cb.
+             */
             UV_UDP_PARTIAL = 2,
             /*
-            * Indicates if SO_REUSEADDR will be set when binding the handle in
-            * uv_udp_bind.
-            * This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other
-            * Unix platforms, it sets the SO_REUSEADDR flag. What that means is that
-            * multiple threads or processes can bind to the same address without error
-            * (provided they all set the flag) but only the last one to bind will receive
-            * any traffic, in effect "stealing" the port from the previous listener.
-            */
+             * Indicates if SO_REUSEADDR will be set when binding the handle.
+             * This sets the SO_REUSEPORT socket flag on the BSDs (except for
+             * DragonFlyBSD), OS X, and other platforms where SO_REUSEPORTs don't
+             * have the capability of load balancing, as the opposite of what
+             * UV_UDP_REUSEPORT would do. On other Unix platforms, it sets the
+             * SO_REUSEADDR flag. What that means is that multiple threads or
+             * processes can bind to the same address without error (provided
+             * they all set the flag) but only the last one to bind will receive
+             * any traffic, in effect "stealing" the port from the previous listener.
+             */
             UV_UDP_REUSEADDR = 4,
             /*
              * Indicates that the message was received by recvmmsg, so the buffer provided
@@ -62,8 +64,20 @@ Data types
              */
             UV_UDP_LINUX_RECVERR = 32,
             /*
-            * Indicates that recvmmsg should be used, if available.
-            */
+             * Indicates if SO_REUSEPORT will be set when binding the handle.
+             * This sets the SO_REUSEPORT socket option on supported platforms.
+             * Unlike UV_UDP_REUSEADDR, this flag will make multiple threads or
+             * processes that are binding to the same address and port "share"
+             * the port, which means incoming datagrams are distributed across
+             * the receiving sockets among threads or processes.
+             *
+             * 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_UDP_REUSEPORT = 64,
+            /*
+             * Indicates that recvmmsg should be used, if available.
+             */
             UV_UDP_RECVMMSG = 256
         };
 
@@ -186,11 +200,24 @@ API
         with the address and port to bind to.
 
     :param flags: Indicate how the socket will be bound,
-        ``UV_UDP_IPV6ONLY``, ``UV_UDP_REUSEADDR``, and ``UV_UDP_RECVERR``
-        are supported.
+        ``UV_UDP_IPV6ONLY``, ``UV_UDP_REUSEADDR``, ``UV_UDP_REUSEPORT``,
+        and ``UV_UDP_RECVERR`` are supported.
 
     :returns: 0 on success, or an error code < 0 on failure.
 
+    .. versionchanged:: 1.49.0 added the ``UV_UDP_REUSEPORT`` flag.
+
+    .. note::
+        ``UV_UDP_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. On other platforms
+        this function will return an UV_ENOTSUP error.
+        For platforms where `SO_REUSEPORT`s have the capability of load balancing,
+        specifying both ``UV_UDP_REUSEADDR`` and ``UV_UDP_REUSEPORT`` in flags is allowed
+        and `SO_REUSEPORT` will always override the behavior of `SO_REUSEADDR`.
+        For platforms where `SO_REUSEPORT`s don't have the capability of load balancing,
+        specifying both ``UV_UDP_REUSEADDR`` and ``UV_UDP_REUSEPORT`` in flags will fail,
+        returning an UV_ENOTSUP error.
+
 .. c:function:: int uv_udp_connect(uv_udp_t* handle, const struct sockaddr* addr)
 
     Associate the UDP handle to a remote address and port, so every