[commit: ghc] master: StaticPointers: Clarify documentation (6dfe982)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/6dfe9828e2b3bd79e22e89c919b0d1b92273b718/ghc

>---------------------------------------------------------------

commit 6dfe9828e2b3bd79e22e89c919b0d1b92273b718
Author: Facundo Domínguez <facundo.dominguez at tweag.io>
Date:   Wed Nov 15 11:37:32 2017 -0500

    StaticPointers: Clarify documentation
    
     * Document requirement to use the same binaries.
     * Fix some code comments.
    
    Test Plan: ./validate
    
    Reviewers: bgamari, mboes, hvr
    
    Reviewed By: bgamari, mboes
    
    Subscribers: rwbarton, thomie
    
    Differential Revision: https://phabricator.haskell.org/D4172


>---------------------------------------------------------------

6dfe9828e2b3bd79e22e89c919b0d1b92273b718
 compiler/main/StaticPtrTable.hs   | 6 +++---
 compiler/rename/RnExpr.hs         | 6 +++---
 compiler/typecheck/TcRnTypes.hs   | 4 ++--
 docs/users_guide/glasgow_exts.rst | 7 +++++++
 libraries/base/GHC/StaticPtr.hs   | 5 +++++
 5 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/compiler/main/StaticPtrTable.hs b/compiler/main/StaticPtrTable.hs
index 23d02f8..47547fc 100644
--- a/compiler/main/StaticPtrTable.hs
+++ b/compiler/main/StaticPtrTable.hs
@@ -60,13 +60,13 @@ Here is a running example:
          in ...(static k)...
 
 * The renamer looks for out-of-scope names in the body of the static
-  form, as always If all names are in scope, the free variables of the
+  form, as always. If all names are in scope, the free variables of the
   body are stored in AST at the location of the static form.
 
 * The typechecker verifies that all free variables occurring in the
   static form are floatable to top level (see Note [Meaning of
-  IdBindingInfo] in TcRnTypes).  In our example, 'k' is floatable, even
-  though it is bound in a nested let, we are fine.
+  IdBindingInfo] in TcRnTypes).  In our example, 'k' is floatable.
+  Even though it is bound in a nested let, we are fine.
 
 * The desugarer replaces the static form with an application of the
   function 'makeStatic' (defined in module GHC.StaticPtr.Internal of
diff --git a/compiler/rename/RnExpr.hs b/compiler/rename/RnExpr.hs
index 8f719c4..22e474b 100644
--- a/compiler/rename/RnExpr.hs
+++ b/compiler/rename/RnExpr.hs
@@ -371,9 +371,9 @@ rnExpr e@(ELazyPat {}) = patSynErr e empty
 *                                                                      *
 ************************************************************************
 
-For the static form we check that the free variables are all top-level
-value bindings. This is done by checking that the name is external or
-wired-in. See the Notes about the NameSorts in Name.hs.
+For the static form we check that it is not used in splices.
+We also collect the free variables of the term which come from
+this module. See Note [Grand plan for static forms] in StaticPtrTable.
 -}
 
 rnExpr e@(HsStatic _ expr) = do
diff --git a/compiler/typecheck/TcRnTypes.hs b/compiler/typecheck/TcRnTypes.hs
index f2309c8..7e347ff 100644
--- a/compiler/typecheck/TcRnTypes.hs
+++ b/compiler/typecheck/TcRnTypes.hs
@@ -1176,8 +1176,8 @@ ClosedLet means that
    - For the ClosedTypeId field see Note [Bindings with closed types]
 
 For (static e) to be valid, we need for every 'x' free in 'e',
-x's binding must be floatable to top level.  Specifically:
-   * x's RhsNames must be non-empty
+that x's binding is floatable to the top level.  Specifically:
+   * x's RhsNames must be empty
    * x's type has no free variables
 See Note [Grand plan for static forms] in StaticPtrTable.hs.
 This test is made in TcExpr.checkClosedInStaticForm.
diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index ab92375..3edb8d6 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -12937,6 +12937,13 @@ While the following definitions are rejected: ::
     entered on the REPL may not. This is a limitation of GHCi; see
     :ghc-ticket:`12356` for details.
 
+.. note::
+
+    The set of keys used for locating static pointers in the Static Pointer
+    Table is not guaranteed to remain stable for different program binaries.
+    Or in other words, only processes launched from the same program binary
+    are guaranteed to use the same set of keys.
+
 .. _typechecking-static-pointers:
 
 Static semantics of static pointers
diff --git a/libraries/base/GHC/StaticPtr.hs b/libraries/base/GHC/StaticPtr.hs
index 65ec483..92829ac 100644
--- a/libraries/base/GHC/StaticPtr.hs
+++ b/libraries/base/GHC/StaticPtr.hs
@@ -28,6 +28,11 @@
 -- table is known as the Static Pointer Table. The reference can then be
 -- dereferenced to obtain the value.
 --
+-- The various communicating processes need to aggree on the keys used to refer
+-- to the values in the Static Pointer Table, or lookups will fail. Only
+-- processes launched from the same program binary are guaranteed to use the
+-- same set of keys.
+--
 -----------------------------------------------------------------------------
 
 module GHC.StaticPtr