Lwt 3.0.0 breaking changes notice

[aantron]

Lwt 3.0.0 will be released near 1 April with minor breaking changes to several APIs. This issue is for informing maintainers of OPAM packages that use those APIs.

Each API that is breaking has been given a deprecation warning in the recent 2.7.0 release. Versioned APIs are provided so you can optionally make a smooth transition. If you switch to one of the versioned APIs, you should add constraint lwt {>= "2.7.0"}. Otherwise, you should add lwt {< "3.0.0"} to your current code.

If you need to temporarily suppress a deprecation warning on an expression e, use

(e [@ocaml.warning "-3"])

I will cc the package maintainers once Lwt 2.7.0 and the factored-out packages are installable from OPAM.

---

• Lwt_unix.bind (Lwt_unix.bind should be in the monad #230, Cooperative Lwt_unix.bind (sockets) #296):

  Warning 3: deprecated: Lwt_unix.bind
   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.
  

  Since Lwt_unix.bind currently evaluates to unit, and the new bind internally has the same synchronous semantics except for Unix domain sockets, it is possible to do nothing if you are not using Unix domain sockets and use ; for sequencing bind. However, you will start getting warnings like this after Lwt 3.0.0:

  Warning 10: this expression should have type unit
  

  The semantics are not guaranteed for the future, so this is not recommended.

  Lwt_unix.bind is used in packages:

  0install arakoon bencode_rpc conduit datakit datakit-client datakit-server datakit-github dht dns-forward imaplet-lwt lwt-parallel mirage-conduit mirage-dns mirage-net mirage-net-direct mirage-net-socket mirage-tcpip-unix mirage-tcpip-xen nbd obus ocplib-concur ocsigenserver osc protocol-9p release socket-daemon tcpip tls typerex-lldb utp vhd-tool vpnkit xapi-idl xentropyd skkserv-lite tlstunnel receive-mail iocaml

---

• Lwt_io.establish_server (Safer alternative to Lwt_io.establish_server #258, Replace establish_server by establish_server_safe #260):

  Warning 3: deprecated: Lwt_io.establish_server
   The signature and semantics of this function will soon change:
   - the callback parameter f will evaluate to a promise (-> unit Lwt.t),
   - channels will be closed automatically when that promise resolves, to avoid
     leaking file descriptors, and
   - the result will be a promise (-> server Lwt.t).
   This will be breaking change in Lwt 3.0.0. See
     https://github.com/ocsigen/lwt/pull/258
   To keep the current functionality, use Lwt_io.Versioned.establish_server_1
   To use the safer version immediately, use Lwt_io.Versioned.establish_server_2
   Both alternatives require Lwt >= 2.7.0.
  

  Lwt_io.establish_server is used in packages:

  distributed imaplet-lwt mqtt usbmux

---

• Lwt_io.shutdown_server (Lwt_io.shutdown_server should evaluate to a thread #259):

  Warning 3: deprecated: Lwt_io.shutdown_server
   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.
  

  Lwt_io.shutdown_server is used in packages:

  distributed imaplet-lwt usbmux

---

• Lwt_engine.libev (Add support for selecting the libev backend #269):

  Warning 3: deprecated: Lwt_engine.libev
   This class will soon have parameters for selecting a libev backend. This will
   be a breaking change in Lwt 3.0.0. See
     https://github.com/ocsigen/lwt/pull/269
   To preserve the current signature, use Lwt_engine.Versioned.libev_1
   To use the replacement immediately, use Lwt_engine.Versioned.libev_2 ()
   Both alternatives require Lwt >= 2.7.0.
  

  Lwt_engine.libev is used in datakit.

---

• Findlib packages lwt.ssl, lwt.glib, and lwt.react are being replaced by Findlib packages lwt_ssl, lwt_glib, and lwt_react, available now in new OPAM packages with those same names. lwt.ssl, lwt.glib, and lwt.react will be removed from OPAM package lwt in 3.0.0. See Begin factoring out Lwt_ssl, Lwt_glib, Lwt_react #301.

  The old (current) package names are used in:

  0install arakoon conduit eliom imap joolog lambda-term mirage-conduit obus ocsigenserver usb xe xen-api-client

---

[aantron]

• 2.7.0 full changelog: https://github.com/ocsigen/lwt/releases/tag/2.7.0
• Roadmap: https://github.com/ocsigen/lwt/wiki/Plan#roadmap

[aantron]

cc @talex5 @domsj @toolslive @rgrinberg @c-cube @samoht @yomimono @avsm @djs55 @gregtatcam @ivg @diml @lefessan @vasilisp @johnelse @andrenth @zoggy @hannesm @pqwy @nojb @jonludlam @anyakichi @dominicjprice @essdotteedot @j0sh @fxfactorial @andrewray @vouillon @hhugo @smondet

[talex5]

Thanks @aantron - these are very clear and helpful deprecation messages :-)
I used Unix.bind (Lwt_unix.unix_file_descr socket) to avoid breaking on older versions (0install needs to build on various Linux distros against native packages, and they're often slow to upgrade).

[j0sh]

@aantron this was super helpful, thanks for the in-depth descriptions of the changes, and tagging all the relevant maintainers.

[aantron]

These changes were committed by 3.0.0. Thanks to all downstream maintainers.

Note that it is still possible to use the pre-3.0.0 APIs, by using the old versioned names (see issue main comment). However, users are encouraged to gradually switch to the 3.0.0 APIs.