Fix #86, remark on lifetime properties of CString.
authorEdward Z. Yang <ezyang@cs.stanford.edu>
Fri, 2 Sep 2016 04:36:57 +0000 (21:36 -0700)
committerEdward Z. Yang <ezyang@cs.stanford.edu>
Fri, 2 Sep 2016 04:36:57 +0000 (21:36 -0700)
Signed-off-by: Edward Z. Yang <ezyang@cs.stanford.edu>
Data/ByteString.hs
Data/ByteString/Unsafe.hs

index 99c7e38..8c9462b 100644 (file)
@@ -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@.  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@.
 -- As for @useAsCString@ this function makes a copy of the original @ByteString@.
+-- 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)
 
index a0a1da8..782a42d 100644 (file)
@@ -260,6 +260,10 @@ unsafePackMallocCStringLen (cstr, len) = do
 -- to guarantee that the @ByteString@ is indeed null terminated. If in
 -- doubt, use @useAsCString@.
 --
+-- * 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)