Introduce classes for indexes and their accumulators

Author: jeltsch

lsm-tree.cabal

@@ -130,6 +130,7 @@ library
     Database.LSMTree.Internal.CRC32C
     Database.LSMTree.Internal.Cursor
     Database.LSMTree.Internal.Entry
+    Database.LSMTree.Internal.Index
     Database.LSMTree.Internal.Index.Compact
     Database.LSMTree.Internal.Index.CompactAcc
     Database.LSMTree.Internal.Index.Ordinary

src-extras/Database/LSMTree/Extras/Index.hs

@@ -1,8 +1,11 @@
+{-|
+    Provides additional support for working with fence pointer indexes and their
+    accumulators.
+-}
 module Database.LSMTree.Extras.Index
 (
     Append (AppendSinglePage, AppendMultiPage),
-    append,
-    append'
+    append
 )
 where
 
@@ -11,12 +14,8 @@ import           Control.Monad.ST.Strict (ST)
 import           Data.Foldable (toList)
 import           Data.Word (Word32)
 import           Database.LSMTree.Internal.Chunk (Chunk)
-import           Database.LSMTree.Internal.Index.CompactAcc (IndexCompactAcc)
-import qualified Database.LSMTree.Internal.Index.CompactAcc as IndexCompact
-                     (appendMulti, appendSingle)
-import           Database.LSMTree.Internal.Index.OrdinaryAcc (IndexOrdinaryAcc)
-import qualified Database.LSMTree.Internal.Index.OrdinaryAcc as IndexOrdinary
-                     (appendMulti, appendSingle)
+import           Database.LSMTree.Internal.Index (IndexAcc, appendMulti,
+                     appendSingle)
 import           Database.LSMTree.Internal.Serialise (SerialisedKey)
 
 -- | Instruction for appending pages, to be used in conjunction with indexes.
@@ -42,31 +41,15 @@ instance NFData Append where
         = rnf key `seq` rnf overflowPageCount
 
 {-|
-    Add information about appended pages to an index under incremental
-    construction.
+    Adds information about appended pages to an index and outputs newly
+    available chunks.
 
-    Internally, 'append' uses 'IndexCompact.appendSingle' and
-    'IndexCompact.appendMulti', and the usage restrictions of those functions
-    apply also here.
+    See the documentation of the 'IndexAcc' class for constraints to adhere to.
 -}
-append :: Append -> IndexCompactAcc s -> ST s [Chunk]
+append :: IndexAcc j => Append -> j s -> ST s [Chunk]
 append instruction indexAcc = case instruction of
     AppendSinglePage minKey maxKey
-        -> toList <$> IndexCompact.appendSingle (minKey, maxKey) indexAcc
-    AppendMultiPage key overflowPageCount
-        -> IndexCompact.appendMulti (key, overflowPageCount) indexAcc
-
-{-|
-    A variant of 'append' for ordinary indexes, which is only used temporarily
-    until there is a type class of index types.
-
-    Internally, 'append'' uses 'IndexOrdinary.appendSingle' and
-    'IndexOrdinary.appendMulti', and the usage restrictions of those functions
-    apply also here.
--}
-append' :: Append -> IndexOrdinaryAcc s -> ST s [Chunk]
-append' instruction indexAcc = case instruction of
-    AppendSinglePage minKey maxKey
-        -> toList <$> IndexOrdinary.appendSingle (minKey, maxKey) indexAcc
+        -> toList <$> appendSingle (minKey, maxKey) indexAcc
     AppendMultiPage key overflowPageCount
-        -> IndexOrdinary.appendMulti (key, overflowPageCount) indexAcc
+        -> appendMulti (key, overflowPageCount) indexAcc
+{-# INLINABLE append #-}

src/Database/LSMTree/Internal/Index.hs

@@ -0,0 +1,100 @@
+{-# LANGUAGE TypeFamilies #-}
+
+{-|
+    Provides a common interface to different types of fence pointer indexes and
+    their accumulators.
+-}
+module Database.LSMTree.Internal.Index
+(
+    Index (search, sizeInPages, fromSBS),
+    IndexAcc (ResultingIndex, appendSingle, appendMulti, unsafeEnd)
+)
+where
+
+import           Control.Monad.ST.Strict (ST)
+import           Data.ByteString.Short (ShortByteString)
+import           Data.Word (Word32)
+import           Database.LSMTree.Internal.Chunk (Chunk)
+import           Database.LSMTree.Internal.Entry (NumEntries)
+import           Database.LSMTree.Internal.Page (NumPages, PageSpan)
+import           Database.LSMTree.Internal.Serialise (SerialisedKey)
+
+-- | The class of index types.
+class Index i where
+
+    {-|
+        Searches for a page span that contains a key–value pair with the given
+        key. If there is indeed such a pair, the result is the corresponding
+        page span; if there is no such pair, the result is an arbitrary but
+        valid page span.
+    -}
+    search :: SerialisedKey -> i -> PageSpan
+
+    -- | Yields the number of pages covered by an index.
+    sizeInPages :: i -> NumPages
+
+    {-|
+        Reads an index along with the number of entries of the respective run
+        from a byte string.
+
+        The byte string must contain the serialised index exactly, with no
+        leading or trailing space. Furthermore, its contents must be stored
+        64-bit-aligned.
+
+        The contents of the byte string may be directly used as the backing
+        memory for the constructed index. Currently, this is done for compact
+        indexes.
+
+        For deserialising numbers, the endianness of the host system is used. If
+        serialisation has been done with a different endianness, this mismatch
+        is detected by looking at the type–version indicator.
+    -}
+    fromSBS :: ShortByteString -> Either String (NumEntries, i)
+
+{-|
+    The class of index accumulator types, where an index accumulator denotes an
+    index under incremental construction.
+
+    Incremental index construction is only guaranteed to work correctly when the
+    following conditions are met:
+
+      * The supplied key ranges do not overlap and are given in ascending order.
+
+      * Each supplied key is at least 8 and at most 65535 bytes long.
+        (Currently, construction of compact indexes needs the former and
+        construction of ordinary indexes needs the latter bound.)
+-}
+class Index (ResultingIndex j) => IndexAcc j where
+
+    -- | The type of indexes constructed by accumulators of a certain type
+    type ResultingIndex j
+
+    {-|
+        Adds information about a single page that fully comprises one or more
+        key–value pairs to an index and outputs newly available chunks.
+
+        See the documentation of the 'IndexAcc' class for constraints to adhere
+        to.
+    -}
+    appendSingle :: (SerialisedKey, SerialisedKey) -> j s -> ST s (Maybe Chunk)
+
+    {-|
+        Adds information about multiple pages that together comprise a single
+        key–value pair to an index and outputs newly available chunks.
+
+        The provided 'Word32' value denotes the number of /overflow/ pages, so
+        that the number of pages that comprise the key–value pair is the
+        successor of that number.
+
+        See the documentation of the 'IndexAcc' class for constraints to adhere
+        to.
+    -}
+    appendMulti :: (SerialisedKey, Word32) -> j s -> ST s [Chunk]
+
+    {-|
+        Returns the constructed index, along with a final chunk in case the
+        serialised key list has not been fully output yet, thereby invalidating
+        the index under construction. Executing @unsafeEnd index@ is only safe
+        when @index@ is not used afterwards.
+    -}
+    unsafeEnd :: j s -> ST s (Maybe Chunk, ResultingIndex j)

src/Database/LSMTree/Internal/Index/Compact.hs

@@ -6,10 +6,10 @@ module Database.LSMTree.Internal.Index.Compact (
     -- $compact
     IndexCompact (..)
     -- * Queries
-  , search
+  , Index.search
+  , Index.sizeInPages
   , countClashes
   , hasClashes
-  , sizeInPages
     -- * Non-incremental serialisation
   , toLBS
     -- * Incremental serialisation
@@ -18,7 +18,7 @@ module Database.LSMTree.Internal.Index.Compact (
   , finalLBS
   , word64VectorToChunk
     -- * Deserialisation
-  , fromSBS
+  , Index.fromSBS
   ) where
 
 import           Control.DeepSeq (NFData (..))
@@ -48,6 +48,9 @@ import           Database.LSMTree.Internal.ByteString (byteArrayFromTo)
 import           Database.LSMTree.Internal.Chunk (Chunk (Chunk))
 import qualified Database.LSMTree.Internal.Chunk as Chunk (toByteString)
 import           Database.LSMTree.Internal.Entry (NumEntries (..))
+import           Database.LSMTree.Internal.Index (Index)
+import qualified Database.LSMTree.Internal.Index as Index (fromSBS, search,
+                     sizeInPages)
 import           Database.LSMTree.Internal.Page
 import           Database.LSMTree.Internal.Serialise
 import           Database.LSMTree.Internal.Unsliced
@@ -378,13 +381,13 @@ instance NFData IndexCompact where
   Queries
 -------------------------------------------------------------------------------}
 
--- |  Searches for a page span that contains a key–value pair with the given key.
---
--- If there is indeed such a pair, the result is the corresponding page span; if
--- there is no such pair, the result is an arbitrary but valid page span.
---
--- See [an informal description of the search algorithm](#search-descr) for more
--- details about the search algorithm.
+{-|
+    For a specification of this operation, see the documentation of [its
+    polymorphic version]('Index.search').
+
+    See [an informal description of the search algorithm](#search-descr) for
+    more details about the search algorithm.
+-}
 search :: SerialisedKey -> IndexCompact -> PageSpan
 -- One way to think of the search algorithm is that it starts with the full page
 -- number interval, and shrinks it to a minimal interval that contains the
@@ -443,7 +446,10 @@ countClashes = Map.size . icTieBreaker
 hasClashes :: IndexCompact -> Bool
 hasClashes = not . Map.null . icTieBreaker
 
--- | The number of pages within the index.
+{-|
+    For a specification of this operation, see the documentation of [its
+    polymorphic version]('Index.sizeInPages').
+-}
 sizeInPages :: IndexCompact -> NumPages
 sizeInPages = NumPages . toEnum . VU.length . icPrimary
 
@@ -548,13 +554,10 @@ putPaddingTo64 written
   Deserialisation
 -------------------------------------------------------------------------------}
 
--- | The input bytestring must be 64 bit aligned and exactly contain the
--- serialised compact index, with no leading or trailing space.
--- It is directly used as the backing memory for the compact index.
---
--- Also note that the implementation reads values in little-endian byte order.
--- If the file has been serialised in big-endian order, the mismatch will be
--- detected by looking at the type–version indicator.
+{-|
+    For a specification of this operation, see the documentation of [its
+    polymorphic version]('Index.fromSBS').
+-}
 fromSBS :: ShortByteString -> Either String (NumEntries, IndexCompact)
 fromSBS (SBS ba') = do
     let ba = ByteArray ba'
@@ -675,6 +678,21 @@ checkedBitVec off len ba
   | otherwise =
       Nothing
 
+{-------------------------------------------------------------------------------
+  Type class instantiation
+-------------------------------------------------------------------------------}
+
+instance Index IndexCompact where
+
+    search :: SerialisedKey -> IndexCompact -> PageSpan
+    search = search
+
+    sizeInPages :: IndexCompact -> NumPages
+    sizeInPages = sizeInPages
+
+    fromSBS :: ShortByteString -> Either String (NumEntries, IndexCompact)
+    fromSBS = fromSBS
+
 {-------------------------------------------------------------------------------
  Vector extras
 -------------------------------------------------------------------------------}