-- 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.1.0


-- | This is an internal module; its interface is unstable.
module Data.ByteString.FastBuilder.Internal

-- | <a>Builder</a> is an auxiliary type for efficiently generating a long
--   <a>ByteString</a>. It is isomorphic to lazy <a>ByteString</a>, but
--   offers constant-time concatanation via <a>&lt;&gt;</a>.
--   
--   Use <a>toLazyByteString</a> to turn a <a>Builder</a> into a
--   <a>ByteString</a>
newtype Builder
Builder :: (DataSink -> BuilderState -> BuilderState) -> Builder
[unBuilder] :: Builder -> DataSink -> BuilderState -> BuilderState

-- | This datatype exists only to work around the limitation that
--   <a>oneShot</a> 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 <a>Queue</a>, then flushed to the
--   <a>Handle</a>.
HandleSink :: !Handle -> !Int -> !(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
--   <a>ThreadedSink</a>.
BoundedGrowingBuffer :: {-# UNPACK #-} !(ForeignPtr Word8) -> !Int -> DynamicSink

-- | A mutable buffer. The <a>Int</a> 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 <a>toLazyByteString</a>. 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 <a>MVar</a>.
data SuspendBuilderException
SuspendBuilderException :: !(MVar ()) -> SuspendBuilderException

-- | Used in the implementation of <a>toLazyByteString</a>. 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 <a>ThreadedSink</a>.
data ChunkOverflowException
ChunkOverflowException :: !ByteString -> !(MVar Request) -> !(MVar Response) -> !Int -> ChunkOverflowException

-- | An internal type that is isomorphic to <a>Builder</a>. 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
--   <tt><a>BuildM</a> a</tt> can do everything a <a>Builder</a> can do,
--   and in addition, returns a value of type <tt>a</tt> upon completion.
newtype BuildM a
BuildM :: ((a -> Builder) -> Builder) -> BuildM a
[runBuildM] :: BuildM a -> (a -> Builder) -> Builder

-- | Convert a <a>Builder</a> into a <a>Builder_</a>.
toBuilder_ :: Builder -> Builder_

-- | Convert a <a>Builder_</a> into a <a>Builder</a>.
fromBuilder_ :: Builder_ -> Builder

-- | Create a builder from a BuildM.
mkBuilder :: BuildM () -> Builder

-- | Embed a builder in the BuildM context.
useBuilder :: Builder -> BuildM ()

-- | Get the <a>DataSink</a>.
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 <a>Builder</a> into a lazy <a>ByteString</a>.
--   
--   <b>Performance hint</b>: when the resulting <a>ByteString</a> 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 <tt>ghc -threaded</tt>.
--   
--   To avoid this problem, do one of these:
--   
--   <ul>
--   <li>Make sure the resulting <a>ByteString</a> is consumed in an
--   unbound thread. Consider using <tt>runInUnboundThread</tt> for
--   this.</li>
--   <li>Use other function to run the <a>Builder</a> instead. Functions
--   that don't return a lazy <a>ByteString</a> do not have this
--   issue.</li>
--   <li>Link your program without <tt>-threaded</tt>.</li>
--   </ul>
toLazyByteString :: Builder -> ByteString

-- | Like <a>toLazyByteString</a>, but allows the user to specify the
--   initial and the subsequent desired buffer sizes.
toLazyByteStringWith :: Int -> Int -> Builder -> ByteString

-- | Turn a <a>Builder</a> into a strict <a>ByteString</a>.
toStrictByteString :: Builder -> ByteString

-- | Output a <a>Builder</a> to a <a>Handle</a>.
hPutBuilder :: Handle -> Builder -> IO ()

-- | Like <tt>hPutBuffer</tt>, but allows the user to specify the initial
--   and the subsequent desired buffer sizes. This function may be useful
--   for setting large buffer when high throughput I/O is needed.
hPutBuilderWith :: Handle -> Int -> Int -> Builder -> IO ()

-- | Turn a value of type <tt>a</tt> into a <a>Builder</a>, using the given
--   <a>BoundedPrim</a>.
primBounded :: BoundedPrim a -> a -> Builder

-- | Turn a value of type <tt>a</tt> into a <a>Builder</a>, using the given
--   <a>FixedPrim</a>.
primFixed :: FixedPrim a -> a -> Builder

-- | Turn a list of values of type <tt>a</tt> into a <a>Builder</a>, using
--   the given <a>BoundedPrim</a>.
primMapListBounded :: BoundedPrim a -> [a] -> Builder

-- | Turn a list of values of type <tt>a</tt> into a <a>Builder</a>, using
--   the given <a>FixedPrim</a>.
primMapListFixed :: FixedPrim a -> [a] -> Builder

-- | Turn a <a>ByteString</a> to a <a>Builder</a>.
byteString :: ByteString -> Builder

-- | Turn a <a>ByteString</a> to a <a>Builder</a>. If the size of the
--   <a>ByteString</a> is larger than the given threshold, avoid copying it
--   as much as possible.
byteStringThreshold :: Int -> ByteString -> Builder

-- | Turn a <a>ByteString</a> to a <a>Builder</a>. The <a>ByteString</a>
--   will be copied to the buffer, regardless of the size.
byteStringCopy :: ByteString -> Builder

-- | Like <a>byteStringCopy</a>, but assumes that the current buffer is
--   large enough.
byteStringCopyNoCheck :: ByteString -> Builder

-- | Turn a <a>ByteString</a> to a <a>Builder</a>. When possible, the given
--   <a>ByteString</a> will not be copied, and inserted directly into the
--   output instead.
byteStringInsert :: ByteString -> Builder

-- | Turn a C String into a <a>Builder</a>. The behavior is undefined if
--   the given <a>CString</a> does not point to a constant null-terminated
--   string.
unsafeCString :: CString -> Builder

-- | Turn a <a>CStringLen</a> into a <a>Builder</a>. The behavior is
--   undefined if the given <a>CStringLen</a> does not point to a constant
--   memory block.
unsafeCStringLen :: CStringLen -> Builder

-- | <tt><a>ensureBytes</a> n</tt> ensures that at least <tt>n</tt> bytes
--   of free space is available in the current buffer, by allocating a new
--   buffer when necessary.
ensureBytes :: Int -> Builder

-- | <tt><a>getBytes</a> n</tt> allocates a new buffer, containing at least
--   <tt>n</tt> bytes.
getBytes :: Int -> Builder

-- | <tt><a>rebuild</a> b</tt> is equivalent to <tt>b</tt>, but it allows
--   GHC to assume that <tt>b</tt> 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
--   <a>rebuild</a> is often a win:
--   
--   <ul>
--   <li>When constructing a builder using a recursive function. e.g.
--   <tt>rebuild $ foldr ...</tt>.</li>
--   <li>When constructing a builder using a conditional expression. e.g.
--   <tt>rebuild $ case x of ... </tt></li>
--   </ul>
rebuild :: Builder -> Builder
instance GHC.Base.Functor Data.ByteString.FastBuilder.Internal.BuildM
instance GHC.Show.Show Data.ByteString.FastBuilder.Internal.Response
instance GHC.Base.Monoid Data.ByteString.FastBuilder.Internal.Write
instance GHC.Base.Applicative Data.ByteString.FastBuilder.Internal.BuildM
instance GHC.Base.Monad Data.ByteString.FastBuilder.Internal.BuildM
instance GHC.Show.Show Data.ByteString.FastBuilder.Internal.SuspendBuilderException
instance GHC.Exception.Exception Data.ByteString.FastBuilder.Internal.SuspendBuilderException
instance GHC.Show.Show Data.ByteString.FastBuilder.Internal.ChunkOverflowException
instance GHC.Exception.Exception Data.ByteString.FastBuilder.Internal.ChunkOverflowException
instance GHC.Base.Monoid Data.ByteString.FastBuilder.Internal.Builder
instance Data.String.IsString Data.ByteString.FastBuilder.Internal.Builder


-- | 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.
--   
--   <h1>Performance tips</h1>
--   
--   fast-builder should be faster than the standard builder in most
--   situations. However, by following certain code patterns, you can often
--   achive even more efficient code, with almost no memory allocation
--   aside from the resulting <tt>ByteString</tt> itself. The below are a
--   list of hints for writing efficient code for constructing builders.
--   
--   <h2>Return builders directly from your function</h2>
--   
--   Once you construct a builder, it's usually a good idea to just return
--   it from your function. Avoid storing it in a data structure or passing
--   it to another function, unless they are going to be eliminated by the
--   compiler. Schematically, prefer this:
--   
--   <pre>
--   good :: YourDataStructure -&gt; Builder
--   good d = serializeThis (this d) &lt;&gt; serializeThat (that d)
--   </pre>
--   
--   over:
--   
--   <pre>
--   bad0 :: YourDataStructure -&gt; (Int, Builder)
--   bad0 d
--      = (compute d, serializeThis (this d) &lt;&gt; serializeThat (that d))
--   </pre>
--   
--   or:
--   
--   <pre>
--   bad1 :: YourDataStructure -&gt; Builder
--   bad1 d = serializeMore d (serializeThis (this d))
--   </pre>
--   
--   An important special case of this general rule is to prefer foldr over
--   foldl' when serializing a list, and to prefer structural recursion
--   over tail recursion in general.
--   
--   <h3>Use <a>rebuild</a></h3>
--   
--   When your function returns a different builder depending on the input,
--   it's usually a good idea to use <a>rebuild</a> to wrap the whole body
--   of your function. See the documentation for <a>rebuild</a> for
--   details.
--   
--   <h3>Background</h3>
--   
--   Why is it good to return builders directly? It is because they are
--   implemented as functions. When storing a function in a data structure
--   or passing it around, you need to first allocate a closure for it.
--   However, if you are just returning it, the returned function can be
--   merged with your function, creating a function with a larger arity.
--   For example, GHC can compile the <tt>good</tt> function above into a
--   5-ary function, which requires no runtime allocation (the exact arity
--   depends on the library version).
--   
--   <h2>Watch out for lazy ByteString generation</h2>
--   
--   When using <a>toLazyByteString</a>, if you consume the result in a
--   bound thread, performance degrades significantly. See the
--   documentation for <a>toLazyByteString</a> for details.
module Data.ByteString.FastBuilder

-- | <a>Builder</a> is an auxiliary type for efficiently generating a long
--   <a>ByteString</a>. It is isomorphic to lazy <a>ByteString</a>, but
--   offers constant-time concatanation via <a>&lt;&gt;</a>.
--   
--   Use <a>toLazyByteString</a> to turn a <a>Builder</a> into a
--   <a>ByteString</a>
data Builder

-- | Turn a <a>Builder</a> into a lazy <a>ByteString</a>.
--   
--   <b>Performance hint</b>: when the resulting <a>ByteString</a> 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 <tt>ghc -threaded</tt>.
--   
--   To avoid this problem, do one of these:
--   
--   <ul>
--   <li>Make sure the resulting <a>ByteString</a> is consumed in an
--   unbound thread. Consider using <tt>runInUnboundThread</tt> for
--   this.</li>
--   <li>Use other function to run the <a>Builder</a> instead. Functions
--   that don't return a lazy <a>ByteString</a> do not have this
--   issue.</li>
--   <li>Link your program without <tt>-threaded</tt>.</li>
--   </ul>
toLazyByteString :: Builder -> ByteString

-- | Like <a>toLazyByteString</a>, but allows the user to specify the
--   initial and the subsequent desired buffer sizes.
toLazyByteStringWith :: Int -> Int -> Builder -> ByteString

-- | Turn a <a>Builder</a> into a strict <a>ByteString</a>.
toStrictByteString :: Builder -> ByteString

-- | Output a <a>Builder</a> to a <a>Handle</a>.
hPutBuilder :: Handle -> Builder -> IO ()

-- | Like <tt>hPutBuffer</tt>, but allows the user to specify the initial
--   and the subsequent desired buffer sizes. This function may be useful
--   for setting large buffer when high throughput I/O is needed.
hPutBuilderWith :: Handle -> Int -> Int -> Builder -> IO ()

-- | <tt><a>rebuild</a> b</tt> is equivalent to <tt>b</tt>, but it allows
--   GHC to assume that <tt>b</tt> 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
--   <a>rebuild</a> is often a win:
--   
--   <ul>
--   <li>When constructing a builder using a recursive function. e.g.
--   <tt>rebuild $ foldr ...</tt>.</li>
--   <li>When constructing a builder using a conditional expression. e.g.
--   <tt>rebuild $ case x of ... </tt></li>
--   </ul>
rebuild :: Builder -> Builder

-- | Turn a value of type <tt>a</tt> into a <a>Builder</a>, using the given
--   <a>BoundedPrim</a>.
primBounded :: BoundedPrim a -> a -> Builder

-- | Turn a value of type <tt>a</tt> into a <a>Builder</a>, using the given
--   <a>FixedPrim</a>.
primFixed :: FixedPrim a -> a -> Builder

-- | Turn a <a>ByteString</a> to a <a>Builder</a>.
byteString :: ByteString -> Builder

-- | Turn a <a>ByteString</a> to a <a>Builder</a>. When possible, the given
--   <a>ByteString</a> will not be copied, and inserted directly into the
--   output instead.
byteStringInsert :: ByteString -> Builder

-- | Turn a <a>ByteString</a> to a <a>Builder</a>. The <a>ByteString</a>
--   will be copied to the buffer, regardless of the size.
byteStringCopy :: ByteString -> Builder

-- | Turn a <a>ByteString</a> to a <a>Builder</a>. If the size of the
--   <a>ByteString</a> 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


-- | Unsafe functions.
module Data.ByteString.FastBuilder.Unsafe

-- | Turn a C String into a <a>Builder</a>. The behavior is undefined if
--   the given <a>CString</a> does not point to a constant null-terminated
--   string.
unsafeCString :: CString -> Builder

-- | Turn a <a>CStringLen</a> into a <a>Builder</a>. The behavior is
--   undefined if the given <a>CStringLen</a> does not point to a constant
--   memory block.
unsafeCStringLen :: CStringLen -> Builder
