diff --git a/Data/ByteString/Plain.hs b/Data/ByteString/Plain.hs new file mode 100644 --- /dev/null +++ b/Data/ByteString/Plain.hs @@ -0,0 +1,162 @@ +{-# LANGUAGE MagicHash, DeriveDataTypeable #-} + +-- | +-- Stability : experimental +-- Portability : GHC +-- +-- This module is intended to be imported @qualified@ in order to +-- avoid name clashes with the "Prelude", "Data.ByteString", and +-- "Data.ByteString.Lazy" modules. E.g.: +-- +-- > import qualified Data.ByteString.Plain as PB +-- +module Data.ByteString.Plain ( + -- * The plain @ByteString@ type and representation + ByteString + -- * Introducing and eliminating 'ByteString's + , empty + , fromStrict + , toStrict + -- * Basic operations + , null + , length + ) where + +import Control.DeepSeq (NFData) +import qualified Data.ByteString as B +import qualified Data.ByteString.Internal as B +import Data.Hashable (Hashable(hashWithSalt)) +import Data.Typeable (Typeable) +import GHC.ForeignPtr +import GHC.Prim +import GHC.Types +import Prelude hiding (length, null) +import System.IO.Unsafe (unsafePerformIO) + +-- |Compact heap representation a (strict) 'B.ByteString' can be (un)wrapped to/from. +-- +-- This data type depends on the ordinary 'B.ByteString' type to be +-- useful but comes with a different cost-model. +-- +-- This representation avoids the 'ForeignPtr' indirection, and the +-- offset/length slice representation for shared 'B.ByteString's, and +-- is therefore suitable if you need to store many small strings in a +-- data records or for use as keys in container types. On the other +-- hand, string operations on 'ByteString' would require +-- re-allocations, and thus are not supported. If you need to perform +-- such operations convert and operate on conventional 'B.ByteString's +-- instead. +-- +-- This structure supports @UNPACK@, and then has an overhead +-- of only 3 words (beyond the word-padded storage of the byte-string +-- payload), as it's basically just a pointer to a +-- 'MutableByteArray#': +-- +-- > data ByteString = PBS !(MutableByteArray# RealWorld) +-- +-- In contrast, a single non-shared unpacked ('PlainPtr'-backed) +-- 'ByteString' field exhibits an overhead of 8 words: +-- +-- > data ByteString = PS {-# UNPACK #-} !(ForeignPtr Word8) -- payload (2 words) +-- > {-# UNPACK #-} !Int -- offset (1 word) +-- > {-# UNPACK #-} !Int -- length (1 word) +-- > +-- > data ForeignPtr a = ForeignPtr Addr# ForeignPtrContents -- 2 words w/o info-ptr +-- > +-- > data ForeignPtrContents -- 1 word needed for info-ptr +-- > = PlainForeignPtr {...} +-- > | MallocPtr {...} +-- > | PlainPtr (MutableByteArray# RealWorld) -- common case (1 word) +-- > +-- > data MutableByteArray# s -- 2 words + payload +-- +-- As an optimization, all zero-length strings are mapped to the +-- singleton 'empty' value. +data ByteString = PBS !(MutableByteArray# RealWorld) + deriving Typeable + +-- |Singleton value the 'B.empty' 'B.ByteString' is mapped to/from. +empty :: ByteString +empty = unsafePerformIO $ do + (ForeignPtr _ (PlainPtr mbarr#)) <- mallocPlainForeignPtrBytes 0 + return $! PBS mbarr# +{-# NOINLINE empty #-} + +-- |Extract 'ByteString' from 'ByteString' +-- +-- If possible, the internally used 'MutableByteArray#' is shared with +-- the original 'ByteString' in which case the conversion is cheap. +-- +-- However, if necessary, a trimmed copy of the original 'ByteString' +-- will be created via 'B.copy' resulting in a newly allocated +-- 'MutableByteArray#'. +-- +-- N.B.: Because strict 'B.ByteString's use pinned memory internally +-- also plain 'ByteString's use pinned memory and thereby increase the +-- potential for memory fragmentation as the garbage collector is not +-- allowed to move pinned memory areas. +-- +-- Depending on the use case, it might be beneficial to apply some +-- form of memoizing to the 'fromStrict' conversion (also known as +-- or +-- ). + +fromStrict :: B.ByteString -> ByteString +fromStrict (B.PS _ _ 0) = empty +fromStrict (B.PS (ForeignPtr addr (PlainPtr mbarr#)) 0 l) + | neAddr# addr' addr = error "internal error" -- sanity check + | l' == l = PBS mbarr# + where + l' = I# (sizeofMutableByteArray# mbarr#) + addr' = byteArrayContents# (unsafeCoerce# mbarr#) +fromStrict bs = fromStrict (B.copy bs) -- this assumes + -- ByteString internals return a trimmed + -- ForeignPtr/PlainPtr string; otherwise there's + -- risk of infinite looping +{-# INLINE fromStrict #-} + +-- |Convert a plain 'ByteString' back into a 'ByteString'. +-- +-- This effectively wraps the plain 'ByteString' into a 'ForeignPtr' +-- and a plain 'B.ByteString' type. +toStrict :: ByteString -> B.ByteString +toStrict (PBS mbarr#) | l == 0 = B.empty + | otherwise = B.PS fp 0 l + where + l = I# (sizeofMutableByteArray# mbarr#) + addr = byteArrayContents# (unsafeCoerce# mbarr#) + fp = ForeignPtr addr (PlainPtr mbarr#) +{-# INLINE toStrict #-} + +null :: ByteString -> Bool +null = (==0) . length +{-# INLINE null #-} + +length :: ByteString -> Int +length (PBS mbarr#) = I# (sizeofMutableByteArray# mbarr#) +{-# INLINE length #-} + +-- WHNF == NF +instance NFData ByteString + +-- the following instances are implement via strict 'B.ByteString's; +-- In the future "native" implementations shall be provided if they +-- result being faster. +instance Eq ByteString where + x == y = toStrict x == toStrict y + {-# INLINE (==) #-} + +instance Ord ByteString where + compare x y = compare (toStrict x) (toStrict y) + {-# INLINE compare #-} + +instance Hashable ByteString where + hashWithSalt salt = hashWithSalt salt . toStrict + {-# INLINE hashWithSalt #-} + +-- Mostly for convenience +instance Show ByteString where + showsPrec p rbs = showsPrec p (toStrict rbs) + +instance Read ByteString where + readsPrec p str = [ (fromStrict x, y) | (x, y) <- readsPrec p str ] diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,30 @@ +Copyright (c) 2013, Herbert Valerio Riedel + +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + * Neither the name of Herbert Valerio Riedel nor the names of other + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/bytestring-plain.cabal b/bytestring-plain.cabal new file mode 100644 --- /dev/null +++ b/bytestring-plain.cabal @@ -0,0 +1,39 @@ +name: bytestring-plain +version: 0.1.0.0 +synopsis: Plain byte strings ('ForeignPtr'-less 'ByteString's) +homepage: https://github.com/hvr/bytestring-plain +bug-reports: https://github.com/hvr/bytestring-plain/issues +license: BSD3 +license-file: LICENSE +author: Herbert Valerio Riedel +maintainer: hvr@gnu.org +copyright: (c) 2013 Herbert Valerio Riedel +category: Data +build-type: Simple +tested-with: GHC ==7.6.3 +cabal-version: >=1.14 +description: + More compact representation for strict 'ByteString's avoiding the + overhead and indirection caused by 'ForeignPtr'. + . + This representation is useful to reduce the incurred memory overhead + when operating with many small, long-lived, distinct byte strings + (such as keys for containers). + . + See documentation in "Data.ByteString.Plain" for more details about + this representation. + +library + default-language: Haskell2010 + exposed-modules: Data.ByteString.Plain + other-extensions: MagicHash + build-depends: base >= 4.6 && <4.7, + bytestring >= 0.10 && <0.11, + ghc-prim >= 0.3 && <0.4, + deepseq >= 1.2 && <1.4, + hashable >= 1.1.1 && <1.3 + ghc-options: -Wall + +Source-Repository head + Type: git + Location: https://github.com/hvr/bytestring-plain.git