rename snapshot operations

Author: mheinzel

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

@@ -418,7 +418,7 @@ doSetup' gopts opts = do
                 | i <- NE.toList batch
                 ]
 
-        LSM.snapshot name tbl
+        LSM.createSnapshot name tbl
 
 -------------------------------------------------------------------------------
 -- dry-run
@@ -577,7 +577,7 @@ doRun gopts opts = do
         -- necessary for testing to load the whole snapshot).
         tbl <- if check opts
                 then LSM.new  @IO @K @V @B session (mkTableConfigRun gopts LSM.defaultTableConfig)
-                else LSM.open @IO @K @V @B session (mkTableConfigOverride gopts) name
+                else LSM.openSnapshot @IO @K @V @B session (mkTableConfigOverride gopts) name
 
         -- In checking mode, compare each output against a pure reference.
         checkvar <- newIORef $ pureReference

src/Database/LSMTree/Internal.hs

@@ -58,8 +58,8 @@ module Database.LSMTree.Internal (
   , readCursorWhile
     -- * Snapshots
   , SnapshotLabel
-  , snapshot
-  , open
+  , createSnapshot
+  , openSnapshot
   , deleteSnapshot
   , listSnapshots
     -- * Mutiple writable tables
@@ -297,8 +297,8 @@ data SessionEnv m h = SessionEnv {
     --
     -- Tables are assigned unique identifiers using 'sessionUniqCounter' to
     -- ensure that modifications to the set of known tables are independent.
-    -- Each identifier is added only once in 'new', 'open' or 'duplicate', and
-    -- is deleted only once in 'close' or 'closeSession'.
+    -- Each identifier is added only once in 'new', 'openSnapshot' or
+    -- 'duplicate', and is deleted only once in 'close' or 'closeSession'.
     --
     -- * A new table may only insert its own identifier when it has acquired the
     --   'sessionState' read-lock. This is to prevent races with 'closeSession'.
@@ -1056,23 +1056,23 @@ readCursorWhile resolve keyIsWanted n Cursor {..} fromEntry = do
   Snapshots
 -------------------------------------------------------------------------------}
 
-{-# SPECIALISE snapshot ::
+{-# SPECIALISE createSnapshot ::
      ResolveSerialisedValue
   -> SnapshotName
   -> SnapshotLabel
   -> SnapshotTableType
   -> Table IO h
   -> IO Int #-}
--- |  See 'Database.LSMTree.Normal.snapshot''.
-snapshot ::
+-- |  See 'Database.LSMTree.Normal.createSnapshot''.
+createSnapshot ::
      (MonadFix m, MonadMask m, MonadMVar m, MonadST m, MonadSTM m)
   => ResolveSerialisedValue
   -> SnapshotName
   -> SnapshotLabel
   -> SnapshotTableType
   -> Table m h
   -> m Int
-snapshot resolve snap label tableType t = do
+createSnapshot resolve snap label tableType t = do
     traceWith (tableTracer t) $ TraceSnapshot snap
     let conf = tableConfig t
     withOpenTable t $ \thEnv -> do
@@ -1120,16 +1120,16 @@ snapshot resolve snap label tableType t = do
 
       pure $! numSnapRuns snappedLevels
 
-{-# SPECIALISE open ::
+{-# SPECIALISE openSnapshot ::
      Session IO h
   -> SnapshotLabel
   -> SnapshotTableType
   -> TableConfigOverride
   -> SnapshotName
   -> ResolveSerialisedValue
   -> IO (Table IO h) #-}
--- |  See 'Database.LSMTree.Normal.open'.
-open ::
+-- |  See 'Database.LSMTree.Normal.openSnapshot'.
+openSnapshot ::
      (MonadFix m, MonadMask m, MonadMVar m, MonadST m, MonadSTM m)
   => Session m h
   -> SnapshotLabel -- ^ Expected label
@@ -1138,7 +1138,7 @@ open ::
   -> SnapshotName
   -> ResolveSerialisedValue
   -> m (Table m h)
-open sesh label tableType override snap resolve = do
+openSnapshot sesh label tableType override snap resolve = do
     traceWith (sessionTracer sesh) $ TraceOpenSnapshot snap override
     withOpenSession sesh $ \seshEnv -> do
       withTempRegistry $ \reg -> do

src/Database/LSMTree/Monoidal.hs

@@ -89,8 +89,8 @@ module Database.LSMTree.Monoidal (
   , SnapshotName
   , Common.mkSnapshotName
   , Common.Labellable (..)
-  , snapshot
-  , open
+  , createSnapshot
+  , openSnapshot
   , Common.TableConfigOverride
   , Common.configNoOverride
   , Common.configOverrideDiskCachePolicy
@@ -521,7 +521,7 @@ mupserts t = updates t . fmap (second Mupsert)
   Snapshots
 -------------------------------------------------------------------------------}
 
-{-# SPECIALISE snapshot ::
+{-# SPECIALISE createSnapshot ::
      (SerialiseKey k, SerialiseValue v, ResolveValue v, Common.Labellable (k, v))
   => SnapshotName
   -> Table IO k v
@@ -530,9 +530,9 @@ mupserts t = updates t . fmap (second Mupsert)
 -- giving the snapshot a name. This is the __only__ mechanism to make a table
 -- durable -- ordinary insert\/delete operations are otherwise not preserved.
 --
--- Snapshots have names and the table may be opened later using 'open' via that
--- name. Names are strings and the management of the names is up to the user of
--- the library.
+-- Snapshots have names and the table may be opened later using 'openSnapshot'
+-- via that name. Names are strings and the management of the names is up to the
+-- user of the library.
 --
 -- The names correspond to disk files, which imposes some constraints on length
 -- and what characters can be used.
@@ -548,7 +548,7 @@ mupserts t = updates t . fmap (second Mupsert)
 -- * It is safe to concurrently make snapshots from any table, provided that
 --   the snapshot names are distinct (otherwise this would be a race).
 --
-snapshot :: forall m k v.
+createSnapshot :: forall m k v.
      ( IOLike m
      , SerialiseKey k
      , SerialiseValue v
@@ -558,12 +558,12 @@ snapshot :: forall m k v.
   => SnapshotName
   -> Table m k v
   -> m ()
-snapshot snap (Internal.MonoidalTable t) =
-    void $ Internal.snapshot (resolve @v Proxy) snap label Internal.SnapMonoidalTable t
+createSnapshot snap (Internal.MonoidalTable t) =
+    void $ Internal.createSnapshot (resolve @v Proxy) snap label Internal.SnapMonoidalTable t
   where
     label = Internal.SnapshotLabel $ Common.makeSnapshotLabel (Proxy @(k, v))
 
-{-# SPECIALISE open ::
+{-# SPECIALISE openSnapshot ::
      (SerialiseKey k, SerialiseValue v, ResolveValue v, Common.Labellable (k, v))
   => Session IO
   -> Common.TableConfigOverride
@@ -584,14 +584,10 @@ snapshot snap (Internal.MonoidalTable t) =
 -- @
 -- example session = do
 --   t <- 'new' \@IO \@Int \@Int \@Int session _
---   'snapshot' "intTable" t
---   'open' \@IO \@Bool \@Bool \@Bool session "intTable"
+--   'createSnapshot' "intTable" t
+--   'openSnapshot' \@IO \@Bool \@Bool \@Bool session "intTable"
 -- @
---
--- TOREMOVE: before snapshots are implemented, the snapshot name should be ignored.
--- Instead, this function should open a table from files that exist in
--- the session's directory.
-open :: forall m k v.
+openSnapshot :: forall m k v.
      ( IOLike m
      , SerialiseKey k
      , SerialiseValue v
@@ -602,9 +598,9 @@ open :: forall m k v.
   -> Common.TableConfigOverride -- ^ Optional config override
   -> SnapshotName
   -> m (Table m k v)
-open (Internal.Session' sesh) override snap =
+openSnapshot (Internal.Session' sesh) override snap =
     Internal.MonoidalTable <$>
-      Internal.open
+      Internal.openSnapshot
         sesh
         label
         Internal.SnapMonoidalTable

src/Database/LSMTree/Normal.hs

@@ -90,8 +90,8 @@ module Database.LSMTree.Normal (
   , SnapshotName
   , Common.mkSnapshotName
   , Common.Labellable (..)
-  , snapshot
-  , open
+  , createSnapshot
+  , openSnapshot
   , Common.TableConfigOverride
   , Common.configNoOverride
   , Common.configOverrideDiskCachePolicy
@@ -150,7 +150,7 @@ import qualified Database.LSMTree.Internal.Vector as V
 --
 -- * 'openSession'
 -- * 'new'
--- * 'open'
+-- * 'openSnapshot'
 -- * 'duplicate'
 -- * 'newCursor'
 --
@@ -171,7 +171,7 @@ import qualified Database.LSMTree.Internal.Vector as V
 --
 -- * 'openSession', paired with 'closeSession'
 -- * 'new', paired with 'close'
--- * 'open', paired with 'close'
+-- * 'openSnapshot', paired with 'close'
 -- * 'duplicate', paired with 'close'
 -- * 'newCursor', paired with 'closeCursor'
 --
@@ -201,7 +201,7 @@ import qualified Database.LSMTree.Internal.Vector as V
 -- * 'lookups'
 -- * 'rangeLookup'
 -- * 'retrieveBlobs'
--- * 'snapshot'
+-- * 'createSnapshot'
 -- * 'duplicate'
 --
 -- The write operations are:
@@ -639,7 +639,7 @@ retrieveBlobs (Internal.Session' (sesh :: Internal.Session m h)) refs =
   Snapshots
 -------------------------------------------------------------------------------}
 
-{-# SPECIALISE snapshot ::
+{-# SPECIALISE createSnapshot ::
      ( SerialiseKey k
      , SerialiseValue v
      , SerialiseValue blob
@@ -652,9 +652,9 @@ retrieveBlobs (Internal.Session' (sesh :: Internal.Session m h)) refs =
 -- giving the snapshot a name. This is the __only__ mechanism to make a table
 -- durable -- ordinary insert\/delete operations are otherwise not preserved.
 --
--- Snapshots have names and the table may be opened later using 'open' via that
--- name. Names are strings and the management of the names is up to the user of
--- the library.
+-- Snapshots have names and the table may be opened later using 'openSnapshot'
+-- via that name. Names are strings and the management of the names is up to
+-- the user of the library.
 --
 -- The names correspond to disk files, which imposes some constraints on length
 -- and what characters can be used.
@@ -677,7 +677,7 @@ retrieveBlobs (Internal.Session' (sesh :: Internal.Session m h)) refs =
 -- as part of the snapshot because run files aren't (yet) deleted when runs are
 -- closed. The write buffer is also persisted to disk as part of the snapshot,
 -- but the original table remains unchanged.
-snapshot :: forall m k v blob.
+createSnapshot :: forall m k v blob.
      ( IOLike m
      , SerialiseKey k
      , SerialiseValue v
@@ -687,12 +687,12 @@ snapshot :: forall m k v blob.
   => SnapshotName
   -> Table m k v blob
   -> m ()
-snapshot snap (Internal.NormalTable t) =
-    void $ Internal.snapshot const snap label Internal.SnapNormalTable t
+createSnapshot snap (Internal.NormalTable t) =
+    void $ Internal.createSnapshot const snap label Internal.SnapNormalTable t
   where
     label = Internal.SnapshotLabel $ Common.makeSnapshotLabel (Proxy @(k, v, blob))
 
-{-# SPECIALISE open ::
+{-# SPECIALISE openSnapshot ::
      ( SerialiseKey k
      , SerialiseValue v
      , SerialiseValue blob
@@ -717,13 +717,13 @@ snapshot snap (Internal.NormalTable t) =
 -- @
 -- example session = do
 --   t <- 'new' \@IO \@Int \@Int \@Int session _
---   'snapshot' "intTable" t
---   'open' \@IO \@Bool \@Bool \@Bool session "intTable"
+--   'createSnapshot' "intTable" t
+--   'openSnapshot' \@IO \@Bool \@Bool \@Bool session "intTable"
 -- @
 --
 -- TODO: this function currently has a temporary implementation until we have
--- proper snapshots. See 'snapshot'.
-open :: forall m k v blob.
+-- proper snapshots. See 'createSnapshot'.
+openSnapshot :: forall m k v blob.
      ( IOLike m
      , SerialiseKey k
      , SerialiseValue v
@@ -734,8 +734,15 @@ open :: forall m k v blob.
   -> Common.TableConfigOverride -- ^ Optional config override
   -> SnapshotName
   -> m (Table m k v blob)
-open (Internal.Session' sesh) override snap =
-    Internal.NormalTable <$!> Internal.open sesh label Internal.SnapNormalTable override snap const
+openSnapshot (Internal.Session' sesh) override snap =
+    Internal.NormalTable <$!>
+      Internal.openSnapshot
+        sesh
+        label
+        Internal.SnapNormalTable
+        override
+        snap
+        const
   where
     label = Internal.SnapshotLabel $ Common.makeSnapshotLabel (Proxy @(k, v, blob))
 

test/Database/LSMTree/Class/Monoidal.hs

@@ -10,7 +10,7 @@ module Database.LSMTree.Class.Monoidal (
   , withSession
   , IsTable (..)
   , withTableNew
-  , withTableOpen
+  , withTableFromSnapshot
   , withTableDuplicate
   , withTableUnion
   , withCursor
@@ -152,7 +152,7 @@ class (IsSession (Session h)) => IsTable h where
         -> V.Vector (k, v)
         -> m ()
 
-    snapshot ::
+    createSnapshot ::
            ( IOLike m
            , Labellable (k, v)
            , ResolveValue v
@@ -164,7 +164,7 @@ class (IsSession (Session h)) => IsTable h where
         -> h m k v
         -> m ()
 
-    open ::
+    openSnapshot ::
            ( IOLike m
            , Labellable (k, v)
            , ResolveValue v
@@ -204,7 +204,7 @@ withTableNew :: forall h m k v a.
   -> m a
 withTableNew sesh conf = bracket (new sesh conf) close
 
-withTableOpen :: forall h m k v a.
+withTableFromSnapshot :: forall h m k v a.
      ( IOLike m
      , IsTable h
      , ResolveValue v
@@ -217,7 +217,7 @@ withTableOpen :: forall h m k v a.
   -> SnapshotName
   -> (h m k v -> m a)
   -> m a
-withTableOpen sesh snap = bracket (open sesh snap) close
+withTableFromSnapshot sesh snap = bracket (openSnapshot sesh snap) close
 
 withTableDuplicate :: forall h m k v a.
      ( IOLike m
@@ -277,8 +277,8 @@ instance IsTable R.Table where
     closeCursor _ = R.closeCursor
     readCursor _ = R.readCursor
 
-    snapshot = R.snapshot
-    open sesh snap = R.open sesh R.configNoOverride snap
+    createSnapshot = R.createSnapshot
+    openSnapshot sesh snap = R.openSnapshot sesh R.configNoOverride snap
 
     duplicate = R.duplicate
     union = R.union