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