src/leveldb/include/leveldb/db.h

   1 // Copyright (c) 2011 The LevelDB Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file. See the AUTHORS file for names of contributors.
   4
   5 #ifndef STORAGE_LEVELDB_INCLUDE_DB_H_
   6 #define STORAGE_LEVELDB_INCLUDE_DB_H_
   7
   8 #include <stdint.h>
   9 #include <stdio.h>
  10 #include "leveldb/iterator.h"
  11 #include "leveldb/options.h"
  12
  13 namespace leveldb {
  14
  15 // Update Makefile if you change these
  16 static const int kMajorVersion = 1;
  17 static const int kMinorVersion = 20;
  18
  19 struct Options;
  20 struct ReadOptions;
  21 struct WriteOptions;
  22 class WriteBatch;
  23
  24 // Abstract handle to particular state of a DB.
  25 // A Snapshot is an immutable object and can therefore be safely
  26 // accessed from multiple threads without any external synchronization.
  27 class Snapshot {
  28  protected:
  29   virtual ~Snapshot();
  30 };
  31
  32 // A range of keys
  33 struct Range {
  34   Slice start;          // Included in the range
  35   Slice limit;          // Not included in the range
  36
  37   Range() { }
  38   Range(const Slice& s, const Slice& l) : start(s), limit(l) { }
  39 };
  40
  41 // A DB is a persistent ordered map from keys to values.
  42 // A DB is safe for concurrent access from multiple threads without
  43 // any external synchronization.
  44 class DB {
  45  public:
  46   // Open the database with the specified "name".
  47   // Stores a pointer to a heap-allocated database in *dbptr and returns
  48   // OK on success.
  49   // Stores NULL in *dbptr and returns a non-OK status on error.
  50   // Caller should delete *dbptr when it is no longer needed.
  51   static Status Open(const Options& options,
  52                      const std::string& name,
  53                      DB** dbptr);
  54
  55   DB() { }
  56   virtual ~DB();
  57
  58   // Set the database entry for "key" to "value".  Returns OK on success,
  59   // and a non-OK status on error.
  60   // Note: consider setting options.sync = true.
  61   virtual Status Put(const WriteOptions& options,
  62                      const Slice& key,
  63                      const Slice& value) = 0;
  64
  65   // Remove the database entry (if any) for "key".  Returns OK on
  66   // success, and a non-OK status on error.  It is not an error if "key"
  67   // did not exist in the database.
  68   // Note: consider setting options.sync = true.
  69   virtual Status Delete(const WriteOptions& options, const Slice& key) = 0;
  70
  71   // Apply the specified updates to the database.
  72   // Returns OK on success, non-OK on failure.
  73   // Note: consider setting options.sync = true.
  74   virtual Status Write(const WriteOptions& options, WriteBatch* updates) = 0;
  75
  76   // If the database contains an entry for "key" store the
  77   // corresponding value in *value and return OK.
  78   //
  79   // If there is no entry for "key" leave *value unchanged and return
  80   // a status for which Status::IsNotFound() returns true.
  81   //
  82   // May return some other Status on an error.
  83   virtual Status Get(const ReadOptions& options,
  84                      const Slice& key, std::string* value) = 0;
  85
  86   // Return a heap-allocated iterator over the contents of the database.
  87   // The result of NewIterator() is initially invalid (caller must
  88   // call one of the Seek methods on the iterator before using it).
  89   //
  90   // Caller should delete the iterator when it is no longer needed.
  91   // The returned iterator should be deleted before this db is deleted.
  92   virtual Iterator* NewIterator(const ReadOptions& options) = 0;
  93
  94   // Return a handle to the current DB state.  Iterators created with
  95   // this handle will all observe a stable snapshot of the current DB
  96   // state.  The caller must call ReleaseSnapshot(result) when the
  97   // snapshot is no longer needed.
  98   virtual const Snapshot* GetSnapshot() = 0;
  99
 100   // Release a previously acquired snapshot.  The caller must not
 101   // use "snapshot" after this call.
 102   virtual void ReleaseSnapshot(const Snapshot* snapshot) = 0;
 103
 104   // DB implementations can export properties about their state
 105   // via this method.  If "property" is a valid property understood by this
 106   // DB implementation, fills "*value" with its current value and returns
 107   // true.  Otherwise returns false.
 108   //
 109   //
 110   // Valid property names include:
 111   //
 112   //  "leveldb.num-files-at-level<N>" - return the number of files at level <N>,
 113   //     where <N> is an ASCII representation of a level number (e.g. "0").
 114   //  "leveldb.stats" - returns a multi-line string that describes statistics
 115   //     about the internal operation of the DB.
 116   //  "leveldb.sstables" - returns a multi-line string that describes all
 117   //     of the sstables that make up the db contents.
 118   //  "leveldb.approximate-memory-usage" - returns the approximate number of
 119   //     bytes of memory in use by the DB.
 120   virtual bool GetProperty(const Slice& property, std::string* value) = 0;
 121
 122   // For each i in [0,n-1], store in "sizes[i]", the approximate
 123   // file system space used by keys in "[range[i].start .. range[i].limit)".
 124   //
 125   // Note that the returned sizes measure file system space usage, so
 126   // if the user data compresses by a factor of ten, the returned
 127   // sizes will be one-tenth the size of the corresponding user data size.
 128   //
 129   // The results may not include the sizes of recently written data.
 130   virtual void GetApproximateSizes(const Range* range, int n,
 131                                    uint64_t* sizes) = 0;
 132
 133   // Compact the underlying storage for the key range [*begin,*end].
 134   // In particular, deleted and overwritten versions are discarded,
 135   // and the data is rearranged to reduce the cost of operations
 136   // needed to access the data.  This operation should typically only
 137   // be invoked by users who understand the underlying implementation.
 138   //
 139   // begin==NULL is treated as a key before all keys in the database.
 140   // end==NULL is treated as a key after all keys in the database.
 141   // Therefore the following call will compact the entire database:
 142   //    db->CompactRange(NULL, NULL);
 143   virtual void CompactRange(const Slice* begin, const Slice* end) = 0;
 144
 145  private:
 146   // No copying allowed
 147   DB(const DB&);
 148   void operator=(const DB&);
 149 };
 150
 151 // Destroy the contents of the specified database.
 152 // Be very careful using this method.
 153 Status DestroyDB(const std::string& name, const Options& options);
 154
 155 // If a DB cannot be opened, you may attempt to call this method to
 156 // resurrect as much of the contents of the database as possible.
 157 // Some data may be lost, so be careful when calling this function
 158 // on a database that contains important information.
 159 Status RepairDB(const std::string& dbname, const Options& options);
 160
 161 }  // namespace leveldb
 162
 163 #endif  // STORAGE_LEVELDB_INCLUDE_DB_H_