Merge pull request #11193 from Octachron/concurrency_alerts_part_one

Octachron · web-flow · commit db5949ffb524 · 2022-11-24T11:17:00.000+01:00
Concurrency safety documentation, part one: concurrency unsafe types
diff --git a/stdlib/buffer.mli b/stdlib/buffer.mli
@@ -30,6 +30,18 @@
 
 *)
 
+(** {b Unsynchronized accesses} *)
+
+[@@@alert unsynchronized_access
+    "Unsynchronized accesses to buffers are a programming error."
+]
+
+ (**
+    Unsynchronized accesses to a buffer may lead to an invalid buffer state.
+    Thus, concurrent accesses to a buffer must be synchronized (for instance
+    with a {!Mutex.t}).
+*)
+
 type t
 (** The abstract type of buffers. *)
 
diff --git a/stdlib/ephemeron.mli b/stdlib/ephemeron.mli
@@ -65,6 +65,18 @@
     @since 4.03
 *)
 
+(** {b Unsynchronized accesses} *)
+
+[@@@alert unsynchronized_access
+  "Unsynchronized accesses to weak hash tables are a programming error."
+]
+
+(**
+    Unsynchronized accesses to a weak hash table may lead to an invalid
+    weak hash table state. Thus, concurrent accesses to a buffer must be
+    synchronized (for instance with a {!Mutex.t}).
+*)
+
 module type S = sig
   (** Propose the same interface as usual hash table. However since
       the bindings are weak, even if [mem h k] is true, a subsequent
diff --git a/stdlib/hashtbl.mli b/stdlib/hashtbl.mli
@@ -41,6 +41,18 @@
    See {{!examples} the examples section}.
 *)
 
+(** {b Unsynchronized accesses} *)
+
+[@@@alert unsynchronized_access
+    "Unsynchronized accesses to hash tables are a programming error."
+]
+
+ (**
+    Unsynchronized accesses to a hash table may lead to an invalid hash table
+    state. Thus, concurrent accesses to a hash tables must be synchronized
+    (for instance with a {!Mutex.t}).
+*)
+
 
 (** {1 Generic interface} *)
 
diff --git a/stdlib/moreLabels.mli b/stdlib/moreLabels.mli
@@ -58,6 +58,18 @@ module Hashtbl : sig
      See {{!examples} the examples section}.
   *)
 
+  (** {b Unsynchronized accesses} *)
+
+  [@@@alert unsynchronized_access
+      "Unsynchronized accesses to hash tables are a programming error."
+  ]
+
+   (**
+      Unsynchronized accesses to a hash table may lead to an invalid hash table
+      state. Thus, concurrent accesses to a hash tables must be synchronized
+      (for instance with a {!Mutex.t}).
+  *)
+
 
   (** {1 Generic interface} *)
 
diff --git a/stdlib/oo.mli b/stdlib/oo.mli
@@ -15,9 +15,12 @@
 
 (** Operations on objects *)
 
-val copy : (< .. > as 'a) -> 'a
 (** [Oo.copy o] returns a copy of object [o], that is a fresh
    object with the same methods and instance variables as [o]. *)
+val copy : (< .. > as 'a) -> 'a
+[@@alert unsynchronized_access
+    "Unsynchronized accesses to mutable objects are a programming error."
+]
 
 external id : < .. > -> int = "%field1"
 (** Return an integer identifying this object, unique for
diff --git a/stdlib/queue.mli b/stdlib/queue.mli
@@ -17,10 +17,18 @@
 
    This module implements queues (FIFOs), with in-place modification.
    See {{!examples} the example section} below.
+*)
+
+(** {b Unsynchronized accesses} *)
+
+[@@@alert unsynchronized_access
+    "Unsynchronized accesses to queues are a programming error."
+]
 
-   {b Warning} This module is not thread-safe: each {!Queue.t} value
-   must be protected from concurrent access (e.g. with a [Mutex.t]).
-   Failure to do so can lead to a crash.
+(**
+    Unsynchronized accesses to a queue may lead to an invalid queue state.
+    Thus, concurrent accesses to queues must be synchronized (for instance
+    with a {!Mutex.t}).
 *)
 
 type !'a t
diff --git a/stdlib/scanf.mli b/stdlib/scanf.mli
@@ -81,10 +81,17 @@
     facility is fully type-checked at compile time.
 *)
 
-(** {2 Note on concurrent use} *)
+(** {b Unsynchronized accesses} *)
 
-(** Since values of type {!Scanning.in_channel} contain inner mutable states,
-    they are not safe to use concurrently without external synchronization.
+[@@@alert unsynchronized_access
+    "Unsynchronized accesses to Scanning.in_channel are a programming error."
+]
+
+ (**
+      Unsynchronized accesses to a {!Scanning.in_channel} may lead to an
+      invalid {!Scanning.in_channel} state. Thus, concurrent accesses
+      to {!Scanning.in_channel}s must be synchronized (for instance with
+      a {!Mutex.t}).
 *)
 
 (** {1 Formatted input channel} *)
diff --git a/stdlib/stack.mli b/stdlib/stack.mli
@@ -18,6 +18,18 @@
    This module implements stacks (LIFOs), with in-place modification.
 *)
 
+(** {b Unsynchronized accesses} *)
+
+[@@@alert unsynchronized_accesses
+    "Unsynchronized accesses to stacks are a programming error."
+]
+
+ (**
+    Unsynchronized accesses to a stack may lead to an invalid queue state.
+    Thus, concurrent accesses to stacks must be synchronized (for instance
+    with a {!Mutex.t}).
+*)
+
 type !'a t
 (** The type of stacks containing elements of type ['a]. *)
 
diff --git a/stdlib/templates/hashtbl.template.mli b/stdlib/templates/hashtbl.template.mli
@@ -41,6 +41,18 @@
    See {{!examples} the examples section}.
 *)
 
+(** {b Unsynchronized accesses} *)
+
+[@@@alert unsynchronized_access
+    "Unsynchronized accesses to hash tables are a programming error."
+]
+
+ (**
+    Unsynchronized accesses to a hash table may lead to an invalid hash table
+    state. Thus, concurrent accesses to a hash tables must be synchronized
+    (for instance with a {!Mutex.t}).
+*)
+
 
 (** {1 Generic interface} *)
 
diff --git a/stdlib/weak.mli b/stdlib/weak.mli
@@ -114,6 +114,14 @@ val blit : 'a t -> int -> 'a t -> int -> int -> unit
     the values and give the same result as with the values themselves.
     *)
 
+(** {b Unsynchronized accesses}
+
+    Unsynchronized accesses to weak hash sets are a programming error.
+    Unsynchronized accesses to a weak hash set may lead to an invalid weak hash
+    set state. Thus, concurrent accesses to weak hash sets must be synchronized
+    (for instance with a {!Mutex.t}).
+*)
+
 module type S = sig
   type data
   (** The type of the elements stored in the table. *)
diff --git a/utils/warnings.ml b/utils/warnings.ml
@@ -580,7 +580,7 @@ let current =
     {
       active = Array.make (last_warning_number + 1) true;
       error = Array.make (last_warning_number + 1) false;
-      alerts = (Misc.Stdlib.String.Set.empty, false); (* all enabled *)
+      alerts = (Misc.Stdlib.String.Set.empty, false);
       alert_errors = (Misc.Stdlib.String.Set.empty, true); (* all soft *)
     }
 
@@ -856,7 +856,7 @@ let parse_options errflag s =
 (* If you change these, don't forget to change them in man/ocamlc.m *)
 let defaults_w = "+a-4-7-9-27-29-30-32..42-44-45-48-50-60-66..70"
 let defaults_warn_error = "-a+31"
-let default_disabled_alerts = [ "unstable" ]
+let default_disabled_alerts = [ "unstable"; "unsynchronized_access" ]
 
 let () = ignore @@ parse_options false defaults_w
 let () = ignore @@ parse_options true defaults_warn_error
