From 86a3c35039ead5698c7ee628795e1d8dcb0aedb2 Mon Sep 17 00:00:00 2001 From: Adam Gundry Date: Thu, 19 Sep 2024 11:15:01 +0100 Subject: [PATCH] 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)