StaticPointers: Clarify documentation
authorFacundo Domínguez <facundo.dominguez@tweag.io>
Wed, 15 Nov 2017 16:37:32 +0000 (11:37 -0500)
committerBen Gamari <ben@smart-cactus.org>
Wed, 15 Nov 2017 16:37:55 +0000 (11:37 -0500)
 * 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

compiler/main/StaticPtrTable.hs
compiler/rename/RnExpr.hs
compiler/typecheck/TcRnTypes.hs
docs/users_guide/glasgow_exts.rst
libraries/base/GHC/StaticPtr.hs

index 23d02f8..47547fc 100644 (file)
@@ -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
index 8f719c4..22e474b 100644 (file)
@@ -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
index f2309c8..7e347ff 100644 (file)
@@ -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.
index ab92375..3edb8d6 100644 (file)
@@ -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
index 65ec483..92829ac 100644 (file)
 -- 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