Commit 852c6a09 authored by shlevy's avatar shlevy Committed by Ben Gamari
Browse files

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
parent 0b7cd65e
...@@ -71,12 +71,14 @@ import GHC.Ptr ( Ptr(..), FunPtr(..) ) ...@@ -71,12 +71,14 @@ import GHC.Ptr ( Ptr(..), FunPtr(..) )
-- class 'Storable'. -- class 'Storable'.
-- --
data ForeignPtr a = ForeignPtr Addr# ForeignPtrContents data ForeignPtr a = ForeignPtr Addr# ForeignPtrContents
-- we cache the Addr# in the ForeignPtr object, but attach -- The Addr# in the ForeignPtr object is intentionally stored
-- the finalizer to the IORef (or the MutableByteArray# in -- separately from the finalizer. The primay aim of the
-- the case of a MallocPtr). The aim of the representation -- representation is to make withForeignPtr efficient; in fact,
-- is to make withForeignPtr efficient; in fact, withForeignPtr -- withForeignPtr should be just as efficient as unpacking a
-- should be just as efficient as unpacking a Ptr, and multiple -- Ptr, and multiple withForeignPtrs can share an unpacked
-- withForeignPtrs can share an unpacked ForeignPtr. Note -- 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 -- that touchForeignPtr only has to touch the ForeignPtrContents
-- object, because that ensures that whatever the finalizer is -- object, because that ensures that whatever the finalizer is
-- attached to is kept alive. -- attached to is kept alive.
...@@ -438,6 +440,14 @@ castForeignPtr = coerce ...@@ -438,6 +440,14 @@ castForeignPtr = coerce
plusForeignPtr :: ForeignPtr a -> Int -> ForeignPtr b plusForeignPtr :: ForeignPtr a -> Int -> ForeignPtr b
-- ^Advances the given address by the given offset in bytes. -- ^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 -- @since 4.10.0.0
plusForeignPtr (ForeignPtr addr c) (I# d) = ForeignPtr (plusAddr# addr d) c plusForeignPtr (ForeignPtr addr c) (I# d) = ForeignPtr (plusAddr# addr d) c
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment