WIP: store the session salt in a session metadata file

Author: jorisdral

bench-unions/Bench/Unions.hs

@@ -292,7 +292,7 @@ doSetup gopts = do
     createDirectoryIfMissing True $ rootDir gopts
 
     -- Populate the specified number of tables
-    LSM.withSession (rootDir gopts) $ \session -> do
+    LSM.withOpenSession (rootDir gopts) $ \session -> do
       -- Create a "baseline" table
       --
       -- We create a single table that *already has* all the same key value pairs
@@ -337,7 +337,7 @@ tableRange gopts =
 -- | Count duplicate keys in all tables that will be unioned together
 doCollisionAnalysis :: GlobalOpts -> IO ()
 doCollisionAnalysis gopts = do
-    LSM.withSession (rootDir gopts) $ \session -> do
+    LSM.withOpenSession (rootDir gopts) $ \session -> do
       seenRef <- newIORef Set.empty
       dupRef <- newIORef Set.empty
 
@@ -381,7 +381,7 @@ doRun gopts opts = do
     withFile dataPath WriteMode $ \h -> do
     hPutStrLn h "# iteration \t baseline (ops/sec) \t union (ops/sec) \t union debt"
 
-    LSM.withSession (rootDir gopts) $ \session -> do
+    LSM.withOpenSession (rootDir gopts) $ \session -> do
     -- Load the baseline table
     LSM.withTableFromSnapshot session baselineTableName label
       $ \baselineTable -> do

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

@@ -416,7 +416,7 @@ doSetup' gopts opts = do
 
     let name = LSM.toSnapshotName "bench"
 
-    LSM.withSession (mkTracer gopts) hasFS hasBlockIO benchSalt (FS.mkFsPath []) $ \session -> do
+    LSM.withOpenSession (mkTracer gopts) hasFS hasBlockIO benchSalt (FS.mkFsPath []) $ \session -> do
         tbl <- LSM.newTableWith @IO @K @V @B (mkTableConfigSetup gopts opts benchTableConfig) session
 
         forM_ (groupsOfN 256 [ 0 .. initialSize gopts ]) $ \batch -> do
@@ -578,7 +578,7 @@ doRun gopts opts = do
 
     let name = LSM.toSnapshotName "bench"
 
-    LSM.withSession (mkTracer gopts) hasFS hasBlockIO benchSalt (FS.mkFsPath []) $ \session ->
+    LSM.withOpenSession (mkTracer gopts) hasFS hasBlockIO benchSalt (FS.mkFsPath []) $ \session ->
       withLatencyHandle $ \h -> do
         -- open snapshot
         -- In checking mode we start with an empty table, since our pure

lsm-tree.cabal

@@ -594,6 +594,7 @@ library
     , lsm-tree:kmerge
     , primitive               ^>=0.9
     , random                  ^>=1.0      || ^>=1.1      || ^>=1.2     || ^>=1.3
+    , serialise               ^>=0.2
     , text                    ^>=2.1.1
     , utf8-string             ^>=1.0
     , vector                  ^>=0.13

src/Database/LSMTree.hs

@@ -19,10 +19,14 @@ module Database.LSMTree (
 
   -- * Sessions
   Session,
-  withSession,
-  withSessionIO,
+  withOpenSession,
+  withOpenSessionIO,
+  withNewSession,
+  withRestoreSession,
   openSession,
   openSessionIO,
+  newSession,
+  restoreSession,
   closeSession,
 
   -- * Tables
@@ -200,8 +204,8 @@ import           Control.DeepSeq (NFData (..))
 import           Control.Exception.Base (assert)
 import           Control.Monad.Class.MonadAsync (MonadAsync)
 import           Control.Monad.Class.MonadST (MonadST)
-import           Control.Monad.Class.MonadThrow (MonadCatch (..), MonadMask,
-                     MonadThrow (..))
+import           Control.Monad.Class.MonadThrow (MonadCatch (..), MonadEvaluate,
+                     MonadMask, MonadThrow (..))
 import           Control.Monad.Primitive (PrimMonad)
 import           Control.Tracer (Tracer)
 import           Data.Bifunctor (Bifunctor (..))
@@ -290,6 +294,7 @@ type IOLike m =
   , MonadMask m
   , PrimMonad m
   , MonadST m
+  , MonadEvaluate m
   )
 
 --------------------------------------------------------------------------------
@@ -384,7 +389,7 @@ runExample action = do
   let createSessionDir = Dir.createDirectoryIfMissing True sessionDir
   let removeSessionDir = Dir.removeDirectoryRecursive sessionDir
   bracket_ createSessionDir removeSessionDir $ do
-    LSMT.withSessionIO mempty sessionDir $ \session -> do
+    LSMT.withOpenSessionIO mempty sessionDir $ \session -> do
       LSMT.withTable session $ \table ->
         action session table
 :}
@@ -399,8 +404,8 @@ runExample action = do
 {- |
 Run an action with access to a session opened from a session directory.
 
-If the session directory is empty, a new session is created.
-Otherwise, the session directory is opened as an existing session.
+If the session directory is empty, a new session is created using the given salt.
+Otherwise, the session directory is restored as an existing session ignoring the given salt.
 
 If there are no open tables or cursors when the session terminates, then the disk I\/O complexity of this operation is \(O(1)\).
 Otherwise, 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
@@ -426,7 +431,7 @@ Throws the following exceptions:
     If the session directory is malformed.
 -}
 {-# SPECIALISE
-  withSession ::
+  withOpenSession ::
     Tracer IO LSMTreeTrace ->
     HasFS IO HandleIO ->
     HasBlockIO IO HandleIO ->
@@ -435,7 +440,7 @@ Throws the following exceptions:
     (Session IO -> IO a) ->
     IO a
   #-}
-withSession ::
+withOpenSession ::
   forall m h a.
   (IOLike m, Typeable h) =>
   Tracer m LSMTreeTrace ->
@@ -447,28 +452,132 @@ withSession ::
   FsPath ->
   (Session m -> m a) ->
   m a
-withSession tracer hasFS hasBlockIO sessionSalt sessionDir action = do
-  Internal.withSession tracer hasFS hasBlockIO sessionSalt sessionDir (action . Session)
+withOpenSession tracer hasFS hasBlockIO sessionSalt sessionDir action = do
+  Internal.withSessionOpen tracer hasFS hasBlockIO sessionSalt sessionDir (action . Session)
 
--- | Variant of 'withSession' that is specialised to 'IO' using the real filesystem.
-withSessionIO ::
+-- | Variant of 'withOpenSession' that is specialised to 'IO' using the real filesystem.
+withOpenSessionIO ::
   Tracer IO LSMTreeTrace ->
   FilePath ->
   (Session IO -> IO a) ->
   IO a
-withSessionIO tracer sessionDir action = do
+withOpenSessionIO tracer sessionDir action = do
   let mountPoint = MountPoint sessionDir
   let sessionDirFsPath = mkFsPath []
   let hasFS = ioHasFS mountPoint
   sessionSalt <- randomIO
   withIOHasBlockIO hasFS defaultIOCtxParams $ \hasBlockIO ->
-    withSession tracer hasFS hasBlockIO sessionSalt sessionDirFsPath action
+    withOpenSession tracer hasFS hasBlockIO sessionSalt sessionDirFsPath action
+
+{- |
+Run an action with access to a new session.
+
+The session directory must be empty.
+
+If there are no open tables or cursors when the session terminates, then the disk I\/O complexity of this operation is \(O(1)\).
+Otherwise, 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
+Consequently, the worst-case disk I\/O complexity of this operation depends on the merge policy of the open tables in the session.
+The following assumes all tables in the session have the same merge policy:
+
+['LazyLevelling']:
+  \(O(o \: T \log_T \frac{n}{B})\).
+
+The variable \(o\) refers to the number of open tables and cursors in the session.
+
+This function is exception-safe for both synchronous and asynchronous exceptions.
+
+It is recommended to use this function instead of 'newSession' and 'closeSession'.
+
+Throws the following exceptions:
+
+['SessionDirDoesNotExistError']:
+    If the session directory does not exist.
+['SessionDirLockedError']:
+    If the session directory is locked by another process.
+['SessionDirCorruptedError']:
+    If the session directory is malformed.
+-}
+{-# SPECIALISE
+  withNewSession ::
+    Tracer IO LSMTreeTrace ->
+    HasFS IO HandleIO ->
+    HasBlockIO IO HandleIO ->
+    Salt ->
+    FsPath ->
+    (Session IO -> IO a) ->
+    IO a
+  #-}
+withNewSession ::
+  forall m h a.
+  (IOLike m, Typeable h) =>
+  Tracer m LSMTreeTrace ->
+  HasFS m h ->
+  HasBlockIO m h ->
+  -- | The session salt.
+  Salt ->
+  -- | The session directory.
+  FsPath ->
+  (Session m -> m a) ->
+  m a
+withNewSession tracer hasFS hasBlockIO sessionSalt sessionDir action = do
+  Internal.withNewSession tracer hasFS hasBlockIO sessionSalt sessionDir (action . Session)
+
+{- |
+Run an action with access to a restored session.
+
+The session directory must be non-empty: a session must have previously been
+opened and closed in this directory.
+
+If there are no open tables or cursors when the session terminates, then the disk I\/O complexity of this operation is \(O(1)\).
+Otherwise, 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
+Consequently, the worst-case disk I\/O complexity of this operation depends on the merge policy of the open tables in the session.
+The following assumes all tables in the session have the same merge policy:
+
+['LazyLevelling']:
+  \(O(o \: T \log_T \frac{n}{B})\).
+
+The variable \(o\) refers to the number of open tables and cursors in the session.
+
+This function is exception-safe for both synchronous and asynchronous exceptions.
+
+It is recommended to use this function instead of 'restoreSession' and 'closeSession'.
+
+Throws the following exceptions:
+
+['SessionDirDoesNotExistError']:
+    If the session directory does not exist.
+['SessionDirLockedError']:
+    If the session directory is locked by another process.
+['SessionDirCorruptedError']:
+    If the session directory is malformed.
+-}
+{-# SPECIALISE
+  withRestoreSession ::
+    Tracer IO LSMTreeTrace ->
+    HasFS IO HandleIO ->
+    HasBlockIO IO HandleIO ->
+    FsPath ->
+    (Session IO -> IO a) ->
+    IO a
+  #-}
+withRestoreSession ::
+  forall m h a.
+  (IOLike m, Typeable h) =>
+  Tracer m LSMTreeTrace ->
+  HasFS m h ->
+  HasBlockIO m h ->
+  -- | The session directory.
+  FsPath ->
+  (Session m -> m a) ->
+  m a
+withRestoreSession tracer hasFS hasBlockIO sessionDir action = do
+  Internal.withRestoreSession tracer hasFS hasBlockIO sessionDir (action . Session)
 
 {- |
 Open a session from a session directory.
 
-If the session directory is empty, a new session is created.
-Otherwise, the session directory is opened as an existing session.
+If the session directory is empty, a new session is created using the given salt.
+Otherwise, the session directory is restored as an existing session ignoring the given salt.
 
 The worst-case disk I\/O complexity of this operation is \(O(1)\).
 
@@ -522,6 +631,86 @@ openSessionIO tracer sessionDir = do
   bracketOnError acquireHasBlockIO releaseHasBlockIO $ \hasBlockIO ->
     openSession tracer hasFS hasBlockIO sessionSalt sessionDirFsPath
 
+{- |
+Create a new session.
+
+The session directory must be empty.
+
+The worst-case disk I\/O complexity of this operation is \(O(1)\).
+
+__Warning:__ Sessions hold open resources and must be closed using 'closeSession'.
+
+Throws the following exceptions:
+
+['SessionDirDoesNotExistError']:
+    If the session directory does not exist.
+['SessionDirLockedError']:
+    If the session directory is locked by another process.
+['SessionDirCorruptedError']:
+    If the session directory is malformed.
+-}
+{-# SPECIALISE
+  newSession ::
+    Tracer IO LSMTreeTrace ->
+    HasFS IO HandleIO ->
+    HasBlockIO IO HandleIO ->
+    Salt ->
+    FsPath ->
+    IO (Session IO)
+  #-}
+newSession ::
+  forall m h.
+  (IOLike m, Typeable h) =>
+  Tracer m LSMTreeTrace ->
+  HasFS m h ->
+  HasBlockIO m h ->
+  -- | The session salt.
+  Salt ->
+  -- | The session directory.
+  FsPath ->
+  m (Session m)
+newSession tracer hasFS hasBlockIO sessionSalt sessionDir =
+  Session <$> Internal.newSession tracer hasFS hasBlockIO sessionSalt sessionDir
+
+{- |
+Restore a session from a session directory.
+
+The session directory must be non-empty: a session must have previously been
+opened (and closed) in this directory.
+
+The worst-case disk I\/O complexity of this operation is \(O(1)\).
+
+__Warning:__ Sessions hold open resources and must be closed using 'closeSession'.
+
+Throws the following exceptions:
+
+['SessionDirDoesNotExistError']:
+    If the session directory does not exist.
+['SessionDirLockedError']:
+    If the session directory is locked by another process.
+['SessionDirCorruptedError']:
+    If the session directory is malformed.
+-}
+{-# SPECIALISE
+  restoreSession ::
+    Tracer IO LSMTreeTrace ->
+    HasFS IO HandleIO ->
+    HasBlockIO IO HandleIO ->
+    FsPath ->
+    IO (Session IO)
+  #-}
+restoreSession ::
+  forall m h.
+  (IOLike m, Typeable h) =>
+  Tracer m LSMTreeTrace ->
+  HasFS m h ->
+  HasBlockIO m h ->
+  -- | The session directory.
+  FsPath ->
+  m (Session m)
+restoreSession tracer hasFS hasBlockIO sessionDir =
+  Session <$> Internal.restoreSession tracer hasFS hasBlockIO sessionDir
+
 {- |
 Close a session.