[commit: ghc] master: compact: Clarify mutability restriction (38f9ead)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/38f9eadd8e4746c2fabf83045073134f5a554a06/ghc

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

commit 38f9eadd8e4746c2fabf83045073134f5a554a06
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Mon Apr 3 19:27:59 2017 -0400

    compact: Clarify mutability restriction
    
    Fixes #13508.
    
    [skip ci]
    
    Test Plan: Read it
    
    Reviewers: austin
    
    Subscribers: rwbarton, thomie
    
    Differential Revision: https://phabricator.haskell.org/D3407


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

38f9eadd8e4746c2fabf83045073134f5a554a06
 libraries/ghc-compact/GHC/Compact.hs | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/libraries/ghc-compact/GHC/Compact.hs b/libraries/ghc-compact/GHC/Compact.hs
index 0464bc6..ea0663e 100644
--- a/libraries/ghc-compact/GHC/Compact.hs
+++ b/libraries/ghc-compact/GHC/Compact.hs
@@ -130,9 +130,9 @@ import GHC.Types
 --   address (the address might be stored in a C data structure, for
 --   example), so we can't make a copy of it to store in the 'Compact'.
 --
--- * Objects with mutable pointer fields also cannot be compacted,
---   because subsequent mutation would destroy the property that a compact is
---   self-contained.
+-- * Objects with mutable pointer fields (e.g. 'Data.IORef.IORef',
+--   'GHC.Array.MutableArray') also cannot be compacted, because subsequent
+--   mutation would destroy the property that a compact is self-contained.
 --
 -- If compaction encounters any of the above, a 'CompactionFailed'
 -- exception will be thrown by the compaction operation.
@@ -186,9 +186,10 @@ getCompact (Compact _ obj _) = obj
 -- not terminate if the structure contains cycles (use 'compactWithSharing'
 -- instead).
 --
--- The object in question must not contain any functions or mutable data; if it
--- does, 'compact' will raise an exception.  In the future, we may add a type
--- class which will help statically check if this is the case or not.
+-- The object in question must not contain any functions or data with mutable
+-- pointers; if it does, 'compact' will raise an exception. In the future, we
+-- may add a type class which will help statically check if this is the case or
+-- not.
 --
 compact :: a -> IO (Compact a)
 compact = compactSized 31268 False
@@ -200,9 +201,10 @@ compact = compactSized 31268 False
 -- by maintaining a hash table mapping uncompacted objects to
 -- compacted objects.
 --
--- The object in question must not contain any functions or mutable data; if it
--- does, 'compact' will raise an exception.  In the future, we may add a type
--- class which will help statically check if this is the case or not.
+-- The object in question must not contain any functions or data with mutable
+-- pointers; if it does, 'compact' will raise an exception. In the future, we
+-- may add a type class which will help statically check if this is the case or
+-- not.
 --
 compactWithSharing :: a -> IO (Compact a)
 compactWithSharing = compactSized 31268 True