doc: document table configuration

Author: wenkokke

README.md

@@ -227,7 +227,7 @@ cmdP = O.subparser $ mconcat
 
 setupOptsP :: O.Parser SetupOpts
 setupOptsP = pure SetupOpts
-    <*> O.option O.auto (O.long "bloom-filter-alloc" <> O.value LSM.defaultBloomFilterAlloc <> O.showDefault <> O.help "Bloom filter allocation method [AllocFixed n | AllocRequestFPR d]")
+    <*> O.option O.auto (O.long "bloom-filter-alloc" <> O.value (LSM.confBloomFilterAlloc LSM.defaultTableConfig) <> O.showDefault <> O.help "Bloom filter allocation method [AllocFixed n | AllocRequestFPR d]")
 
 runOptsP :: O.Parser RunOpts
 runOptsP = pure RunOpts

bench/macro/lsm-tree-bench-wp8.hs

@@ -113,13 +113,12 @@ module Database.LSMTree (
   ),
   defaultTableConfig,
   MergePolicy (LazyLevelling),
+  MergeSchedule (..),
   SizeRatio (Four),
   WriteBufferAlloc (AllocNumEntries),
   BloomFilterAlloc (AllocFixed, AllocRequestFPR),
-  defaultBloomFilterAlloc,
   FencePointerIndexType (OrdinaryIndex, CompactIndex),
   DiskCachePolicy (..),
-  MergeSchedule (..),
 
   -- ** Table Configuration Overrides #table_configuration_overrides#
   OverrideDiskCachePolicy (..),
@@ -217,8 +216,7 @@ import           Database.LSMTree.Internal.Config
                      DiskCachePolicy (..), FencePointerIndexType (..),
                      LevelNo (..), MergePolicy (..), MergeSchedule (..),
                      SizeRatio (..), TableConfig (..), WriteBufferAlloc (..),
-                     defaultBloomFilterAlloc, defaultTableConfig,
-                     serialiseKeyMinimalSize)
+                     defaultTableConfig, serialiseKeyMinimalSize)
 import           Database.LSMTree.Internal.Config.Override
                      (OverrideDiskCachePolicy (..))
 import           Database.LSMTree.Internal.Entry (NumEntries (..))

lsm-tree.cabal

@@ -48,10 +48,13 @@ import           Database.LSMTree.Internal.Snapshot
   Override disk cache policy
 -------------------------------------------------------------------------------}
 
--- | Override the 'DiskCachePolicy'
+{- |
+The 'OverrideDiskCachePolicy' can be used to override the 'DiskCachePolicy'
+when opening a table from a snapshot.
+-}
 data OverrideDiskCachePolicy =
-    OverrideDiskCachePolicy DiskCachePolicy
-  | NoOverrideDiskCachePolicy
+    NoOverrideDiskCachePolicy
+  | OverrideDiskCachePolicy DiskCachePolicy
   deriving stock (Show, Eq)
 
 -- | Override the disk cache policy that is stored in snapshot metadata.

src/Database/LSMTree.hs

@@ -494,7 +494,7 @@ updatesWithInterleavedFlushes tr conf resolve hfs hbio root uc es reg tc = do
     (wb', es') <- addWriteBufferEntries hfs resolve wbblobs maxn wb es
     -- Supply credits before flushing, so that we complete merges in time. The
     -- number of supplied credits is based on the size increase of the write
-    -- buffer, not the the number of processed entries @length es' - length es@.
+    -- buffer, not the number of processed entries @length es' - length es@.
     let numAdded = unNumEntries (WB.numEntries wb') - unNumEntries (WB.numEntries wb)
     supplyCredits conf (NominalCredits numAdded) (tableLevels tc)
     let tc' = tc { tableWriteBuffer = wb' }

src/Database/LSMTree/Internal/Config.hs

@@ -13,9 +13,13 @@ import           Control.DeepSeq (NFData (..))
 
 -- | A range of keys.
 data Range k =
-    -- | Inclusive lower bound, exclusive upper bound
+    {- |
+    @'FromToExcluding' i j@ is the ranges from @i@ (inclusive) to @j@ (exclusive).
+    -}
     FromToExcluding k k
-    -- | Inclusive lower bound, inclusive upper bound
+    {- |
+    @'FromToIncluding' i j@ is the ranges from @i@ (inclusive) to @j@ (inclusive).
+    -}
   | FromToIncluding k k
   deriving stock (Show, Eq, Functor)
 

src/Database/LSMTree/Internal/Config/Override.hs

@@ -69,6 +69,7 @@ import           Prelude hiding (drop, take)
 import           GHC.Exts
 import           GHC.Stack
 import           GHC.Word
+import           Text.Printf (printf)
 
 {- Note: [Export structure]
    ~~~~~~~~~~~~~~~~~~~~~~~
@@ -80,15 +81,30 @@ import           GHC.Word
   Raw bytes
 -------------------------------------------------------------------------------}
 
--- | Raw bytes with no alignment constraint (i.e. byte aligned), and no
--- guarantee of pinned or unpinned memory (i.e. could be either).
+{- |
+Raw bytes.
+
+This type imposes no alignment constraint and provides no guarantee of whether the memory is pinned or unpinned.
+-}
 newtype RawBytes = RawBytes (VP.Vector Word8)
-  deriving newtype (Show, NFData)
+  deriving newtype (NFData)
+
+-- TODO: Should we have a more well-behaved instance for 'Show'?
+--       For instance, an instance that prints the bytes as a hexadecimal string?
+deriving newtype instance Show RawBytes
+
+_showBytesAsHex :: RawBytes -> ShowS
+_showBytesAsHex (RawBytes bytes) = VP.foldr ((.) . showByte) id bytes
+  where
+    showByte :: Word8 -> ShowS
+    showByte = showString . printf "%02x"
 
 instance Eq RawBytes where
   bs1 == bs2 = compareBytes bs1 bs2 == EQ
 
--- | Lexicographical 'Ord' instance.
+{- |
+This instance uses lexicographic ordering.
+-}
 instance Ord RawBytes where
   compare = compareBytes
 
@@ -113,6 +129,11 @@ instance Hashable RawBytes where
 hash :: Word64 -> RawBytes -> Word64
 hash salt (RawBytes (VP.Vector off len ba)) = hashByteArray ba off len salt
 
+{- |
+@'fromList'@: \(O(n)\).
+
+@'toList'@: \(O(n)\).
+-}
 instance IsList RawBytes where
   type Item RawBytes = Word8
 
@@ -122,9 +143,13 @@ instance IsList RawBytes where
   toList :: RawBytes -> [Item RawBytes]
   toList = unpack
 
--- | Mostly to make test cases shorter to write.
+{- |
+@'fromString'@: \(O(n)\).
+
+__Warning:__ 'fromString' truncates multi-byte characters to octets. e.g. \"枯朶に烏のとまりけり秋の暮\" becomes \"�6k�nh~�Q��n�\".
+-}
 instance IsString RawBytes where
-    fromString = pack . map (fromIntegral . fromEnum)
+    fromString = fromByteString . fromString
 
 {-------------------------------------------------------------------------------
   Accessors
@@ -171,9 +196,19 @@ toWord64 x# = byteSwap64 (W64# x#)
   Construction
 -------------------------------------------------------------------------------}
 
+{- |
+@('<>')@: \(O(n)\).
+
+@'Data.Semigroup.sconcat'@: \(O(n)\).
+-}
 instance Semigroup RawBytes where
     (<>) = coerce (VP.++)
 
+{- |
+@'mempty'@: \(O(1)\).
+
+@'mconcat'@: \(O(n)\).
+-}
 instance Monoid RawBytes where
     mempty = coerce VP.empty
     mconcat = coerce VP.concat