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 <cstdint> |
9 | #include <cstdio> |
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 = 23; |
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_ |
168 | |