improve names and documentation

Author: raphael-proust

src/core/lwt.ml

@@ -712,14 +712,14 @@ open Basic_helpers
 
 (* Small helpers to avoid catching ocaml-runtime exceptions *)
 type exception_filter = exn -> bool
-let catch_all_filter = fun _ -> true
-let catch_not_runtime_filter = function
+let catch_filter__all = fun _ -> true
+let catch_filter__all_except_runtime = function
   | Out_of_memory -> false
   | Stack_overflow -> false
   | _ -> true
 let exception_filter =
   (* Default value: the legacy behaviour to avoid breaking programs *)
-  ref catch_all_filter
+  ref catch_filter__all
 let set_exception_filter f = exception_filter := f
 let filter_exception e = !exception_filter e
 

src/core/lwt.mli

@@ -2003,10 +2003,10 @@ val ignore_result : _ t -> unit
 
     Depending on the kind of programs that you write, you may need to treat
     exceptions thrown by the OCaml runtime (namely [Out_of_memory] and
-    [Stack_overflow] differently. This is because (a) these exceptions are not
-    reproducible (in that they are thrown at different points of your program
-    depending on the machine that your program runs on) and (b) recovering
-    from these errors may be impossible.
+    [Stack_overflow]) differently than all the other exceptions. This is because
+    (a) these exceptions are not reproducible (in that they are thrown at
+    different points of your program depending on the machine that your program
+    runs on) and (b) recovering from these errors may be impossible.
 
     The helpers below allow you to change the way that Lwt handles the two OCaml
     runtime exceptions [Out_of_memory] and [Stack_overflow]. *)
@@ -2016,15 +2016,15 @@ val ignore_result : _ t -> unit
     immediately. *)
 type exception_filter
 
-(** [catch_all_filter] is the default filter. With it the all the exceptions
+(** [catch_filter__all] is the default filter. With it the all the exceptions
     (including [Out_of_memory] and [Stack_overflow]) are caught and transformed
     into rejected promises. *)
-val catch_all_filter : exception_filter
+val catch_filter__all : exception_filter
 
-(** [catch_not_runtime_filter] is a filter which lets the OCaml runtime
+(** [catch_filter__all_except_runtime] is a filter which lets the OCaml runtime
     exceptions ([Out_of_memory] and [Stack_overflow]) go through all the Lwt
     abstractions and bubble all the way out of the call to [Lwt_main.run]. *)
-val catch_not_runtime_filter : exception_filter
+val catch_filter__all_except_runtime : exception_filter
 
 (** [set_exception_filter] sets the given exception filter globally. *)
 val set_exception_filter : exception_filter -> unit

src/unix/lwt_main.mli

@@ -39,13 +39,16 @@ let () = Lwt_main.run (main ())
       [Lwt_main.run] will raise [Failure]. This should be considered a logic
       error (i.e., code making such a call is inherently broken).
 
-      In addition, note that Lwt does not attempt to catch exceptions thrown by
-      the OCaml runtime. Specifically, Lwt lets [Out_of_memory] and
-      [Stack_overflow] exceptions traverse all of its functions and bubble up to
-      the caller of [Lwt_main.run]. Moreover because these exceptions are left
-      to traverse the call stack, they leave the internal data-structures in an
-      inconsistent state. For this reason, calling [Lwt_main.run] again after
-      such an exception will raise [Failure].
+      In addition, note that if you have set the exception filter to let runtime
+      exceptions bubble up (via
+      [Lwt.set_exception_filter catch_filter__all_except_runtime]) then Lwt does
+      not attempt to catch exceptions thrown by the OCaml runtime. Specifically,
+      in this case, Lwt lets [Out_of_memory] and [Stack_overflow] exceptions
+      traverse all of its functions and bubble up to the caller of
+      [Lwt_main.run]. Moreover because these exceptions are left to traverse the
+      call stack, they leave the internal data-structures in an inconsistent
+      state. For this reason, calling [Lwt_main.run] again after such an
+      exception will raise [Failure].
 
       It is not safe to call [Lwt_main.run] in a function registered with
       [Stdlib.at_exit], use {!Lwt_main.at_exit} instead. *)

test/core/test_lwt.ml

@@ -638,7 +638,7 @@ let catch_tests = suite "catch" [
 
 
   test "catch with ocaml-runtime exception" begin fun () ->
-    Lwt.set_exception_filter Lwt.catch_not_runtime_filter;
+    Lwt.set_exception_filter Lwt.catch_filter__all_except_runtime;
     try
       Lwt.catch
         (fun () -> raise Out_of_memory)
@@ -648,7 +648,7 @@ let catch_tests = suite "catch" [
   end;
 
   test "try_bind with ocaml-runtime exception" begin fun () ->
-    Lwt.set_exception_filter Lwt.catch_not_runtime_filter;
+    Lwt.set_exception_filter Lwt.catch_filter__all_except_runtime;
     try
       Lwt.try_bind
         (fun () -> raise Out_of_memory)
@@ -659,7 +659,7 @@ let catch_tests = suite "catch" [
   end;
 
   test "try_bind(2) with ocaml-runtime exception" begin fun () ->
-    Lwt.set_exception_filter Lwt.catch_not_runtime_filter;
+    Lwt.set_exception_filter Lwt.catch_filter__all_except_runtime;
     try
       let _ =
         Lwt.try_bind

test/unix/ocaml_runtime_exc_1.ml

@@ -2,7 +2,7 @@
    details, or visit https://github.com/ocsigen/lwt/blob/master/LICENSE.md. *)
 
 (* set the exception filter being tested *)
-let () = Lwt.set_exception_filter Lwt.catch_not_runtime_filter
+let () = Lwt.set_exception_filter Lwt.catch_filter__all_except_runtime
 
 (* OCaml runtime exceptions (out-of-memory, stack-overflow) are fatal in a
    different way than other exceptions and they leave the Lwt main loop in an

test/unix/ocaml_runtime_exc_2.ml

@@ -2,7 +2,7 @@
    details, or visit https://github.com/ocsigen/lwt/blob/master/LICENSE.md. *)
 
 (* set the exception filter being tested *)
-let () = Lwt.set_exception_filter Lwt.catch_not_runtime_filter
+let () = Lwt.set_exception_filter Lwt.catch_filter__all_except_runtime
 
 (* OCaml runtime exceptions (out-of-memory, stack-overflow) are fatal in a
    different way than other exceptions and they leave the Lwt main loop in an

test/unix/ocaml_runtime_exc_3.ml

@@ -2,7 +2,7 @@
    details, or visit https://github.com/ocsigen/lwt/blob/master/LICENSE.md. *)
 
 (* set the exception filter being tested *)
-let () = Lwt.set_exception_filter Lwt.catch_not_runtime_filter
+let () = Lwt.set_exception_filter Lwt.catch_filter__all_except_runtime
 
 (* OCaml runtime exceptions (out-of-memory, stack-overflow) are fatal in a
    different way than other exceptions and they leave the Lwt main loop in an

test/unix/ocaml_runtime_exc_4.ml

@@ -2,7 +2,7 @@
    details, or visit https://github.com/ocsigen/lwt/blob/master/LICENSE.md. *)
 
 (* set the exception filter being tested *)
-let () = Lwt.set_exception_filter Lwt.catch_not_runtime_filter
+let () = Lwt.set_exception_filter Lwt.catch_filter__all_except_runtime
 
 (* OCaml runtime exceptions (out-of-memory, stack-overflow) are fatal in a
    different way than other exceptions and they leave the Lwt main loop in an

test/unix/ocaml_runtime_exc_5.ml

@@ -2,7 +2,7 @@
    details, or visit https://github.com/ocsigen/lwt/blob/master/LICENSE.md. *)
 
 (* set the exception filter being tested *)
-let () = Lwt.set_exception_filter Lwt.catch_not_runtime_filter
+let () = Lwt.set_exception_filter Lwt.catch_filter__all_except_runtime
 
 (* OCaml runtime exceptions (out-of-memory, stack-overflow) are fatal in a
    different way than other exceptions and they leave the Lwt main loop in an

test/unix/ocaml_runtime_exc_6.ml

@@ -2,7 +2,7 @@
    details, or visit https://github.com/ocsigen/lwt/blob/master/LICENSE.md. *)
 
 (* set the exception filter being tested *)
-let () = Lwt.set_exception_filter Lwt.catch_not_runtime_filter
+let () = Lwt.set_exception_filter Lwt.catch_filter__all_except_runtime
 
 (* OCaml runtime exceptions (out-of-memory, stack-overflow) are fatal in a
    different way than other exceptions and they leave the Lwt main loop in an