sync with upstream @ 21409451

Check the NEWS file for details of what changed.

git-svn-id: https://leveldb.googlecode.com/svn/trunk@28 62dab493-f737-651d-591e-8d6aee1b9529

9 files changed, 85 insertions, 20 deletions

diff --git a/include/leveldb/comparator.h b/include/leveldb/comparator.h
index 4e00e4d..c215fac 100644
--- a/include/leveldb/comparator.h
+++ b/include/leveldb/comparator.h
@@ -12,7 +12,9 @@ namespace leveldb {
 class Slice;
 
 // A Comparator object provides a total order across slices that are
-// used as keys in an sstable or a database.
+// used as keys in an sstable or a database.  A Comparator implementation
+// must be thread-safe since leveldb may invoke its methods concurrently
+// from multiple threads.
 class Comparator {
  public:
   virtual ~Comparator();
diff --git a/include/leveldb/db.h b/include/leveldb/db.h
index f18ded3..79bd283 100644
--- a/include/leveldb/db.h
+++ b/include/leveldb/db.h
@@ -13,26 +13,32 @@
 namespace leveldb {
 
 static const int kMajorVersion = 1;
-static const int kMinorVersion = 1;
+static const int kMinorVersion = 2;
 
 struct Options;
 struct ReadOptions;
 struct WriteOptions;
-
-class Snapshot;
 class WriteBatch;
 
-// Some internal types.  Clients should ignore.
-class WriteBatchInternal;
+// Abstract handle to particular state of a DB.
+// A Snapshot is an immutable object and can therefore be safely
+// accessed from multiple threads without any external synchronization.
+class Snapshot {
+ protected:
+  virtual ~Snapshot();
+};
 
+// A range of keys
 struct Range {
-  Slice start;
-  Slice limit;
+  Slice start;          // Included in the range
+  Slice limit;          // Not included in the range
 
   Range(const Slice& s, const Slice& l) : start(s), limit(l) { }
 };
 
 // A DB is a persistent ordered map from keys to values.
+// A DB is safe for concurrent access from multiple threads without
+// any external synchronization.
 class DB {
  public:
   // Open the database with the specified "name".
diff --git a/include/leveldb/env.h b/include/leveldb/env.h
index 4b6e712..39f6a1a 100644
--- a/include/leveldb/env.h
+++ b/include/leveldb/env.h
@@ -6,6 +6,9 @@
 // operating system functionality like the filesystem etc.  Callers
 // may wish to provide a custom Env object when opening a database to
 // get fine gain control; e.g., to rate limit file system operations.
+//
+// All Env implementations are safe for concurrent access from
+// multiple threads without any external synchronization.
 
 #ifndef STORAGE_LEVELDB_INCLUDE_ENV_H_
 #define STORAGE_LEVELDB_INCLUDE_ENV_H_
@@ -160,6 +163,15 @@ class SequentialFile {
   //
   // REQUIRES: External synchronization
   virtual Status Read(size_t n, Slice* result, char* scratch) = 0;
+
+  // Skip "n" bytes from the file. This is guaranteed to be no
+  // slower that reading the same data, but may be faster.
+  //
+  // If end of file is reached, skipping will stop at the end of the
+  // file, and Skip will return OK.
+  //
+  // REQUIRES: External synchronization
+  virtual Status Skip(uint64_t n) = 0;
 };
 
 // A file abstraction for randomly reading the contents of a file.
diff --git a/include/leveldb/iterator.h b/include/leveldb/iterator.h
index 1866fb5..6821d85 100644
--- a/include/leveldb/iterator.h
+++ b/include/leveldb/iterator.h
@@ -6,6 +6,11 @@
 // The following class defines the interface.  Multiple implementations
 // are provided by this library.  In particular, iterators are provided
 // to access the contents of a Table or a DB.
+//
+// Multiple threads can invoke const methods on an Iterator without
+// external synchronization, but if any of the threads may call a
+// non-const method, all threads accessing the same Iterator must use
+// external synchronization.
 
 #ifndef STORAGE_LEVELDB_INCLUDE_ITERATOR_H_
 #define STORAGE_LEVELDB_INCLUDE_ITERATOR_H_
diff --git a/include/leveldb/slice.h b/include/leveldb/slice.h
index 62cb894..3c000b8 100644
--- a/include/leveldb/slice.h
+++ b/include/leveldb/slice.h
@@ -6,6 +6,11 @@
 // storage and a size.  The user of a Slice must ensure that the slice
 // is not used after the corresponding external storage has been
 // deallocated.
+//
+// Multiple threads can invoke const methods on a Slice without
+// external synchronization, but if any of the threads may call a
+// non-const method, all threads accessing the same Slice must use
+// external synchronization.
 
 #ifndef STORAGE_LEVELDB_INCLUDE_SLICE_H_
 #define STORAGE_LEVELDB_INCLUDE_SLICE_H_
diff --git a/include/leveldb/status.h b/include/leveldb/status.h
index 47e3edf..6796fdd 100644
--- a/include/leveldb/status.h
+++ b/include/leveldb/status.h
@@ -4,12 +4,16 @@
 //
 // A Status encapsulates the result of an operation.  It may indicate success,
 // or it may indicate an error with an associated error message.
+//
+// Multiple threads can invoke const methods on a Status without
+// external synchronization, but if any of the threads may call a
+// non-const method, all threads accessing the same Status must use
+// external synchronization.
 
 #ifndef STORAGE_LEVELDB_INCLUDE_STATUS_H_
 #define STORAGE_LEVELDB_INCLUDE_STATUS_H_
 
 #include <string>
-#include <utility>
 #include "leveldb/slice.h"
 
 namespace leveldb {
@@ -18,7 +22,7 @@ class Status {
  public:
   // Create a success status.
   Status() : state_(NULL) { }
-  ~Status() { delete state_; }
+  ~Status() { delete[] state_; }
 
   // Copy the specified status.
   Status(const Status& s);
@@ -29,7 +33,7 @@ class Status {
 
   // Return error status of an appropriate type.
   static Status NotFound(const Slice& msg, const Slice& msg2 = Slice()) {
-    return Status(kNotFound, msg, Slice());
+    return Status(kNotFound, msg, msg2);
   }
   static Status Corruption(const Slice& msg, const Slice& msg2 = Slice()) {
     return Status(kCorruption, msg, msg2);
@@ -55,6 +59,13 @@ class Status {
   std::string ToString() const;
 
  private:
+  // OK status has a NULL state_.  Otherwise, state_ is a new[] array
+  // of the following form:
+  //    state_[0..3] == length of message
+  //    state_[4]    == code
+  //    state_[5..]  == message
+  const char* state_;
+
   enum Code {
     kOk = 0,
     kNotFound = 1,
@@ -63,21 +74,24 @@ class Status {
     kInvalidArgument = 4,
     kIOError = 5,
   };
-  Code code() const { return (state_ == NULL) ? kOk : state_->first; }
 
-  Status(Code code, const Slice& msg, const Slice& msg2);
+  Code code() const {
+    return (state_ == NULL) ? kOk : static_cast<Code>(state_[4]);
+  }
 
-  typedef std::pair<Code, std::string> State;
-  State* state_;
+  Status(Code code, const Slice& msg, const Slice& msg2);
+  static const char* CopyState(const char* s);
 };
 
 inline Status::Status(const Status& s) {
-  state_ = (s.state_ == NULL) ? NULL : new State(*s.state_);
+  state_ = (s.state_ == NULL) ? NULL : CopyState(s.state_);
 }
 inline void Status::operator=(const Status& s) {
-  if (this != &s) {
-    delete state_;
-    state_ = (s.state_ == NULL) ? NULL : new State(*s.state_);
+  // The following condition catches both aliasing (when this == &s),
+  // and the common case where both s and *this are ok.
+  if (state_ != s.state_) {
+    delete[] state_;
+    state_ = (s.state_ == NULL) ? NULL : CopyState(s.state_);
   }
 }
 
diff --git a/include/leveldb/table.h b/include/leveldb/table.h
index bd99176..35e5d22 100644
--- a/include/leveldb/table.h
+++ b/include/leveldb/table.h
@@ -17,7 +17,8 @@ class RandomAccessFile;
 struct ReadOptions;
 
 // A Table is a sorted map from strings to strings.  Tables are
-// immutable and persistent.
+// immutable and persistent.  A Table may be safely accessed from
+// multiple threads without external synchronization.
 class Table {
  public:
   // Attempt to open the table that is stored in bytes [0..file_size)
diff --git a/include/leveldb/table_builder.h b/include/leveldb/table_builder.h
index 49d2d51..23851de 100644
--- a/include/leveldb/table_builder.h
+++ b/include/leveldb/table_builder.h
@@ -4,6 +4,11 @@
 //
 // TableBuilder provides the interface used to build a Table
 // (an immutable and sorted map from keys to values).
+//
+// Multiple threads can invoke const methods on a TableBuilder without
+// external synchronization, but if any of the threads may call a
+// non-const method, all threads accessing the same TableBuilder must use
+// external synchronization.
 
 #ifndef STORAGE_LEVELDB_INCLUDE_TABLE_BUILDER_H_
 #define STORAGE_LEVELDB_INCLUDE_TABLE_BUILDER_H_
diff --git a/include/leveldb/write_batch.h b/include/leveldb/write_batch.h
index 3411952..b4446c2 100644
--- a/include/leveldb/write_batch.h
+++ b/include/leveldb/write_batch.h
@@ -12,11 +12,17 @@
 //    batch.Delete("key");
 //    batch.Put("key", "v2");
 //    batch.Put("key", "v3");
+//
+// Multiple threads can invoke const methods on a WriteBatch without
+// external synchronization, but if any of the threads may call a
+// non-const method, all threads accessing the same WriteBatch must use
+// external synchronization.
 
 #ifndef STORAGE_LEVELDB_INCLUDE_WRITE_BATCH_H_
 #define STORAGE_LEVELDB_INCLUDE_WRITE_BATCH_H_
 
 #include <string>
+#include "leveldb/status.h"
 
 namespace leveldb {
 
@@ -36,6 +42,15 @@ class WriteBatch {
   // Clear all updates buffered in this batch.
   void Clear();
 
+  // Support for iterating over the contents of a batch.
+  class Handler {
+   public:
+    virtual ~Handler();
+    virtual void Put(const Slice& key, const Slice& value) = 0;
+    virtual void Delete(const Slice& key) = 0;
+  };
+  Status Iterate(Handler* handler) const;
+
  private:
   friend class WriteBatchInternal;