[commit: ghc] master: Modify ForeignPtr documentation in light of plusForeignPtr (852c6a0)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/852c6a09f8ac21c3e843e64dfa7c6382073eb5ce/ghc

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

commit 852c6a09f8ac21c3e843e64dfa7c6382073eb5ce
Author: Shea Levy <shea at shealevy.com>
Date:   Wed Jan 18 16:22:18 2017 -0500

    Modify ForeignPtr documentation in light of plusForeignPtr
    
    Reviewers: austin, rwbarton, simonmar, hvr, bgamari
    
    Reviewed By: rwbarton, simonmar
    
    Subscribers: thomie
    
    Differential Revision: https://phabricator.haskell.org/D2970


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

852c6a09f8ac21c3e843e64dfa7c6382073eb5ce
 libraries/base/GHC/ForeignPtr.hs | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/libraries/base/GHC/ForeignPtr.hs b/libraries/base/GHC/ForeignPtr.hs
index 6088084..28b33e0 100644
--- a/libraries/base/GHC/ForeignPtr.hs
+++ b/libraries/base/GHC/ForeignPtr.hs
@@ -71,12 +71,14 @@ import GHC.Ptr          ( Ptr(..), FunPtr(..) )
 -- class 'Storable'.
 --
 data ForeignPtr a = ForeignPtr Addr# ForeignPtrContents
-        -- we cache the Addr# in the ForeignPtr object, but attach
-        -- the finalizer to the IORef (or the MutableByteArray# in
-        -- the case of a MallocPtr).  The aim of the representation
-        -- is to make withForeignPtr efficient; in fact, withForeignPtr
-        -- should be just as efficient as unpacking a Ptr, and multiple
-        -- withForeignPtrs can share an unpacked ForeignPtr.  Note
+        -- The Addr# in the ForeignPtr object is intentionally stored
+        -- separately from the finalizer. The primay aim of the
+        -- representation is to make withForeignPtr efficient; in fact,
+        -- withForeignPtr should be just as efficient as unpacking a
+        -- Ptr, and multiple withForeignPtrs can share an unpacked
+        -- ForeignPtr. As a secondary benefit, this representation
+        -- allows pointers to subregions within the same overall block
+        -- to share the same finalizer (see 'plusForeignPtr'). Note
         -- that touchForeignPtr only has to touch the ForeignPtrContents
         -- object, because that ensures that whatever the finalizer is
         -- attached to is kept alive.
@@ -438,6 +440,14 @@ castForeignPtr = coerce
 plusForeignPtr :: ForeignPtr a -> Int -> ForeignPtr b
 -- ^Advances the given address by the given offset in bytes.
 --
+-- The new 'ForeignPtr' shares the finalizer of the original,
+-- equivalent from a finalization standpoint to just creating another
+-- reference to the original. That is, the finalizer will not be
+-- called before the new 'ForeignPtr' is unreachable, nor will it be
+-- called an additional time due to this call, and the finalizer will
+-- be called with the same address that it would have had this call
+-- not happened, *not* the new address.
+--
 -- @since 4.10.0.0
 plusForeignPtr (ForeignPtr addr c) (I# d) = ForeignPtr (plusAddr# addr d) c