-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Fast ByteString Builder -- -- An efficient implementation of ByteString builder. It should be faster -- than the standard implementation in most cases. -- -- In many benchmarks, the performance improvement is 2x-10x. @package fast-builder @version 0.0.0.2 -- | This is an internal module; its interface is unstable. module Data.ByteString.FastBuilder.Internal -- | Builder is an auxiliary type for efficiently generating a long -- ByteString. It is isomorphic to lazy ByteString, but -- offers constant-time concatanation via <>. -- -- Use toLazyByteString to turn a Builder into a -- ByteString newtype Builder [Builder] :: (DataSink -> BuilderState -> BuilderState) -> Builder [unBuilder] :: Builder -> DataSink -> BuilderState -> BuilderState -- | This datatype exists only to work around the limitation that -- oneShot cannot work with unboxed argument types. data BuilderState [BuilderState] :: !(Ptr Word8) -> !(Ptr Word8) -> (State# RealWorld) -> BuilderState -- | Specifies where bytes generated by a builder go. data DataSink -- | The destination of data changes while the builder is running. [DynamicSink] :: !(IORef DynamicSink) -> DataSink -- | Bytes are accumulated in a contiguous buffer. [GrowingBuffer] :: !(IORef (ForeignPtr Word8)) -> DataSink -- | Bytes are first accumulated in the Queue, then flushed to the -- Handle. [HandleSink] :: !Handle -> !(IORef Queue) -> DataSink -- | Variable-destination cases. data DynamicSink -- | Bytes are sent to another thread. [ThreadedSink] :: !(MVar Request) -> !(MVar Response) -> DynamicSink -- | Bytes are accumulated in a contiguous buffer until the size limit is -- reached. After that, the destination switches to a -- ThreadedSink. [BoundedGrowingBuffer] :: {-# UNPACK #-} !(ForeignPtr Word8) -> !Int -> DynamicSink -- | A mutable buffer. The Int specifies where the data start. data Queue [Queue] :: !(ForeignPtr Word8) -> !Int -> Queue -- | A request from the driver thread to the builder thread. data Request [Request] :: {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> Request -- | A response from the builder thread to the driver thread. data Response -- | A synchronous exception was thrown by the builder [Error] :: SomeException -> Response -- | The builder thread has completed. [Done] :: !(Ptr Word8) -> Response -- | The builder thread has finished generating one chunk, and waits for -- another request with the specified minimum size. [MoreBuffer] :: !(Ptr Word8) -> !Int -> Response -- | The builder thread has partially filled the current chunk, and wants -- to emit the bytestring to be included in the final output. [InsertByteString] :: !(Ptr Word8) -> !ByteString -> Response -- | Used in the implementation of toLazyByteString. This is a -- message sent from the consumer thread to the builder thread, -- requesting the builder thread to temporarily pause execution. Later, -- the consumer thread may request resumption by filling the MVar. data SuspendBuilderException [SuspendBuilderException] :: !(MVar ()) -> SuspendBuilderException -- | Used in the implementation of toLazyByteString. This is an -- exception thrown by the consumer thread to itself when it has finished -- filling the first chunk of the output. After this, a thread will be -- forked, and the execution of the builder will be resumed in the new -- thread, using ThreadedSink. data ChunkOverflowException [ChunkOverflowException] :: !ByteString -> !(MVar Request) -> !(MVar Response) -> !Int -> ChunkOverflowException -- | An internal type that is isomorphic to Builder. This is a -- maximaly efficient representation for NOINLINE functions. type Builder_ = DataSink -> Addr# -> Addr# -> State# RealWorld -> (# Addr#, Addr#, State# RealWorld #) -- | An internal type for making it easier to define builders. A value of -- BuildM a can do everything a Builder can do, -- and in addition, returns a value of type a upon completion. newtype BuildM a [BuildM] :: ((a -> Builder) -> Builder) -> BuildM a [runBuildM] :: BuildM a -> (a -> Builder) -> Builder -- | Convert a Builder into a Builder_. toBuilder_ :: Builder -> Builder_ -- | Convert a Builder_ into a Builder. fromBuilder_ :: Builder_ -> Builder -- | Create a builder from a BuildM. mkBuilder :: BuildM () -> Builder -- | Embed a builder in the BuildM context. useBuilder :: Builder -> BuildM () -- | Get the DataSink. getSink :: BuildM DataSink -- | Get the current pointer. getCur :: BuildM (Ptr Word8) -- | Get the end-of-buffer pointer. getEnd :: BuildM (Ptr Word8) -- | Set the current pointer. setCur :: Ptr Word8 -> BuildM () -- | Set the end-of-buffer pointer. setEnd :: Ptr Word8 -> BuildM () -- | Run a builder. runBuilder :: Builder -> DataSink -> Ptr Word8 -> Ptr Word8 -> IO (Ptr Word8) -- | Turn a Builder into a lazy ByteString. -- -- Performance hint: when the resulting ByteString does not -- fit in one chunk, this function forks a thread. Due to this, the -- performance degrades sharply if you use this function from a bound -- thread. Note in particular that the main thread is a bound thread when -- you use ghc -threaded. -- -- To avoid this problem, do one of these: -- -- toLazyByteString :: Builder -> ByteString -- | Like toLazyByteString, but allows the user to specify the -- initial and the subsequent desired buffer sizes. toLazyByteStringWith :: Int -> Int -> Builder -> ByteString -- | Turn a Builder into a strict ByteString. toStrictByteString :: Builder -> ByteString -- | Output a Builder to a Handle. hPutBuilder :: Handle -> Builder -> IO () -- | Turn a value of type a into a Builder, using the given -- BoundedPrim. primBounded :: BoundedPrim a -> a -> Builder -- | Turn a value of type a into a Builder, using the given -- FixedPrim. primFixed :: FixedPrim a -> a -> Builder -- | Turn a list of values of type a into a Builder, using -- the given BoundedPrim. primMapListBounded :: BoundedPrim a -> [a] -> Builder -- | Turn a list of values of type a into a Builder, using -- the given FixedPrim. primMapListFixed :: FixedPrim a -> [a] -> Builder -- | Turn a ByteString to a Builder. byteString :: ByteString -> Builder -- | Turn a ByteString to a Builder. If the size of the -- ByteString is larger than the given threshold, avoid copying it -- as much as possible. byteStringThreshold :: Int -> ByteString -> Builder -- | Turn a ByteString to a Builder. The ByteString -- will be copied to the buffer, regardless of the size. byteStringCopy :: ByteString -> Builder -- | Like byteStringCopy, but assumes that the current buffer is -- large enough. byteStringCopyNoCheck :: ByteString -> Builder -- | Turn a ByteString to a Builder. When possible, the given -- ByteString will not be copied, and inserted directly into the -- output instead. byteStringInsert :: ByteString -> Builder -- | Turn a C String into a Builder. The behavior is undefined if -- the given CString does not point to a constant null-terminated -- string. unsafeCString :: CString -> Builder -- | ensureBytes n ensures that at least n bytes -- of free space is available in the current buffer, by allocating a new -- buffer when necessary. ensureBytes :: Int -> Builder -- | getBytes n allocates a new buffer, containing at least -- n bytes. getBytes :: Int -> Builder -- | rebuild b is equivalent to b, but it allows -- GHC to assume that b will be run at most once. This can -- enable various optimizations that greately improve performance. -- -- There are two types of typical situations where a use of -- rebuild is often a win: -- -- rebuild :: Builder -> Builder instance Functor BuildM instance Show Response instance Monoid Builder instance IsString Builder instance Show ChunkOverflowException instance Exception ChunkOverflowException instance Show SuspendBuilderException instance Exception SuspendBuilderException instance Applicative BuildM instance Monad BuildM instance Monoid Write -- | An efficient implementation of ByteString builder. -- -- In many cases, this module works as a drop-in replacement for -- Data.ByteString.Builder, and should improve speed. However, one caveat -- applies: when using toLazyByteString, if you consume the result -- in a bound thread, performance degrades significantly. See the -- documentation for toLazyByteString for details. -- -- Sometimes performance can be greatly improved by inserting calls to -- rebuild to your program. See the documentation for -- rebuild for details. module Data.ByteString.FastBuilder -- | Builder is an auxiliary type for efficiently generating a long -- ByteString. It is isomorphic to lazy ByteString, but -- offers constant-time concatanation via <>. -- -- Use toLazyByteString to turn a Builder into a -- ByteString data Builder -- | Turn a Builder into a lazy ByteString. -- -- Performance hint: when the resulting ByteString does not -- fit in one chunk, this function forks a thread. Due to this, the -- performance degrades sharply if you use this function from a bound -- thread. Note in particular that the main thread is a bound thread when -- you use ghc -threaded. -- -- To avoid this problem, do one of these: -- -- toLazyByteString :: Builder -> ByteString -- | Like toLazyByteString, but allows the user to specify the -- initial and the subsequent desired buffer sizes. toLazyByteStringWith :: Int -> Int -> Builder -> ByteString -- | Turn a Builder into a strict ByteString. toStrictByteString :: Builder -> ByteString -- | Output a Builder to a Handle. hPutBuilder :: Handle -> Builder -> IO () -- | rebuild b is equivalent to b, but it allows -- GHC to assume that b will be run at most once. This can -- enable various optimizations that greately improve performance. -- -- There are two types of typical situations where a use of -- rebuild is often a win: -- -- rebuild :: Builder -> Builder -- | Turn a value of type a into a Builder, using the given -- BoundedPrim. primBounded :: BoundedPrim a -> a -> Builder -- | Turn a value of type a into a Builder, using the given -- FixedPrim. primFixed :: FixedPrim a -> a -> Builder -- | Turn a ByteString to a Builder. byteString :: ByteString -> Builder -- | Turn a ByteString to a Builder. When possible, the given -- ByteString will not be copied, and inserted directly into the -- output instead. byteStringInsert :: ByteString -> Builder -- | Turn a ByteString to a Builder. The ByteString -- will be copied to the buffer, regardless of the size. byteStringCopy :: ByteString -> Builder -- | Turn a ByteString to a Builder. If the size of the -- ByteString is larger than the given threshold, avoid copying it -- as much as possible. byteStringThreshold :: Int -> ByteString -> Builder int8 :: Int8 -> Builder word8 :: Word8 -> Builder int16LE :: Int16 -> Builder int32LE :: Int32 -> Builder int64LE :: Int64 -> Builder word16LE :: Word16 -> Builder word32LE :: Word32 -> Builder word64LE :: Word64 -> Builder floatLE :: Float -> Builder doubleLE :: Double -> Builder int16BE :: Int16 -> Builder int32BE :: Int32 -> Builder int64BE :: Int64 -> Builder word16BE :: Word16 -> Builder word32BE :: Word32 -> Builder word64BE :: Word64 -> Builder floatBE :: Float -> Builder doubleBE :: Double -> Builder intHost :: Int -> Builder int16Host :: Int16 -> Builder int32Host :: Int32 -> Builder int64Host :: Int64 -> Builder wordHost :: Word -> Builder word16Host :: Word16 -> Builder word32Host :: Word32 -> Builder word64Host :: Word64 -> Builder floatHost :: Float -> Builder doubleHost :: Double -> Builder intDec :: Int -> Builder int8Dec :: Int8 -> Builder int16Dec :: Int16 -> Builder int32Dec :: Int32 -> Builder int64Dec :: Int64 -> Builder wordDec :: Word -> Builder word8Dec :: Word8 -> Builder word16Dec :: Word16 -> Builder word32Dec :: Word32 -> Builder word64Dec :: Word64 -> Builder integerDec :: Integer -> Builder floatDec :: Double -> Builder doubleDec :: Double -> Builder wordHex :: Word -> Builder word8Hex :: Word8 -> Builder word16Hex :: Word16 -> Builder word32Hex :: Word32 -> Builder word64Hex :: Word64 -> Builder int8HexFixed :: Int8 -> Builder int16HexFixed :: Int16 -> Builder int32HexFixed :: Int32 -> Builder int64HexFixed :: Int64 -> Builder word8HexFixed :: Word8 -> Builder word16HexFixed :: Word16 -> Builder word32HexFixed :: Word32 -> Builder word64HexFixed :: Word64 -> Builder floatHexFixed :: Float -> Builder doubleHexFixed :: Double -> Builder charUtf8 :: Char -> Builder stringUtf8 :: String -> Builder char7 :: Char -> Builder string7 :: String -> Builder char8 :: Char -> Builder string8 :: String -> Builder