Request for clarification in Builder.customStrategy docs

[jberryman]

customStrategy is documented:

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.
  -> Int
     -- ^ Default buffer size.
  -> (Int -> Int -> Bool)
     -- ^ A predicate @trim used allocated@ returning 'True', if the buffer
     -- should be trimmed before it is returned.
  -> AllocationStrategy

I'm struggling to understand where one might want to reuse the buffer passed to the first argument of customStrategy (call it nextBuffer) . My understanding is nextBuffer is meant to do something like:

nextBuffer (Just (buf, minSize)) = if free_space_in buf <= minSize then return buf else newBuffer minSize

But I’m confused about under what circumstances free_space_in buf is true. None of the AllocationStrategys in the library make use of buf as far as I can tell

[jberryman]

...I guess it can be used to override the decision to flush during bytestring construction

[adamgundry]

I'm late to spot this issue, but I propose updating the documentation for customStrategy in https://github.com/haskell/bytestring/pull/692. In general I think the answer is that one should not reuse the buffer in customStrategy and providing the ability to do so is arguably a mistake...