Breaking: switch to new Lwt_io.shutdown_server

Originally added in #259.

src/unix/lwt_io.ml

@@ -1415,9 +1415,10 @@ type server = {
   shutdown : unit Lwt.t Lazy.t;
 }
 
-let shutdown_server_2 server = Lazy.force server.shutdown
+let shutdown_server server = Lazy.force server.shutdown
 
-let shutdown_server server = Lwt.async (fun () -> shutdown_server_2 server)
+let shutdown_server_deprecated server =
+  Lwt.async (fun () -> shutdown_server server)
 
 let establish_server_base
     bind ?fd ?(buffer_size = !default_buffer_size) ?(backlog=5) sockaddr f =
@@ -1562,6 +1563,6 @@ struct
   let establish_server_1 = establish_server_deprecated
   let establish_server_2 = establish_server
 
-  let shutdown_server_1 = shutdown_server
-  let shutdown_server_2 = shutdown_server_2
+  let shutdown_server_1 = shutdown_server_deprecated
+  let shutdown_server_2 = shutdown_server
 end

src/unix/lwt_io.mli

@@ -446,21 +446,13 @@ val establish_server :
 
     @since 3.0.0 *)
 
-val shutdown_server : server -> unit
-[@@ocaml.deprecated
-" This function will soon evaluate to a promise that resolves when the close
- system call completes. This will be a breaking change in Lwt 3.0.0. See
-   https://github.com/ocsigen/lwt/issues/259
- To keep the current signature, use Lwt_io.Versioned.shutdown_server_1
- To use the new version immediately, use Lwt_io.Versioned.shutdown_server_2
- Both alternatives require Lwt >= 2.7.0."]
-  (** Closes the given server's listening socket. This function does not wait
-      for the [close] operation to actually complete. It does not affect the
-      sockets of connections that have already been accepted, i.e. passed to [f]
-      by [establish_server].
-
-      @deprecated Will be replaced by {!Versioned.shutdown_server_2}, which
-        evaluates to a thread that waits for [close] to complete. *)
+val shutdown_server : server -> unit Lwt.t
+(** Closes the given server's listening socket. The returned promise resolves
+    when the [close(2)] system call completes. This function does not affect the
+    sockets of connections that have already been accepted, i.e. passed to [f]
+    by {!establish_server}.
+
+    @since 3.0.0 *)
 
 val lines_of_file : file_name -> string Lwt_stream.t
   (** [lines_of_file name] returns a stream of all lines of the file
@@ -610,20 +602,20 @@ sig
 
   val shutdown_server_1 : server -> unit
     [@@ocaml.deprecated
-" Deprecated in favor of Lwt_io.Versioned.shutdown_server_2. See
+" Deprecated in favor of Lwt_io.shutdown_server. See
    https://github.com/ocsigen/lwt/issues/259"]
-  (** Alias for the current {!Lwt_io.shutdown_server}.
+  (** Old version of {!Lwt_io.shutdown_server}. The current
+      {!Lwt_io.shutdown_server} returns a promise, which resolves when the
+      server's listening socket is closed.
 
-      @deprecated Use {!shutdown_server_2}.
+      @deprecated Use {!Lwt_io.shutdown_server}.
       @since 2.7.0 *)
 
   val shutdown_server_2 : server -> unit Lwt.t
-  (** Closes the given server's listening socket. The thread returned by this
-      function waits for the underlying [close] system call to complete.
-
-      This function does not affect sockets of connections that have already
-      been accepted by the server, i.e. those passed by [establish_server] to
-      its callback [f].
+    [@@ocaml.deprecated
+" In Lwt >= 3.0.0, this is an alias for Lwt_io.shutdown_server."]
+  (** Since Lwt 3.0.0, this is just an alias for {!Lwt_io.shutdown_server}.
 
+      @deprecated Use {!Lwt_io.shutdown_server}.
       @since 2.7.0 *)
 end

tests/unix/test_lwt_io.ml

@@ -58,7 +58,7 @@ struct
     in
 
     client_finished >>= fun () ->
-    Lwt_io.Versioned.shutdown_server_2 server
+    Lwt_io.shutdown_server server
 
   (* Dirty hack for forcing [Lwt_io.close] to fail, to test response to [close]
      exceptions. Impolitely closes the [n]th last file descriptor allocated by
@@ -183,7 +183,7 @@ let suite = suite "lwt_io" [
 
       Lwt_io.with_connection local (fun _ -> Lwt.return_unit) >>= fun () ->
       Lwt.wakeup client_finished ();
-      Lwt_io.Versioned.shutdown_server_2 server >>= fun () ->
+      Lwt_io.shutdown_server server >>= fun () ->
       handler);
 
   (* Counterpart to establish_server: shutdown test. Confirms that shutdown is
@@ -207,7 +207,7 @@ let suite = suite "lwt_io" [
 
       >>= fun result ->
 
-      Lwt_io.Versioned.shutdown_server_2 server >|= fun () ->
+      Lwt_io.shutdown_server server >|= fun () ->
       result);
 
   test "establish_server: implicit close"
@@ -376,7 +376,7 @@ let suite = suite "lwt_io" [
         Lwt.return_unit)
 
       >>= fun () ->
-      Lwt_io.Versioned.shutdown_server_2 server >>= fun () ->
+      Lwt_io.shutdown_server server >>= fun () ->
       is_closed_in !in_channel' >>= fun in_closed ->
       is_closed_out !out_channel' >|= fun out_closed ->
       in_closed && out_closed);
@@ -414,6 +414,6 @@ let suite = suite "lwt_io" [
 
       >>= fun () ->
       Lwt.wakeup resume_server ();
-      Lwt_io.Versioned.shutdown_server_2 server >|= fun () ->
+      Lwt_io.shutdown_server server >|= fun () ->
       !exceptions_observed = 2);
 ]