Lwt cooperative cancellation vs Async with_timeout for reliable file descriptor closure on timeout

Answer the question first

For an operation that opens a file descriptor, Async’s with_timeout guarantees the descriptor is closed before the timeout handler continues—provided the I/O uses Async’s cancellable primitives. Lwt’s cooperative cancellation only guarantees closure if you explicitly cancel the promise and attach a finally block (or Lwt.finalize) that closes the descriptor. Without those, the descriptor may remain open until the promise settles or the GC runs.

Likely explanation

• Lwt – Cancellation is cooperative. If the promise is blocked on a system call that does not honor cancellation, the file descriptor stays open until the call returns. Finalizers are not automatically run on cancellation; you must wrap the I/O in Lwt.finalize or a try…with…finally block.
• Async – with_timeout internally creates a deferred that is cancelled after the timeout. Async’s runtime runs any finalizers attached to the I/O resource when the deferred is cancelled, so the descriptor is closed before the timeout handler runs. If the underlying I/O does not register a finalizer, the descriptor may leak; in that case you still need an explicit finally block.
• Effect-based handlers – Deterministic release, but require the –effects compiler flag and limited library support, so they are not widely applicable.

Confirmed facts (from OCaml library docs)

• Async’s with_timeout runs the supplied function and, if the timeout elapses, cancels the deferred and runs any registered finalizers immediately.
• Lwt’s cancellation does not automatically invoke finalizers; developers must explicitly attach cleanup logic.
• Both libraries require the I/O operation itself to be cancellable; blocking system calls that ignore cancellation defeat the timeout mechanism.

Practical steps for this case

1. Open the file descriptor using the library’s I/O primitive (e.g., Async.Unix.openfile or Lwt_unix.openfile).

2. Wrap the read/write operation in a timeout guard:

   • For Async: let%bind _ = Async.with_timeout 5.0 (fun () -> Async.Unix.read fd buf 0 len)
   • For Lwt: let promise = Lwt_unix.read fd buf 0 len in Lwt.pick [promise; Lwt_unix.sleep 5.0 |> Lwt.map (fun () -> Lwt.fail Timeout)]

3. Attach a cleanup block:

   • Async: Async.finalize (fun () -> Async.Unix.close fd) (fun () -> …)
   • Lwt: Lwt.finalize (fun () -> Lwt_unix.close fd) (fun () -> …)

4. Verify that the descriptor count drops after the timeout by running lsof -p $$ or inspecting /proc/self/fd before and after the operation.

Ask for missing diagnostic detail

Do you use the native Lwt_unix blocking calls or a library that already provides cancellation support? Knowing this will tell us whether the timeout guard alone is sufficient or if you need an explicit finalizer.