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
15namespace leveldb {
16
17// Update CMakeLists.txt if you change these
18static const int kMajorVersion = 1;
19static const int kMinorVersion = 23;
20
21struct Options;
22struct ReadOptions;
23struct WriteOptions;
24class 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.
29class LEVELDB_EXPORT Snapshot {
30 protected:
31 virtual ~Snapshot();
32};
33
34// A range of keys
35struct 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.
46class 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.
155LEVELDB_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.
162LEVELDB_EXPORT Status RepairDB(const std::string& dbname,
163 const Options& options);
164
165} // namespace leveldb
166
167#endif // STORAGE_LEVELDB_INCLUDE_DB_H_
168