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
13namespace leveldb {
14
15// Update Makefile if you change these
16static const int kMajorVersion = 1;
17static const int kMinorVersion = 17;
18
19struct Options;
20struct ReadOptions;
21struct WriteOptions;
22class 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.
27class Snapshot {
28 protected:
29  virtual ~Snapshot();
30};
31
32// A range of keys
33struct 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.
44class 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  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.
151Status 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.
157Status RepairDB(const std::string& dbname, const Options& options);
158
159}  // namespace leveldb
160
161#endif  // STORAGE_LEVELDB_INCLUDE_DB_H_
162