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 = 17; 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 RangeRange37 Range() { } RangeRange38 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 DB()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 virtual bool GetProperty(const Slice& property, std::string* value) = 0; 119 120 // For each i in [0,n-1], store in "sizes[i]", the approximate 121 // file system space used by keys in "[range[i].start .. range[i].limit)". 122 // 123 // Note that the returned sizes measure file system space usage, so 124 // if the user data compresses by a factor of ten, the returned 125 // sizes will be one-tenth the size of the corresponding user data size. 126 // 127 // The results may not include the sizes of recently written data. 128 virtual void GetApproximateSizes(const Range* range, int n, 129 uint64_t* sizes) = 0; 130 131 // Compact the underlying storage for the key range [*begin,*end]. 132 // In particular, deleted and overwritten versions are discarded, 133 // and the data is rearranged to reduce the cost of operations 134 // needed to access the data. This operation should typically only 135 // be invoked by users who understand the underlying implementation. 136 // 137 // begin==NULL is treated as a key before all keys in the database. 138 // end==NULL is treated as a key after all keys in the database. 139 // Therefore the following call will compact the entire database: 140 // db->CompactRange(NULL, NULL); 141 virtual void CompactRange(const Slice* begin, const Slice* end) = 0; 142 143 private: 144 // No copying allowed 145 DB(const DB&); 146 void operator=(const DB&); 147 }; 148 149 // Destroy the contents of the specified database. 150 // Be very careful using this method. 151 Status DestroyDB(const std::string& name, const Options& options); 152 153 // If a DB cannot be opened, you may attempt to call this method to 154 // resurrect as much of the contents of the database as possible. 155 // Some data may be lost, so be careful when calling this function 156 // on a database that contains important information. 157 Status RepairDB(const std::string& dbname, const Options& options); 158 159 } // namespace leveldb 160 161 #endif // STORAGE_LEVELDB_INCLUDE_DB_H_ 162