Centralized tracking of frontend's global state (#9963)

import Local_store from merlin, with a simplified API following review comments

1 files changed, 66 insertions, 0 deletions

diff --git a/utils/local_store.mli b/utils/local_store.mli
new file mode 100644
index 0000000000..f39cd12328
--- /dev/null
+++ b/utils/local_store.mli
@@ -0,0 +1,66 @@
+(**************************************************************************)
+(*                                                                        *)
+(*                                 OCaml                                  *)
+(*                                                                        *)
+(*                        Frederic Bour, Tarides                          *)
+(*                         Thomas Refis, Tarides                          *)
+(*                                                                        *)
+(*   Copyright 2020 Tarides                                               *)
+(*                                                                        *)
+(*   All rights reserved.  This file is distributed under the terms of    *)
+(*   the GNU Lesser General Public License version 2.1, with the          *)
+(*   special exception on linking described in the file LICENSE.          *)
+(*                                                                        *)
+(**************************************************************************)
+
+(** This module provides some facilities for creating references (and hash
+    tables) which can easily be snapshoted and restored to an arbitrary version.
+
+    It is used throughout the frontend (read: typechecker), to register all
+    (well, hopefully) the global state. Thus making it easy for tools like
+    Merlin to go back and forth typechecking different files. *)
+
+(** {1 Creators} *)
+
+val s_ref : 'a -> 'a ref
+(** Similar to {!ref}, except the allocated reference is registered into the
+    store. *)
+
+val s_table : ('a -> 'b) -> 'a -> 'b ref
+(** Used to register hash tables. Those also need to be placed into refs to be
+    easily swapped out, but one can't just "snapshot" the initial value to
+    create fresh instances, so instead an initializer is required.
+
+    Use it like this:
+    {[
+      let my_table = s_table Hashtbl.create 42
+    ]}
+*)
+
+(** {1 State management}
+
+    Note: all the following functions are currently unused inside the compiler
+    codebase. Merlin is their only user at the moment. *)
+
+type store
+
+val fresh : unit -> store
+(** Returns a fresh instance of the store.
+
+    The first time this function is called, it snapshots the value of all the
+    registered references, later calls to [fresh] will return instances
+    initialized to those values. *)
+
+val with_store : store -> (unit -> 'a) -> 'a
+(** [with_scope s f] resets all the registered references to the value they have
+    in [s] for the run of [f].
+    If [f] updates any of the registered refs, [s] is updated to remember those
+    changes. *)
+
+val reset : unit -> unit
+(** Resets all the references to the initial snapshot (i.e. to the same values
+    that new instances start with). *)
+
+val is_bound : unit -> bool
+(** Returns [true] when a scope is active (i.e. when called from the callback
+    passed to {!with_scope}), [false] otherwise. *)