[commit: packages/bytestring] master: Fix #86, remark on lifetime properties of CString. (00902c5)

[git at git.haskell.org]

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

On branch  : master
Link       : http://git.haskell.org/packages/bytestring.git/commitdiff/00902c50959f801f1f014ee16aac2de90fb16874

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

commit 00902c50959f801f1f014ee16aac2de90fb16874
Author: Edward Z. Yang <ezyang at cs.stanford.edu>
Date:   Thu Sep 1 21:36:57 2016 -0700

    Fix #86, remark on lifetime properties of CString.
    
    Signed-off-by: Edward Z. Yang <ezyang at cs.stanford.edu>


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

00902c50959f801f1f014ee16aac2de90fb16874
 Data/ByteString.hs        | 4 +++-
 Data/ByteString/Unsafe.hs | 4 ++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/Data/ByteString.hs b/Data/ByteString.hs
index 99c7e38..8c9462b 100644
--- a/Data/ByteString.hs
+++ b/Data/ByteString.hs
@@ -1533,7 +1533,8 @@ sort (PS input s l) = unsafeCreate l $ \p -> allocaArray 256 $ \arr -> do
 
 -- | /O(n) construction/ Use a @ByteString@ with a function requiring a
 -- null-terminated @CString at .  The @CString@ is a copy and will be freed
--- automatically.
+-- automatically; it must not be stored or used after the
+-- subcomputation finishes.
 useAsCString :: ByteString -> (CString -> IO a) -> IO a
 useAsCString (PS fp o l) action =
  allocaBytes (l+1) $ \buf ->
@@ -1544,6 +1545,7 @@ useAsCString (PS fp o l) action =
 
 -- | /O(n) construction/ Use a @ByteString@ with a function requiring a @CStringLen at .
 -- As for @useAsCString@ this function makes a copy of the original @ByteString at .
+-- It must not be stored or used after the subcomputation finishes.
 useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
 useAsCStringLen p@(PS _ _ l) f = useAsCString p $ \cstr -> f (cstr,l)
 
diff --git a/Data/ByteString/Unsafe.hs b/Data/ByteString/Unsafe.hs
index a0a1da8..782a42d 100644
--- a/Data/ByteString/Unsafe.hs
+++ b/Data/ByteString/Unsafe.hs
@@ -260,6 +260,10 @@ unsafePackMallocCStringLen (cstr, len) = do
 -- to guarantee that the @ByteString@ is indeed null terminated. If in
 -- doubt, use @useAsCString at .
 --
+-- * The memory may freed at any point after the subcomputation
+-- terminates, so the pointer to the storage must *not* be used
+-- after this.
+--
 unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a
 unsafeUseAsCString (PS ps s _) ac = withForeignPtr ps $ \p -> ac (castPtr p `plusPtr` s)