From 86a3c35039ead5698c7ee628795e1d8dcb0aedb2 Mon Sep 17 00:00:00 2001 From: Adam Gundry Date: Thu, 19 Sep 2024 11:15:01 +0100 Subject: [PATCH 1/2] Clarify documentation of 'customStrategy' based on #690 --- Data/ByteString/Builder/Internal.hs | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/Data/ByteString/Builder/Internal.hs b/Data/ByteString/Builder/Internal.hs index b9053642..ed381629 100644 --- a/Data/ByteString/Builder/Internal.hs +++ b/Data/ByteString/Builder/Internal.hs @@ -1060,11 +1060,20 @@ data AllocationStrategy = AllocationStrategy {-# INLINE customStrategy #-} customStrategy :: (Maybe (Buffer, Int) -> IO Buffer) - -- ^ Buffer allocation function. If 'Nothing' is given, then a new first - -- buffer should be allocated. If @'Just' (oldBuf, minSize)@ is given, - -- then a buffer with minimal size @minSize@ must be returned. The - -- strategy may reuse the @oldBuf@, if it can guarantee that this - -- referentially transparent and @oldBuf@ is large enough. + -- ^ Buffer allocation function. + -- + -- * If 'Nothing' is given, then a new first buffer should be allocated. + -- + -- * If @'Just' (oldBuf, minSize)@ is given, then a buffer with minimal + -- size @minSize@ must be returned. The strategy may reuse @oldBuf@ only if + -- @oldBuf@ is large enough and the consumer can guarantee that this will + -- not result in a violation of referential transparency. + -- + -- /Warning:/ for multithreaded programs, it is generally unsafe to reuse + -- buffers when using the consumers of 'Builder' in this package. For + -- example, if 'toLazyByteStringWith' is called with an + -- 'AllocationStrategy' that reuses buffers, evaluating the result by + -- multiple threads simultaneously may lead to corrupted output. -> Int -- ^ Default buffer size. -> (Int -> Int -> Bool) From 197bcdceb9cfd3048735fc2dea48dbda6369ade3 Mon Sep 17 00:00:00 2001 From: Adam Gundry Date: Thu, 19 Sep 2024 11:15:42 +0100 Subject: [PATCH 2/2] Remove outdated comments on AllocationStrategy (These were not visible in the Haddock output anyway.) --- Data/ByteString/Builder/Internal.hs | 8 -------- 1 file changed, 8 deletions(-) diff --git a/Data/ByteString/Builder/Internal.hs b/Data/ByteString/Builder/Internal.hs index ed381629..8bb6278b 100644 --- a/Data/ByteString/Builder/Internal.hs +++ b/Data/ByteString/Builder/Internal.hs @@ -1042,14 +1042,6 @@ maximalCopySize = 2 * L.smallChunkSize ------------------------------------------------------------------------------ -- | A buffer allocation strategy for executing 'Builder's. - --- The strategy --- --- > 'AllocationStrategy' firstBufSize bufSize trim --- --- states that the first buffer is of size @firstBufSize@, all following buffers --- are of size @bufSize@, and a buffer of size @n@ filled with @k@ bytes should --- be trimmed iff @trim k n@ is 'True'. data AllocationStrategy = AllocationStrategy (Maybe (Buffer, Int) -> IO Buffer) {-# UNPACK #-} !Int