{-# LANGUAGE LambdaCase #-}
-- |
-- Module : Database.RocksDB.Base
-- Copyright : (c) 2012-2013 The leveldb-haskell Authors
-- (c) 2014-2020 The rocksdb-haskell Authors
-- License : BSD3
-- Maintainer : jprupp@protonmail.ch
-- Stability : experimental
-- Portability : non-portable
--
-- RocksDB Haskell binding.
--
-- The API closely follows the C-API of RocksDB. All resources (databases,
-- snapshots, iterators) are managed with bracket-style functions such as
-- 'withDB', 'withSnapshot' and 'withIter', which release them when the
-- supplied action returns or throws. Manual variants such as 'createSnapshot'
-- and 'createIterator' exist for cases where the lifetime of a resource cannot
-- be expressed as a scope.
--
-- A t'DB' handle is safe to use from many threads at once.
module Database.RocksDB.Base
( -- * Exported Types
DB (..),
BatchOp (..),
Range,
ColumnFamily,
Snapshot,
ReadOpts,
-- * Options
Config (..),
MergeOperator (..),
FullMerge,
PartialMerge,
-- * Basic Database Manipulations
withDB,
withDBCF,
put,
putCF,
delete,
deleteCF,
merge,
mergeCF,
write,
get,
getCF,
multiGet,
multiGetCF,
withSnapshot,
createSnapshot,
releaseSnapshot,
-- * Packed batches
-- $packed
writePacked,
packOps,
PackedOp (..),
packedHeaderSize,
pokePackedHeader,
-- * Administrative Functions
Property (..),
getProperty,
getPropertyCF,
destroy,
repair,
approximateSize,
compactRange,
flush,
-- * Iteration
module Database.RocksDB.Iterator,
)
where
import Control.Exception
import Control.Monad (foldM_, forM, forM_, when)
import Data.ByteString (ByteString)
import qualified Data.ByteString as BS
import Data.ByteString.Internal (ByteString (..))
import qualified Data.ByteString.Internal as BI
import qualified Data.ByteString.Unsafe as BU
import Data.Int
import Data.Maybe (fromMaybe)
import Data.Word (Word32, Word8)
import Database.RocksDB.C
import Database.RocksDB.Internal
import Database.RocksDB.Iterator
import Foreign.C.String
import Foreign.ForeignPtr
import Foreign.Marshal.Alloc
import Foreign.Marshal.Array
import Foreign.Marshal.Utils (copyBytes, withMany)
import Foreign.Ptr
import Foreign.Storable
import System.Directory
-- | Properties exposed by RocksDB. Read them with 'getProperty' or
-- 'getPropertyCF'. Every value is returned by RocksDB as text.
data Property
= -- | @rocksdb.num-files-at-level\<N\>@: number of SST files at level @N@
NumFilesAtLevel Int
| -- | @rocksdb.stats@: multi-line human-readable statistics
Stats
| -- | @rocksdb.sstables@: description of the SST files that make up the
-- database
SSTables
| -- | @rocksdb.estimate-table-readers-mem@: memory for index and filter
-- blocks of open table files, outside the block cache
EstimateTableReadersMem
| -- | @rocksdb.cur-size-all-mem-tables@: memory of all memtables
CurSizeAllMemTables
| -- | @rocksdb.block-cache-usage@: memory used by the block cache
BlockCacheUsage
| -- | any other property, by its full name
PropertyName String
deriving (Eq, Show)
-- | A single operation in an atomic batch written with 'write'.
--
-- Batches are how a program keeps several keys consistent with each other: an
-- index and the data it points to, for example, must change together or not at
-- all. RocksDB applies a batch atomically and in one write to its log, so a batch
-- is also much faster than the same writes made one by one.
data BatchOp
= -- | set a key to a value in the default column family
Put !ByteString !ByteString
| -- | delete a key from the default column family
Del !ByteString
| -- | set a key to a value in a column family
PutCF !ColumnFamily !ByteString !ByteString
| -- | delete a key from a column family
DelCF !ColumnFamily !ByteString
| -- | add a merge record to a key of the default column family: the
-- second byte string is for the t'MergeOperator' of the column family
-- to combine with the value that the key has. Nothing is read when
-- the batch is written. RocksDB refuses the batch if the column family
-- has no merge operator, and 'write' throws. What is left of such a
-- batch depends on the version: RocksDB 11 keeps none of it, RocksDB
-- 8.9 keeps the operations that came before the merge. Give every
-- column family that gets merge records its operator.
Merge !ByteString !ByteString
| -- | add a merge record to a key of a column family
MergeCF !ColumnFamily !ByteString !ByteString
deriving (Eq, Show)
-- | Open a database at the given path and pass its handle to a function.
--
-- The handle is closed automatically when the function returns or throws, and
-- must not be used afterwards. If 'createIfMissing' is set, the directory is
-- created first if needed. Throws an 'IOError' if the database cannot be
-- opened, for example if it does not exist and 'createIfMissing' is not set,
-- or if it is locked by another process.
--
-- Only the default column family is opened. A database that has other column
-- families must be opened with 'withDBCF'.
--
-- Opening is expensive and a database can only be opened by one process at a
-- time, so open it once at program start and share the t'DB' between threads for
-- the life of the program.
withDB :: FilePath -> Config -> (DB -> IO a) -> IO a
withDB path config f =
withBlockCache config $ \cache ->
withOptionsCache cache config $ \opts_ptr ->
withReadOpts Nothing $ \read_opts ->
withWriteOpts $ \write_opts ->
bracket (create_db opts_ptr read_opts write_opts) destroy_db f
where
destroy_db db = c_rocksdb_close $ rocksDB db
create_db opts_ptr read_opts write_opts = do
when (createIfMissing config) $
createDirectoryIfMissing True path
withCString path $ \path_ptr -> do
db_ptr <-
throwIfErr "open" $
c_rocksdb_open opts_ptr path_ptr
return
DB
{ rocksDB = db_ptr,
columnFamilies = [],
readOpts = read_opts,
snapshot = Nothing,
writeOpts = write_opts
}
-- | Open a database with column families and pass its handle to a function.
--
-- The second argument configures the database and its default column family.
-- The third argument lists the other column families by name, each with its own
-- t'Config'. Their handles are stored in 'columnFamilies', in the same order.
--
-- If the database directory is empty, a new database is created along with all
-- the listed column families. Otherwise the existing database is opened with
-- those column families; if some of them do not exist yet, the open fails unless
-- 'createMissingColumnFamilies' is set in the database t'Config'. RocksDB also
-- requires every column family that exists in the database to be listed.
--
-- The handle and all column family handles are released when the function
-- returns or throws.
--
-- Column families are separate key spaces in one database. They share the
-- write-ahead log, so a batch can change several of them atomically, but each
-- has its own files, memtables and tuning. Use them to keep data of different
-- shapes apart, such as an index with short keys and a table of large values.
withDBCF ::
FilePath ->
Config ->
[(String, Config)] ->
(DB -> IO a) ->
IO a
withDBCF path config cf_cfgs f =
withBlockCache config $ \cache ->
withOptionsCache cache config $ \opts_ptr ->
withOptionsCFCache cache (map snd cf_cfgs) $ \cf_opts ->
withReadOpts Nothing $ \read_opts ->
withWriteOpts $ \write_opts ->
withStrings (map fst cf_cfgs) $ \cf_names ->
allocaArray (length cf_cfgs + 1) $ \cf_names_array ->
allocaArray (length cf_cfgs + 1) $ \cf_opts_array ->
allocaArray (length cf_cfgs + 1) $ \cf_ptrs_array ->
bracket
( create_db
opts_ptr
cf_names
cf_names_array
cf_opts
cf_opts_array
read_opts
cf_ptrs_array
write_opts
)
destroy_db
f
where
create_new cf_names cf_opts opts_ptr read_opts write_opts = do
createDirectoryIfMissing True path
withCString path $ \path_ptr -> do
db_ptr <-
throwIfErr "open" $
c_rocksdb_open opts_ptr path_ptr
cfs <- forM (zip cf_names cf_opts) $ \(n, o) ->
throwIfErr "create_column_family" $
c_rocksdb_create_column_family
db_ptr
o
n
return
DB
{ rocksDB = db_ptr,
columnFamilies = cfs,
readOpts = read_opts,
snapshot = Nothing,
writeOpts = write_opts
}
destroy_db db = do
mapM_ c_rocksdb_column_family_handle_destroy (columnFamilies db)
c_rocksdb_close $ rocksDB db
create_db
opts_ptr
cf_names
cf_names_array
cf_opts
cf_opts_array
read_opts
cf_ptrs_array
write_opts = do
when (createIfMissing config) $
createDirectoryIfMissing True path
listDirectory path >>= \case
[] -> create_new cf_names cf_opts opts_ptr read_opts write_opts
_ -> withCString path $ \path_ptr ->
withCString "default" $ \cf_deflt_name -> do
pokeArray cf_names_array (cf_deflt_name : cf_names)
pokeArray cf_opts_array (opts_ptr : cf_opts)
db_ptr <-
throwIfErr "open" $
c_rocksdb_open_column_families
opts_ptr
path_ptr
(intToCInt (length cf_cfgs + 1))
cf_names_array
cf_opts_array
cf_ptrs_array
(deflt, cfs) <-
peekArray (length cf_cfgs + 1) cf_ptrs_array >>= \case
d : cs -> return (d, cs)
[] -> error "rocksdb_open_column_families returned no handles"
-- Every handle must be destroyed before the database is
-- closed. The default column family is not kept, so
-- release its handle now; the database keeps its own.
c_rocksdb_column_family_handle_destroy deflt
return
DB
{ rocksDB = db_ptr,
columnFamilies = cfs,
readOpts = read_opts,
snapshot = Nothing,
writeOpts = write_opts
}
-- | Run an action with a snapshot of the database.
-- The t'DB' object is not valid after the action ends.
--
-- The t'DB' passed to the action reads from a consistent point-in-time view of
-- the database: 'get', 'multiGet' and iterators created from it do not see
-- writes made after the snapshot was taken. Writes through it still go to the
-- live database.
--
-- Without a snapshot, two reads made one after the other can see different
-- states of the database if another thread writes in between. Anything that
-- reads several related keys and expects them to agree, such as an index and the
-- records it points to, should read through a snapshot.
withSnapshot :: DB -> (DB -> IO a) -> IO a
withSnapshot db f =
bracket (createSnapshot db) releaseSnapshot (f . fst)
-- | Manually create an unmanaged snapshot.
-- The returned t'DB' has 'readOpts' configured for the snapshot.
-- Use 'releaseSnapshot' to release both the snapshot and its read options.
createSnapshot :: DB -> IO (DB, Snapshot)
createSnapshot db@DB {rocksDB = db_ptr} = do
snap_ptr <- c_rocksdb_create_snapshot db_ptr
read_opts <- createReadOpts (Just snap_ptr)
return (db {readOpts = read_opts, snapshot = Just snap_ptr}, snap_ptr)
-- | Function to release an unmanaged snapshot.
-- Also releases the read options associated with the snapshot DB.
releaseSnapshot :: (DB, Snapshot) -> IO ()
releaseSnapshot (DB {rocksDB = db_ptr, readOpts = read_opts}, snap_ptr) = do
destroyReadOpts read_opts
c_rocksdb_release_snapshot db_ptr snap_ptr
-- | Get a property of the default column family, or of the database as a
-- whole. Returns 'Nothing' if RocksDB does not know the property.
getProperty :: DB -> Property -> IO (Maybe ByteString)
getProperty DB {rocksDB = db_ptr} p =
withCString (propertyName p) $ \name ->
c_rocksdb_property_value db_ptr name >>= propertyResult
-- | Get a property of a column family. Many properties, such as the memory
-- of memtables and table readers, are kept per column family.
getPropertyCF :: DB -> ColumnFamily -> Property -> IO (Maybe ByteString)
getPropertyCF DB {rocksDB = db_ptr} cf p =
withCString (propertyName p) $ \name ->
c_rocksdb_property_value_cf db_ptr cf name >>= propertyResult
-- | Turn a property value returned by RocksDB into a 'ByteString', freeing the
-- C string.
propertyResult :: CString -> IO (Maybe ByteString)
propertyResult val_ptr
| val_ptr == nullPtr = return Nothing
| otherwise = do
res <- BS.packCString val_ptr
freeCString val_ptr
return (Just res)
-- | The name RocksDB uses for a property.
propertyName :: Property -> String
propertyName = \case
NumFilesAtLevel i -> "rocksdb.num-files-at-level" ++ show i
Stats -> "rocksdb.stats"
SSTables -> "rocksdb.sstables"
EstimateTableReadersMem -> "rocksdb.estimate-table-readers-mem"
CurSizeAllMemTables -> "rocksdb.cur-size-all-mem-tables"
BlockCacheUsage -> "rocksdb.block-cache-usage"
PropertyName n -> n
-- | Destroy the given RocksDB database, deleting all of its files. The
-- database must not be open. Throws an 'IOError' on failure.
destroy :: FilePath -> Options -> IO ()
destroy path opts_ptr =
withCString path $ \path_ptr ->
throwIfErr "destroy" $ c_rocksdb_destroy_db opts_ptr path_ptr
-- | Try to recover as much data as possible from a corrupted database. Some
-- data may be lost. The database must not be open. Throws an 'IOError' on
-- failure.
repair :: FilePath -> Options -> IO ()
repair path opts_ptr =
withCString path $ \path_ptr ->
throwIfErr "repair" $ c_rocksdb_repair_db opts_ptr path_ptr
-- | A key range given as @(start, limit)@. The start key is included and the
-- limit key is excluded.
--
-- TODO: support [Range], like C API does
type Range = (ByteString, ByteString)
-- | Approximate number of bytes of file system space used by the keys in a
-- 'Range' of the default column family. Data still in memtables may not be
-- counted. Throws an 'IOError' on failure.
approximateSize :: DB -> Range -> IO Int64
approximateSize DB {rocksDB = db_ptr} (from, to) =
BU.unsafeUseAsCStringLen from $ \(from_ptr, flen) ->
BU.unsafeUseAsCStringLen to $ \(to_ptr, tlen) ->
withArray [from_ptr] $ \from_ptrs ->
withArray [intToCSize flen] $ \flen_ptrs ->
withArray [to_ptr] $ \to_ptrs ->
withArray [intToCSize tlen] $ \tlen_ptrs ->
alloca $ \size_ptr -> do
throwIfErr "approximate_sizes" $
c_rocksdb_approximate_sizes
db_ptr
1
from_ptrs
flen_ptrs
to_ptrs
tlen_ptrs
size_ptr
fromIntegral <$> peek size_ptr
-- | Write again every table file that has keys from the first to the second
-- of the two given, in the default column family or in the one given, and
-- return when it is done. 'Nothing' leaves that end of the range open, so
-- two of them are the whole column family.
--
-- RocksDB compacts by itself, and a program does not need this to keep a
-- database in order. It is for the one thing that only a rewrite does:
-- giving the files that a database already has the layout of its present
-- t'Config', such as a Bloom filter or 'partitionIndexAndFilters', which
-- otherwise reach a file only when RocksDB happens to compact it, and the
-- files of the last level, which hold most of the data, rarely are. Every
-- file in the range is written, those of the last level included.
--
-- It reads and writes all the data in the range, with the background
-- threads of the database ('maxBackgroundJobs'): hours on a large one, and
-- room on the disk for the files being written until the old ones are
-- deleted. The database can be read and written meanwhile. RocksDB reports
-- no error from it; what it could not do stays as it was.
compactRange :: DB -> Maybe ColumnFamily -> Maybe ByteString -> Maybe ByteString -> IO ()
compactRange DB {rocksDB = db_ptr} mcf from to =
bracket c_rocksdb_compactoptions_create c_rocksdb_compactoptions_destroy $ \opts -> do
c_rocksdb_compactoptions_set_bottommost_level_compaction opts forceOptimized
bound from $ \(from_ptr, flen) ->
bound to $ \(to_ptr, tlen) ->
case mcf of
Just cf -> c_rocksdb_compact_range_cf_opt db_ptr cf opts from_ptr flen to_ptr tlen
Nothing -> c_rocksdb_compact_range_opt db_ptr opts from_ptr flen to_ptr tlen
where
-- @BottommostLevelCompaction::kForceOptimized@: the files of the last
-- level too, but not those that this compaction has just written
forceOptimized = 3
bound Nothing f = f (nullPtr, 0)
bound (Just k) f = BU.unsafeUseAsCStringLen k $ \(p, n) -> f (p, intToCSize n)
-- | Write a key/value pair to the default column family, replacing any
-- previous value. Throws an 'IOError' on failure.
put :: DB -> ByteString -> ByteString -> IO ()
put db = putCommon db Nothing
-- | Like 'put', but write to the given column family.
putCF :: DB -> ColumnFamily -> ByteString -> ByteString -> IO ()
putCF db cf = putCommon db (Just cf)
-- | Write a key/value pair to the default column family, or to a column family
-- if one is given.
putCommon :: DB -> Maybe ColumnFamily -> ByteString -> ByteString -> IO ()
putCommon DB {rocksDB = db_ptr, writeOpts = write_opts} mcf key value =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
BU.unsafeUseAsCStringLen value $ \(val_ptr, vlen) ->
throwIfErr "put" $ case mcf of
Just cf ->
c_rocksdb_put_cf
db_ptr
write_opts
cf
key_ptr
(intToCSize klen)
val_ptr
(intToCSize vlen)
Nothing ->
c_rocksdb_put
db_ptr
write_opts
key_ptr
(intToCSize klen)
val_ptr
(intToCSize vlen)
-- | Read a value by key from the default column family. Returns 'Nothing' if
-- the key is not found. Throws an 'IOError' on failure.
get :: DB -> ByteString -> IO (Maybe ByteString)
get db = getCommon db Nothing
-- | Like 'get', but read from the given column family.
getCF :: DB -> ColumnFamily -> ByteString -> IO (Maybe ByteString)
getCF db cf = getCommon db (Just cf)
-- | Read a value from the default column family, or from a column family if one
-- is given.
getCommon :: DB -> Maybe ColumnFamily -> ByteString -> IO (Maybe ByteString)
getCommon DB {rocksDB = db_ptr, readOpts = read_opts} mcf key =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
alloca $ \vlen_ptr -> do
val_ptr <- throwIfErr "get" $
case mcf of
Just cf ->
c_rocksdb_get_cf
db_ptr
read_opts
cf
key_ptr
(intToCSize klen)
vlen_ptr
Nothing ->
c_rocksdb_get
db_ptr
read_opts
key_ptr
(intToCSize klen)
vlen_ptr
if val_ptr == nullPtr
then return Nothing
else do
vlen <- peek vlen_ptr
res <- BU.unsafePackMallocCStringLen (val_ptr, cSizeToInt vlen)
return $ Just res
-- | Read the values of many keys in one call. RocksDB looks the keys up
-- together, sharing the work of finding the files and blocks that hold
-- them, which is faster than reading them one by one. The values are in the
-- order of the keys, with 'Nothing' for keys that are not found. Duplicate keys
-- are allowed. Throws an 'IOError' if any of the lookups fails.
--
-- For a query that needs hundreds of keys at once, such as the balances of many
-- addresses, this cuts the time spent finding blocks and crossing into C to a
-- fraction of separate 'get' calls.
multiGet :: DB -> [ByteString] -> IO [Maybe ByteString]
multiGet db = multiGetCommon db Nothing
-- | 'multiGet' on a column family.
multiGetCF :: DB -> ColumnFamily -> [ByteString] -> IO [Maybe ByteString]
multiGetCF db cf = multiGetCommon db (Just cf)
-- | Read many values from the default column family, or from a column family if
-- one is given.
multiGetCommon :: DB -> Maybe ColumnFamily -> [ByteString] -> IO [Maybe ByteString]
multiGetCommon _ _ [] = return []
multiGetCommon DB {rocksDB = db_ptr, readOpts = read_opts} mcf keys =
withMany BU.unsafeUseAsCStringLen keys $ \kls ->
withArrayLen (map fst kls) $ \n key_ptrs ->
withArray (map (intToCSize . snd) kls) $ \key_lens ->
allocaArray n $ \val_ptrs ->
allocaArray n $ \val_lens ->
allocaArray n $ \err_ptrs -> do
case mcf of
Just cf ->
withArray (replicate n cf) $ \cfs ->
c_rocksdb_multi_get_cf
db_ptr
read_opts
cfs
(intToCSize n)
key_ptrs
key_lens
val_ptrs
val_lens
err_ptrs
Nothing ->
c_rocksdb_multi_get
db_ptr
read_opts
(intToCSize n)
key_ptrs
key_lens
val_ptrs
val_lens
err_ptrs
vals <- peekArray n val_ptrs
lens <- peekArray n val_lens
errs <- peekArray n err_ptrs
-- Own every value and free every error before throwing, so that
-- none of them leaks.
res <- forM (zip vals lens) $ \(v, l) ->
if v == nullPtr
then return Nothing
else Just <$> BU.unsafePackMallocCStringLen (v, cSizeToInt l)
msgs <- forM errs $ \e ->
if e == nullPtr
then return Nothing
else do
m <- peekCString e
free e
return (Just m)
case [m | Just m <- msgs] of
m : _ -> throwIO $ userError $ "multi_get: " ++ m
[] -> return res
-- | Delete a key from the default column family. Deleting a key that does not
-- exist is not an error. Throws an 'IOError' on failure.
delete :: DB -> ByteString -> IO ()
delete db = deleteCommon db Nothing
-- | Like 'delete', but delete from the given column family.
deleteCF :: DB -> ColumnFamily -> ByteString -> IO ()
deleteCF db cf = deleteCommon db (Just cf)
-- | Delete a key/value pair from the default column family, or from a column
-- family if one is given.
deleteCommon :: DB -> Maybe ColumnFamily -> ByteString -> IO ()
deleteCommon DB {rocksDB = db_ptr, writeOpts = write_opts} mcf key =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
throwIfErr "delete" $ case mcf of
Just cf -> c_rocksdb_delete_cf db_ptr write_opts cf key_ptr (intToCSize klen)
Nothing -> c_rocksdb_delete db_ptr write_opts key_ptr (intToCSize klen)
-- | Add a merge record to a key of the default column family, for the
-- t'MergeOperator' of the column family to combine with the value that the
-- key has. Nothing is read: the merge is done when the key is read, and
-- when RocksDB compacts the files that hold the record and the value.
--
-- Throws an 'IOError' if the column family has no merge operator, and on
-- any other failure. For many keys at once use a 'Merge' in a batch.
merge :: DB -> ByteString -> ByteString -> IO ()
merge db = mergeCommon db Nothing
-- | Like 'merge', but for a key of the given column family.
mergeCF :: DB -> ColumnFamily -> ByteString -> ByteString -> IO ()
mergeCF db cf = mergeCommon db (Just cf)
-- | Add a merge record to a key of the default column family, or of a
-- column family if one is given.
mergeCommon :: DB -> Maybe ColumnFamily -> ByteString -> ByteString -> IO ()
mergeCommon DB {rocksDB = db_ptr, writeOpts = write_opts} mcf key value =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
BU.unsafeUseAsCStringLen value $ \(val_ptr, vlen) ->
throwIfErr "merge" $ case mcf of
Just cf ->
c_rocksdb_merge_cf
db_ptr
write_opts
cf
key_ptr
(intToCSize klen)
val_ptr
(intToCSize vlen)
Nothing ->
c_rocksdb_merge
db_ptr
write_opts
key_ptr
(intToCSize klen)
val_ptr
(intToCSize vlen)
-- | Write the memtable of the default column family, or of the one given,
-- to a table file, and return when it is done.
--
-- RocksDB flushes by itself when a memtable is full, and a program does
-- not need this to keep its data: what is in a memtable is in the
-- write-ahead log too. It is for tests and benchmarks that want data in
-- table files, where the data of a database in production is, and with
-- 'disableAutoCompactions' in a file of its own for each flush. Throws an
-- 'IOError' on failure.
flush :: DB -> Maybe ColumnFamily -> IO ()
flush DB {rocksDB = db_ptr} mcf =
bracket c_rocksdb_flushoptions_create c_rocksdb_flushoptions_destroy $ \opts -> do
c_rocksdb_flushoptions_set_wait opts 1
throwIfErr "flush" $ case mcf of
Just cf -> c_rocksdb_flush_cf db_ptr opts cf
Nothing -> c_rocksdb_flush db_ptr opts
-- | Perform a batch mutation. All operations in the list are applied atomically:
-- either all of them are written or none are. They are applied in order, so a
-- later operation on a key overrides an earlier one. Throws an 'IOError' on
-- failure.
--
-- The keys and values are kept alive until RocksDB has copied them, because
-- they are handed to C as pointers into Haskell memory.
--
-- Each operation is handed to RocksDB with a foreign call of its own. For a
-- batch of tens of thousands of operations, 'writePacked' hands them over a
-- few thousand at a call.
write :: DB -> [BatchOp] -> IO ()
write DB {rocksDB = db_ptr, writeOpts = write_opts} batch =
bracket
c_rocksdb_writebatch_create
c_rocksdb_writebatch_destroy
$ \batch_ptr -> do
mapM_ (batchAdd batch_ptr) batch
throwIfErr "write" $ c_rocksdb_write db_ptr write_opts batch_ptr
-- ensure @ByteString@s (and respective shared @CStringLen@s) aren't
-- GC'ed until here
mapM_ touch batch
where
batchAdd batch_ptr (Put key val) =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
BU.unsafeUseAsCStringLen val $ \(val_ptr, vlen) ->
c_rocksdb_writebatch_put
batch_ptr
key_ptr
(intToCSize klen)
val_ptr
(intToCSize vlen)
batchAdd batch_ptr (PutCF cf_ptr key val) =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
BU.unsafeUseAsCStringLen val $ \(val_ptr, vlen) ->
c_rocksdb_writebatch_put_cf
batch_ptr
cf_ptr
key_ptr
(intToCSize klen)
val_ptr
(intToCSize vlen)
batchAdd batch_ptr (Del key) =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
c_rocksdb_writebatch_delete
batch_ptr
key_ptr
(intToCSize klen)
batchAdd batch_ptr (DelCF cf_ptr key) =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
c_rocksdb_writebatch_delete_cf
batch_ptr
cf_ptr
key_ptr
(intToCSize klen)
batchAdd batch_ptr (Merge key val) =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
BU.unsafeUseAsCStringLen val $ \(val_ptr, vlen) ->
c_rocksdb_writebatch_merge
batch_ptr
key_ptr
(intToCSize klen)
val_ptr
(intToCSize vlen)
batchAdd batch_ptr (MergeCF cf_ptr key val) =
BU.unsafeUseAsCStringLen key $ \(key_ptr, klen) ->
BU.unsafeUseAsCStringLen val $ \(val_ptr, vlen) ->
c_rocksdb_writebatch_merge_cf
batch_ptr
cf_ptr
key_ptr
(intToCSize klen)
val_ptr
(intToCSize vlen)
touch (Put (PS p _ _) (PS p' _ _)) = do
touchForeignPtr p
touchForeignPtr p'
touch (PutCF _ (PS p _ _) (PS p' _ _)) = do
touchForeignPtr p
touchForeignPtr p'
touch (Del (PS p _ _)) =
touchForeignPtr p
touch (DelCF _ (PS p _ _)) =
touchForeignPtr p
touch (Merge (PS p _ _) (PS p' _ _)) = do
touchForeignPtr p
touchForeignPtr p'
touch (MergeCF _ (PS p _ _) (PS p' _ _)) = do
touchForeignPtr p
touchForeignPtr p'
-- $packed
--
-- 'write' hands a batch to RocksDB one operation at a time, and each is a
-- foreign call of the kind that lets other Haskell threads run meanwhile:
-- the thread gives up its capability for it, and has to get one back. For
-- a batch of a few operations that is nothing. For the 65,000 keys of a
-- Bitcoin block it was more than half of the time of the batch in the
-- benchmark of this package, 26 ms of 48, and 400 ms or more when eight
-- other threads wanted the four capabilities. It comes on top of a
-- 'ByteString' for each key and each value, which is memory that the
-- collector cannot move.
--
-- A packed batch is the same operations written one after another into a
-- few large buffers: /chunks/. 'writePacked' gives each chunk to a small C
-- function of this package, which adds its operations to the batch, and
-- then writes the batch as 'write' does: atomically, with one write.
--
-- There are two ways to make chunks:
--
-- * 'packOps' packs a list of t'BatchOp' into one chunk. It is the simple
-- way, for small batches and for tests.
--
-- * A program that serialises its keys and values itself can do so
-- straight into a buffer of its own, with no 'ByteString' for each: leave
-- 'packedHeaderSize' bytes, serialise the key and then the value after
-- them, and fill in the header with 'pokePackedHeader' once the two
-- lengths are known. The next record starts where the value ended.
--
-- A record is a header and then the bytes of the key and of the value, with
-- no padding. The header is the column family handle (a null pointer for
-- the default one), the length of the key and that of the value as 32-bit
-- numbers, and one byte for the operation, all as the machine holds them
-- in memory and none of them aligned. @cbits\/rocksdb_haskell.h@ has the
-- layout for a program that writes records by other means.
--
-- The format is this package's own, and what a chunk becomes is a series of
-- calls to the C API of RocksDB. The alternative was to write RocksDB's own
-- encoding of a batch in Haskell and hand it over whole
-- (@rocksdb_writebatch_create_from@), which saves the copy in C. That
-- encoding is internal to RocksDB, with column family numbers and record
-- types that a binding has no business knowing, and the copy costs a few
-- milliseconds for a batch that takes hundreds to write.
--
-- A chunk holds column family handles, which are pointers: it means
-- something only in the process that made it, and only while the database
-- that the handles came from is open.
-- | What a record of a packed batch does to its key.
data PackedOp
= -- | set the key to the value, as 'Put' and 'PutCF' do
PackedPut
| -- | delete the key, as 'Del' and 'DelCF' do; the record has no value
PackedDel
| -- | add a merge record to the key, as 'Merge' and 'MergeCF' do: the
-- value of the record is for the t'MergeOperator' of the column family
-- to combine with the value that the key has.
--
-- On a column family without a merge operator, RocksDB refuses the
-- batch when it is written, and 'writePacked' throws. RocksDB 11 then
-- keeps none of the batch; RocksDB 8.9 keeps the operations that came
-- before the merge. Do not count on either: a batch that is not all
-- or nothing is what a batch is there to prevent.
PackedMerge
deriving (Eq, Show, Enum, Bounded)
-- | Bytes of the header that comes before the key in a record of a packed
-- batch: 17 where a pointer has eight.
packedHeaderSize :: Int
packedHeaderSize = sizeOf (nullPtr :: ColumnFamily) + 2 * sizeOf (0 :: Word32) + 1
-- | Write the header of a record of a packed batch at a pointer, which
-- needs no alignment: the column family, or 'Nothing' for the default one,
-- the operation, the length of the key and the length of the value. It
-- writes 'packedHeaderSize' bytes. The bytes of the key come right after
-- them, and those of the value right after the key.
--
-- It is for a program that serialises keys and values into its own buffer:
-- see the top of this section. The lengths are only known once that is
-- done, so the header is written last, into the room left for it.
--
-- Throws an 'IOError', and writes nothing, if a length is negative or does
-- not fit in 32 bits, or if a 'PackedDel' is given a value.
pokePackedHeader :: Ptr a -> Maybe ColumnFamily -> PackedOp -> Int -> Int -> IO ()
pokePackedHeader ptr mcf op klen vlen = do
when (outside klen || outside vlen) $
throwIO (userError "pokePackedHeader: a length that does not fit in 32 bits")
when (op == PackedDel && vlen /= 0) $
throwIO (userError "pokePackedHeader: a delete with a value")
-- Unaligned writes, in the byte order of the machine, which is how
-- the C side reads them back with memcpy.
poke (castPtr ptr) (fromMaybe nullPtr mcf)
pokeByteOff ptr word (fromIntegral klen :: Word32)
pokeByteOff ptr (word + 4) (fromIntegral vlen :: Word32)
pokeByteOff ptr (word + 8) code
where
word = sizeOf (nullPtr :: ColumnFamily)
-- compared as words, which have 32 bits at least, so that the limit is
-- not a negative number where an 'Int' has 32
outside n = n < 0 || (fromIntegral n :: Word) > fromIntegral (maxBound :: Word32)
-- ROCKSDB_HASKELL_PUT, _DELETE and _MERGE of rocksdb_haskell.h
code :: Word8
code = case op of
PackedPut -> 0
PackedDel -> 1
PackedMerge -> 2
{-# INLINE pokePackedHeader #-}
-- | Pack the operations of a batch into one chunk for 'writePacked', in
-- their order. @'writePacked' db ['packOps' ops]@ does what @'write' db ops@
-- does.
--
-- This is the simple way to a packed batch: it copies every key and value
-- once more, into a buffer as large as all of them together. Use it for
-- small batches, for the odd operation that a program does not serialise
-- itself, and for tests. A program with a large batch gains more by
-- serialising straight into its own chunks with 'pokePackedHeader'.
--
-- The chunk holds the column family handles of the operations, so it is
-- only good while their database is open. Evaluating it throws an 'IOError'
-- if a key or a value is of four gigabytes or more.
packOps :: [BatchOp] -> ByteString
packOps ops = BI.unsafeCreate (sum (map size ops)) $ \start -> foldM_ pack start ops
where
parts (Put k v) = (Nothing, PackedPut, k, v)
parts (Del k) = (Nothing, PackedDel, k, BS.empty)
parts (PutCF cf k v) = (Just cf, PackedPut, k, v)
parts (DelCF cf k) = (Just cf, PackedDel, k, BS.empty)
parts (Merge k v) = (Nothing, PackedMerge, k, v)
parts (MergeCF cf k v) = (Just cf, PackedMerge, k, v)
size op = case parts op of
(_, _, k, v) -> packedHeaderSize + BS.length k + BS.length v
-- write the record of an operation, and give where the next one goes
pack :: Ptr Word8 -> BatchOp -> IO (Ptr Word8)
pack ptr op = do
let (mcf, kind, k, v) = parts op
key_ptr = ptr `plusPtr` packedHeaderSize
val_ptr = key_ptr `plusPtr` BS.length k
pokePackedHeader ptr mcf kind (BS.length k) (BS.length v)
copy k key_ptr
copy v val_ptr
return (val_ptr `plusPtr` BS.length v)
-- memcpy must not be given the pointer of an empty string
copy bytes to =
BU.unsafeUseAsCStringLen bytes $ \(from, len) ->
when (len > 0) $ copyBytes to (castPtr from) len
-- | Write a batch that is given as packed chunks: see the top of this
-- section for what they are and how to make them. All the operations of all
-- the chunks are applied atomically, as one batch and with one write:
-- either all of them are written or none are. They are applied in the order
-- of the chunks, and within a chunk in the order of its records, so a later
-- operation on a key overrides an earlier one.
--
-- Every chunk must hold whole records: a record cannot start in one chunk
-- and end in the next. Where a chunk is cut otherwise does not matter, and
-- an empty chunk or no chunk at all is fine. So a program that packs on
-- several cores gives the chunks of each core, one core after another.
--
-- Use it for batches of thousands of operations, where it saves the
-- foreign call that 'write' makes for each operation, and the 'ByteString'
-- for each key and value if the program packs its own chunks. It makes one
-- foreign call for each chunk, so chunks of a few hundred kilobytes are
-- large enough. For a few operations, 'write' is as fast and simpler.
--
-- Throws an 'IOError', with nothing written, if a chunk is not made of
-- whole records: one that is cut short, an operation that does not exist,
-- a delete with a value. The message names the chunk and the record, both
-- counted from zero. Each chunk is checked in C before any of it is added
-- to the batch, and nothing is read outside it. What cannot be checked is
-- the column family handle of a record: a wrong one crashes the process,
-- as it would in 'PutCF'.
--
-- Also throws an 'IOError' if RocksDB refuses the batch, as 'write' does.
-- That is what happens to a batch with a 'PackedMerge' for a column family
-- that has no 'mergeOperator': RocksDB 11 refuses it when it is written,
-- with nothing written.
writePacked :: DB -> [ByteString] -> IO ()
writePacked DB {rocksDB = db_ptr, writeOpts = write_opts} chunks =
bracket
c_rocksdb_writebatch_create
c_rocksdb_writebatch_destroy
$ \batch_ptr -> do
forM_ (zip [0 :: Int ..] chunks) $ \(n, chunk) ->
-- the chunk cannot move or be freed during the call, and RocksDB
-- has copied what it needs when the call returns
BU.unsafeUseAsCStringLen chunk $ \(chunk_ptr, len) ->
alloca $ \count_ptr -> do
status <-
c_rocksdb_haskell_writebatch_add_packed
batch_ptr
chunk_ptr
(intToCSize len)
count_ptr
when (status /= 0) $ do
count <- peek count_ptr
-- both are counted from zero
throwIO . userError . unwords $
[ "writePacked: chunk",
show n,
"is not made of whole records: record",
show (cSizeToInt count),
"is malformed or cut short"
]
throwIfErr "write" $ c_rocksdb_write db_ptr write_opts batch_ptr
-- | Marshal a list of strings into C strings that are valid while the function
-- runs.
withStrings :: [String] -> ([CString] -> IO a) -> IO a
withStrings ss f =
go [] ss
where
go acc [] = f (reverse acc)
go acc (x : xs) = withCString x $ \p -> go (p : acc) xs