@ -25,27 +25,27 @@ creating it if necessary:
#include < assert>
#include "leveldb/db.h"
level db::DB* db;
level db::Options options;
rocks db::DB* db;
rocks db::Options options;
options.create_if_missing = true;
leveldb::Status status = level db::DB::Open(options, "/tmp/testdb", & db);
rocksdb::Status status = rocks db::DB::Open(options, "/tmp/testdb", & db);
assert(status.ok());
...
< / pre >
If you want to raise an error if the database already exists, add
the following line before the < code > level db::DB::Open< / code > call:
the following line before the < code > rocks db::DB::Open< / code > call:
< pre >
options.error_if_exists = true;
< / pre >
< h1 > Status< / h1 >
< p >
You may have noticed the < code > level db::Status< / code > type above. Values of this
You may have noticed the < code > rocks db::Status< / code > type above. Values of this
type are returned by most functions in < code > leveldb< / code > that may encounter an
error. You can check if such a result is ok, and also print an
associated error message:
< p >
< pre >
level db::Status s = ...;
rocks db::Status s = ...;
if (!s.ok()) cerr < < s.ToString() < < endl;
< / pre >
< h1 > Closing A Database< / h1 >
@ -65,9 +65,9 @@ modify/query the database. For example, the following code
moves the value stored under key1 to key2.
< pre >
std::string value;
leveldb::Status s = db-> Get(level db::ReadOptions(), key1, & value);
if (s.ok()) s = db-> Put(level db::WriteOptions(), key2, value);
if (s.ok()) s = db-> Delete(level db::WriteOptions(), key1);
rocksdb::Status s = db-> Get(rocks db::ReadOptions(), key1, & value);
if (s.ok()) s = db-> Put(rocks db::WriteOptions(), key2, value);
if (s.ok()) s = db-> Delete(rocks db::WriteOptions(), key1);
< / pre >
< h1 > Atomic Updates< / h1 >
@ -81,12 +81,12 @@ atomically apply a set of updates:
#include "leveldb/write_batch.h"
...
std::string value;
leveldb::Status s = db-> Get(level db::ReadOptions(), key1, & value);
rocksdb::Status s = db-> Get(rocks db::ReadOptions(), key1, & value);
if (s.ok()) {
level db::WriteBatch batch;
rocks db::WriteBatch batch;
batch.Delete(key1);
batch.Put(key2, value);
s = db-> Write(level db::WriteOptions(), & batch);
s = db-> Write(rocks db::WriteOptions(), & batch);
}
< / pre >
The < code > WriteBatch< / code > holds a sequence of edits to be made to the database,
@ -109,7 +109,7 @@ persistent storage. (On Posix systems, this is implemented by calling
either < code > fsync(...)< / code > or < code > fdatasync(...)< / code > or
< code > msync(..., MS_SYNC)< / code > before the write operation returns.)
< pre >
level db::WriteOptions write_options;
rocks db::WriteOptions write_options;
write_options.sync = true;
db-> Put(write_options, ...);
< / pre >
@ -144,7 +144,7 @@ the batch.
A database may only be opened by one process at a time.
The < code > leveldb< / code > implementation acquires a lock from the
operating system to prevent misuse. Within a single process, the
same < code > level db::DB< / code > object may be safely shared by multiple
same < code > rocks db::DB< / code > object may be safely shared by multiple
concurrent threads. I.e., different threads may write into or fetch
iterators or call < code > Get< / code > on the same database without any
external synchronization (the leveldb implementation will
@ -160,7 +160,7 @@ The following example demonstrates how to print all key,value pairs
in a database.
< p >
< pre >
leveldb::Iterator* it = db-> NewIterator(level db::ReadOptions());
rocksdb::Iterator* it = db-> NewIterator(rocks db::ReadOptions());
for (it-> SeekToFirst(); it-> Valid(); it-> Next()) {
cout < < it-> key().ToString() < < ": " < < it-> value().ToString() < < endl;
}
@ -196,10 +196,10 @@ implicit snapshot of the current state.
Snapshots are created by the DB::GetSnapshot() method:
< p >
< pre >
level db::ReadOptions options;
rocks db::ReadOptions options;
options.snapshot = db-> GetSnapshot();
... apply some updates to db ...
level db::Iterator* iter = db-> NewIterator(options);
rocks db::Iterator* iter = db-> NewIterator(options);
... read using iter to view the state when the snapshot was created ...
delete iter;
db-> ReleaseSnapshot(options.snapshot);
@ -211,7 +211,7 @@ support reading as of that snapshot.
< h1 > Slice< / h1 >
< p >
The return value of the < code > it->key()< / code > and < code > it->value()< / code > calls above
are instances of the < code > level db::Slice< / code > type. < code > Slice< / code > is a simple
are instances of the < code > rocks db::Slice< / code > type. < code > Slice< / code > is a simple
structure that contains a length and a pointer to an external byte
array. Returning a < code > Slice< / code > is a cheaper alternative to returning a
< code > std::string< / code > since we do not need to copy potentially large keys and
@ -223,10 +223,10 @@ C++ strings and null-terminated C-style strings can be easily converted
to a Slice:
< p >
< pre >
level db::Slice s1 = "hello";
rocks db::Slice s1 = "hello";
std::string str("world");
level db::Slice s2 = str;
rocks db::Slice s2 = str;
< / pre >
A Slice can be easily converted back to a C++ string:
< pre >
@ -238,7 +238,7 @@ the external byte array into which the Slice points remains live while
the Slice is in use. For example, the following is buggy:
< p >
< pre >
level db::Slice slice;
rocks db::Slice slice;
if (...) {
std::string str = ...;
slice = str;
@ -255,16 +255,16 @@ which orders bytes lexicographically. You can however supply a custom
comparator when opening a database. For example, suppose each
database key consists of two numbers and we should sort by the first
number, breaking ties by the second number. First, define a proper
subclass of < code > level db::Comparator< / code > that expresses these rules:
subclass of < code > rocks db::Comparator< / code > that expresses these rules:
< p >
< pre >
class TwoPartComparator : public level db::Comparator {
class TwoPartComparator : public rocks db::Comparator {
public:
// Three-way comparison function:
// if a < b: negative result
// if a > b: positive result
// else: zero result
int Compare(const leveldb::Slice& a, const level db::Slice& b) const {
int Compare(const rocksdb::Slice& a, const rocks db::Slice& b) const {
int a1, a2, b1, b2;
ParseKey(a, & a1, & a2);
ParseKey(b, & b1, & b2);
@ -277,7 +277,7 @@ subclass of <code>leveldb::Comparator</code> that expresses these rules:
// Ignore the following methods for now:
const char* Name() const { return "TwoPartComparator"; }
void FindShortestSeparator(std::string*, const level db::Slice& ) const { }
void FindShortestSeparator(std::string*, const rocks db::Slice& ) const { }
void FindShortSuccessor(std::string*) const { }
};
< / pre >
@ -285,18 +285,18 @@ Now create a database using this custom comparator:
< p >
< pre >
TwoPartComparator cmp;
level db::DB* db;
level db::Options options;
rocks db::DB* db;
rocks db::Options options;
options.create_if_missing = true;
options.comparator = & cmp;
leveldb::Status status = level db::DB::Open(options, "/tmp/testdb", & db);
rocksdb::Status status = rocks db::DB::Open(options, "/tmp/testdb", & db);
...
< / pre >
< h2 > Backwards compatibility< / h2 >
< p >
The result of the comparator's < code > Name< / code > method is attached to the
database when it is created, and is checked on every subsequent
database open. If the name changes, the < code > level db::DB::Open< / code > call will
database open. If the name changes, the < code > rocks db::DB::Open< / code > call will
fail. Therefore, change the name if and only if the new key format
and comparison function are incompatible with existing databases, and
it is ok to discard the contents of all existing databases.
@ -339,9 +339,9 @@ compression entirely, but should only do so if benchmarks show a
performance improvement:
< p >
< pre >
level db::Options options;
options.compression = level db::kNoCompression;
... level db::DB::Open(options, name, ...) ....
rocks db::Options options;
options.compression = rocks db::kNoCompression;
... rocks db::DB::Open(options, name, ...) ....
< / pre >
< h2 > Cache< / h2 >
< p >
@ -353,10 +353,10 @@ uncompressed block contents.
< pre >
#include "leveldb/cache.h"
level db::Options options;
options.cache = level db::NewLRUCache(100 * 1048576); // 100MB cache
level db::DB* db;
level db::DB::Open(options, name, &db);
rocks db::Options options;
options.cache = rocks db::NewLRUCache(100 * 1048576); // 100MB cache
rocks db::DB* db;
rocks db::DB::Open(options, name, &db);
... use the db ...
delete db
delete options.cache;
@ -373,9 +373,9 @@ displacing most of the cached contents. A per-iterator option can be
used to achieve this:
< p >
< pre >
level db::ReadOptions options;
rocks db::ReadOptions options;
options.fill_cache = false;
level db::Iterator* it = db-> NewIterator(options);
rocks db::Iterator* it = db-> NewIterator(options);
for (it-> SeekToFirst(); it-> Valid(); it-> Next()) {
...
}
@ -407,10 +407,10 @@ a single <code>Get()</code> call may involve multiple reads from disk.
The optional < code > FilterPolicy< / code > mechanism can be used to reduce
the number of disk reads substantially.
< pre >
level db::Options options;
rocks db::Options options;
options.filter_policy = NewBloomFilter(10);
level db::DB* db;
level db::DB::Open(options, "/tmp/testdb", & db);
rocks db::DB* db;
rocks db::DB::Open(options, "/tmp/testdb", & db);
... use the database ...
delete db;
delete options.filter_policy;
@ -434,7 +434,7 @@ consider a comparator that ignores trailing spaces when comparing keys.
Instead, the application should provide a custom filter policy that
also ignores trailing spaces. For example:
< pre >
class CustomFilterPolicy : public level db::FilterPolicy {
class CustomFilterPolicy : public rocks db::FilterPolicy {
private:
FilterPolicy* builtin_policy_;
public:
@ -484,7 +484,7 @@ checksums are verified:
parts of its persistent storage have been corrupted.
< p >
If a database is corrupted (perhaps it cannot be opened when
paranoid checking is turned on), the < code > level db::RepairDB< / code > function
paranoid checking is turned on), the < code > rocks db::RepairDB< / code > function
may be used to recover as much of the data as possible
< p >
< / ul >
@ -494,11 +494,11 @@ The <code>GetApproximateSizes</code> method can used to get the approximate
number of bytes of file system space used by one or more key ranges.
< p >
< pre >
level db::Range ranges[2];
ranges[0] = level db::Range("a", "c");
ranges[1] = level db::Range("x", "z");
rocks db::Range ranges[2];
ranges[0] = rocks db::Range("a", "c");
ranges[1] = rocks db::Range("x", "z");
uint64_t sizes[2];
level db::Status s = db-> GetApproximateSizes(ranges, 2, sizes);
rocks db::Status s = db-> GetApproximateSizes(ranges, 2, sizes);
< / pre >
The preceding call will set < code > sizes[0]< / code > to the approximate number of
bytes of file system space used by the key range < code > [a..c)< / code > and
@ -508,21 +508,21 @@ bytes of file system space used by the key range <code>[a..c)</code> and
< h1 > Environment< / h1 >
< p >
All file operations (and other operating system calls) issued by the
< code > leveldb< / code > implementation are routed through a < code > level db::Env< / code > object.
< code > leveldb< / code > implementation are routed through a < code > rocks db::Env< / code > object.
Sophisticated clients may wish to provide their own < code > Env< / code >
implementation to get better control. For example, an application may
introduce artificial delays in the file IO paths to limit the impact
of < code > leveldb< / code > on other activities in the system.
< p >
< pre >
class SlowEnv : public level db::Env {
class SlowEnv : public rocks db::Env {
.. implementation of the Env interface ...
};
SlowEnv env;
level db::Options options;
rocks db::Options options;
options.env = & env;
Status s = level db::DB::Open(options, ...);
Status s = rocks db::DB::Open(options, ...);
< / pre >
< h1 > Porting< / h1 >
< p >
@ -531,7 +531,7 @@ specific implementations of the types/methods/functions exported by
< code > leveldb/port/port.h< / code > . See < code > leveldb/port/port_example.h< / code > for more
details.
< p >
In addition, the new platform may need a new default < code > level db::Env< / code >
In addition, the new platform may need a new default < code > rocks db::Env< / code >
implementation. See < code > leveldb/util/env_posix.h< / code > for an example.
< h1 > Other Information< / h1 >
Dhruba Borthakur
11 years ago