Breaking: switch to non-blocking Lwt_unix.bind

Originally requested in #230 and prepared in #296.

doc/examples/unix/relay.ml

@@ -125,7 +125,7 @@ let%lwt () =
     (* Initialize the listening address. *)
     let sock = Lwt_unix.socket Unix.PF_INET Unix.SOCK_STREAM 0 in
     Lwt_unix.setsockopt sock Unix.SO_REUSEADDR true;
-    let%lwt () = Lwt_unix.Versioned.bind_2 sock src_addr in
+    let%lwt () = Lwt_unix.bind sock src_addr in
     Lwt_unix.listen sock 1024;
 
     ignore (Lwt_log.notice "waiting for connection");

src/unix/lwt_io.ml

@@ -1511,8 +1511,8 @@ let establish_server_safe
 
   let server, started =
     establish_server_base
-      Lwt_unix.Versioned.bind_2
-      ?fd ?buffer_size ?backlog sockaddr handler in
+      Lwt_unix.bind ?fd ?buffer_size ?backlog sockaddr handler
+  in
   started >>= fun () ->
   Lwt.return server
 

src/unix/lwt_unix.cppo.ml

@@ -1606,14 +1606,10 @@ let connect ch addr =
               raise Retry
     end
 
-let bind ch addr =
-  check_descriptor ch;
-  Unix.bind ch.fd addr
-
 external bind_job : Unix.file_descr -> Unix.sockaddr -> unit job =
   "lwt_unix_bind_job"
 
-let bind' fd addr =
+let bind fd addr =
   check_descriptor fd;
   match Sys.win32, addr with
   | true, _ | false, Unix.ADDR_INET _ -> Lwt.return (Unix.bind fd.fd addr)
@@ -2371,6 +2367,9 @@ let () =
 
 module Versioned =
 struct
-  let bind_1 = bind
-  let bind_2 = bind'
+  let bind_1 ch addr =
+    check_descriptor ch;
+    Unix.bind ch.fd addr
+
+  let bind_2 = bind
 end

src/unix/lwt_unix.cppo.mli

@@ -888,24 +888,13 @@ val socket : socket_domain -> socket_type -> int -> file_descr
 val socketpair : socket_domain -> socket_type -> int -> file_descr * file_descr
   (** Wrapper for [Unix.socketpair] *)
 
-val bind : file_descr -> sockaddr -> unit
-  [@@ocaml.deprecated
-" This function will soon evaluate to a promise (-> unit Lwt.t), because the
- bind system call can block for Unix domain sockets. See
-   https://github.com/ocsigen/lwt/issues/230
- This will be a breaking change in Lwt 3.0.0.
- If you don't use Unix domain sockets and use Lwt_unix.bind ... ; rather than
- let () = Lwt_unix.bind ... in, you can ignore this warning.
- To retain the current signature, use Lwt_unix.Versioned.bind_1
- To use the new non-blocking version immediately, use Lwt_unix.Versioned.bind_2
- Both alternatives require Lwt >= 2.7.0."]
+val bind : file_descr -> sockaddr -> unit Lwt.t
 (** Binds an address to the given socket. This is the cooperative analog of
     {{:http://caml.inria.fr/pub/docs/manual-ocaml/libref/Unix.html#VALbind}
     [Unix.bind]}. See also
     {{:http://man7.org/linux/man-pages/man3/bind.3p.html} [bind(3p)]}.
 
-    @deprecated Will be replaced by {!Versioned.bind_2}, whose result type is
-      [unit Lwt.t] instead of [unit]. *)
+    @since 3.0.0 *)
 
 val listen : file_descr -> int -> unit
   (** Wrapper for [Unix.listen] *)
@@ -1432,17 +1421,21 @@ module Versioned :
 sig
   val bind_1 : file_descr -> sockaddr -> unit
     [@@ocaml.deprecated
-" Deprecated in favor of Lwt_unix.Versioned.bind_2. See
+" Deprecated in favor of Lwt_unix.bind. See
    https://github.com/ocsigen/lwt/issues/230"]
-  (** Alias for the current {!Lwt_unix.bind}.
+  (** Old version of {!Lwt_unix.bind}. The current {!Lwt_unix.bind} evaluates to
+      a promise, because the internal [bind(2)] system call can block if the
+      given socket is a Unix domain socket.
 
-      @deprecated Use {!bind_2}.
+      @deprecated Use {!Lwt_unix.bind}.
       @since 2.7.0 *)
 
   val bind_2 : file_descr -> sockaddr -> unit Lwt.t
-  (** Like {!Lwt_unix.bind}, but evaluates to an Lwt thread, in order to avoid
-      blocking the process in case the given socket is a Unix domain socket.
+    [@@ocaml.deprecated
+" In Lwt >= 3.0.0, this is an alias for Lwt_unix.bind."]
+  (** Since Lwt 3.0.0, this is just an alias for {!Lwt_unix.bind}.
 
+      @deprecated Use {!Lwt_unix.bind}.
       @since 2.7.0 *)
 end
 

tests/unix/test_lwt_unix.cppo.ml

@@ -589,7 +589,7 @@ let bind_tests = [
 
       Lwt.finalize
         (fun () ->
-          Lwt_unix.Versioned.bind_2 socket bind_tests_address >>= fun () ->
+          Lwt_unix.bind socket bind_tests_address >>= fun () ->
           Lwt.return (Unix.getsockname (Lwt_unix.unix_file_descr socket)))
         (fun () ->
           Lwt_unix.close socket)
@@ -610,7 +610,7 @@ let bind_tests = [
           let address = Unix.(ADDR_UNIX path) in
           Lwt.catch
             (fun () ->
-              Lwt_unix.Versioned.bind_2 socket address >>= fun () ->
+              Lwt_unix.bind socket address >>= fun () ->
               Lwt.return_true)
             (function
               | Unix.Unix_error (Unix.EADDRINUSE, "bind", _) -> Lwt.return_false
@@ -655,7 +655,7 @@ let bind_tests = [
       Lwt_unix.close socket >>= fun () ->
       Lwt.catch
         (fun () ->
-          Lwt_unix.Versioned.bind_2 socket bind_tests_address >>= fun () ->
+          Lwt_unix.bind socket bind_tests_address >>= fun () ->
           Lwt.return_false)
         (function
           | Unix.Unix_error (Unix.EBADF, _, _) -> Lwt.return_true
@@ -669,7 +669,7 @@ let bind_tests = [
         (fun () ->
           Lwt.catch
             (fun () ->
-              Lwt_unix.Versioned.bind_2 socket bind_tests_address >>= fun () ->
+              Lwt_unix.bind socket bind_tests_address >>= fun () ->
               Lwt.return_false)
             (function
               | Exit -> Lwt.return_true

tests/unix/test_mcast.ml

@@ -57,7 +57,7 @@ let test_mcast name join set_loop =
     let t () =
       Lwt.catch
         (fun () ->
-           Lwt_unix.(Versioned.bind_2
+           Lwt_unix.(bind
              fd1 (ADDR_INET (Unix.inet_addr_any, mcast_port))) >>= fun () ->
            let t1 = child join fd1 in
            let t2 = parent set_loop fd2 in