mason
Fast and extensible bytestring builder
LTS Haskell 22.37: | 0.2.6 |
Stackage Nightly 2024-07-21: | 0.2.6 |
Latest on Hackage: | 0.2.6 |
mason-0.2.6@sha256:87e6233cf21222c2bb3392e453ad9ee4257a850c75bfb2537461f60574ce87e9,1274
Module documentation for 0.2.6
mason: alacritous builder library
mason is a builder & IO library.
- Fast: much faster than bytestring’s Builder.
- Extensible: Builders can be consumed in a user-defined way.
- Hackable: Low-level APIs are exposed. It’s easy to plug in even pointer-level operations.
Mason.Builder
has API mostly compatible with Data.ByteString.Builder
but there are some additions to the original API:
toStrictByteString
produces a strictByteString
directly.hPutBuilderLen
writes a builder to a handle and returns the number of bytes.sendBuilder
sends the content ofBuilder
over a socket.withPopper
turns a builder into http-client’sGivesPoppertoStreamingBody
creates wai’s StreamingBody
Usage
Replace Data.ByteString.Builder
with Mason.Builder
. Note that if you have Builder
in the type signature, you’ll need RankNTypes
extensions because of the design explained below. Alternatively, you can also import Mason.Builder.Compat
which has an API almost compatible with Data.ByteString.Builder
.
Performance
As long as the code is optimised, mason’s builder can be very fast (twice or more as bytestring). Make sure that functions returning Builder
s are well inlined.
Serialisation of JSON-like structure:
mason/hPutBuilder mean 274.7 μs ( +- 49.40 μs )
fast-builder/hPutBuilder mean 399.9 μs ( +- 76.05 μs )
bytestring/hPutBuilder mean 335.1 μs ( +- 86.96 μs )
mason/toStrictByteString mean 106.6 μs ( +- 6.680 μs )
fast-builder/toStrictByteString mean 254.8 μs ( +- 31.64 μs )
bytestring/toLazyByteString mean 283.3 μs ( +- 24.26 μs )
mason/toLazyByteString mean 127.2 μs ( +- 25.86 μs )
fast-builder/toLazyByteString mean 249.0 μs ( +- 25.60 μs )
bytestring/toLazyByteString mean 263.4 μs ( +- 9.401 μs )
In the same benchmark application, the allocation footprint of mason is feathery.
toStrictByteString
mason 291,112 0
fast-builder 991,016 0
bytestring 1,158,584 0 (toStrict . toLazyByteString)
toLazyByteString
Case Allocated GCs
mason 228,936 0
fast-builder 903,752 0
bytestring 1,101,448 0
doubleDec
employs Grisu3 which grants ~20x speedup over show
-based implementation.
mason/double mean 116.2 ns ( +- 6.654 ns )
fast-builder/double mean 2.183 μs ( +- 85.80 ns )
bytestring/double mean 2.312 μs ( +- 118.8 ns )
You can find more benchmarks below:
Architecture
Mason’s builder is a function that takes a purpose-dependent environment and a buffer. There is little intermediate structure involved; almost everything runs in one pass. This design is inspired by fast-builder.
type Builder = forall s. Buildable s => BuilderFor s
newtype BuilderFor s = Builder { unBuilder :: s -> Buffer -> IO Buffer }
data Buffer = Buffer
{ bEnd :: {-# UNPACK #-} !(Ptr Word8) -- ^ end of the buffer (next to the last byte)
, bCur :: {-# UNPACK #-} !(Ptr Word8) -- ^ current position
}
class Buildable s where
byteString :: B.ByteString -> BuilderFor s
flush :: BuilderFor s
allocate :: Int -> BuilderFor s
Instances of the Buildable
class implement purpose-specific behaviour (e.g. exponentially allocate a buffer, flush to disk). This generic interface also allows creative uses of Builders such as on-the-fly compression.
Builder
has a smart constructor called ensure
:
ensure :: Int -> (Buffer -> IO Buffer) -> Builder
ensure n f
secures at least n
bytes in the buffer and passes the pointer to f
. This gives rise to monoid homorphism; namely, ensure m f <> ensure n g
will fuse into ensure (m + n) (f >=> g)
so don’t worry about the overhead of bound checking.
Creating your own primitives
The easiest way to create a new primitive is withPtr
, a simplified version of ensure
. This is quite convenient for calling foreign functions or anything low-level.
-- | Construct a 'Builder' from a "poke" function.
withPtr :: Int -- ^ number of bytes to allocate (if needed)
-> (Ptr Word8 -> IO (Ptr Word8)) -- ^ return a next pointer after writing
-> Builder
grisu v = withPtr 24 $ \ptr -> do
n <- dtoa_grisu3 v ptr
return $ plusPtr ptr (fromIntegral n)
foreign import ccall unsafe "static dtoa_grisu3"
dtoa_grisu3 :: Double -> Ptr Word8 -> IO CInt
Changes
0.2.5
- Supported GHC 9.2.1
0.2.4
- Generalised the argument
intersperse
,unlines
,unwords
from a list to anyFoldable
- Supported GHC 9.0.1
0.2.3
- Added
intDecPadded
- Exported backend types:
StrictByteStringBackend
,LazyByteStringBackend
andBufferedIOBackend
0.2.2
- Added
withPopper
andtoStreamingBody
- Added
viaShow
- Added
intersperse
,unwords
andunlines
- Optmised the internal representation
0.2.1
- Added
Mason.Builder.Compat
0.2
- Added
doubleFixed
,doubleSI
anddoubleExp
- Added
textUtf8
- Added
prefixVarInt
,wordVLQ
andintVLQ
- Renamed
padded
andzeroPadded
topaddedBoundedPrim
andzeroPaddedBoundedPrim
respectively - Added
Mason.Builder.Dynamic
0 – 2019-12-05
- First version. Released on an unsuspecting world.