作者: 韩晨旭 10225101440 李畅 10225102463
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

323 lines
11 KiB

  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. // An Env is an interface used by the leveldb implementation to access
  6. // operating system functionality like the filesystem etc. Callers
  7. // may wish to provide a custom Env object when opening a database to
  8. // get fine gain control; e.g., to rate limit file system operations.
  9. //
  10. // All Env implementations are safe for concurrent access from
  11. // multiple threads without any external synchronization.
  12. #ifndef STORAGE_LEVELDB_INCLUDE_ENV_H_
  13. #define STORAGE_LEVELDB_INCLUDE_ENV_H_
  14. #include <cstdarg>
  15. #include <string>
  16. #include <vector>
  17. #include <stdint.h>
  18. #include "leveldb/status.h"
  19. namespace leveldb {
  20. class FileLock;
  21. class Logger;
  22. class RandomAccessFile;
  23. class SequentialFile;
  24. class Slice;
  25. class WritableFile;
  26. class Env {
  27. public:
  28. Env() { }
  29. virtual ~Env();
  30. // Return a default environment suitable for the current operating
  31. // system. Sophisticated users may wish to provide their own Env
  32. // implementation instead of relying on this default environment.
  33. //
  34. // The result of Default() belongs to leveldb and must never be deleted.
  35. static Env* Default();
  36. // Create a brand new sequentially-readable file with the specified name.
  37. // On success, stores a pointer to the new file in *result and returns OK.
  38. // On failure stores NULL in *result and returns non-OK. If the file does
  39. // not exist, returns a non-OK status.
  40. //
  41. // The returned file will only be accessed by one thread at a time.
  42. virtual Status NewSequentialFile(const std::string& fname,
  43. SequentialFile** result) = 0;
  44. // Create a brand new random access read-only file with the
  45. // specified name. On success, stores a pointer to the new file in
  46. // *result and returns OK. On failure stores NULL in *result and
  47. // returns non-OK. If the file does not exist, returns a non-OK
  48. // status.
  49. //
  50. // The returned file may be concurrently accessed by multiple threads.
  51. virtual Status NewRandomAccessFile(const std::string& fname,
  52. RandomAccessFile** result) = 0;
  53. // Create an object that writes to a new file with the specified
  54. // name. Deletes any existing file with the same name and creates a
  55. // new file. On success, stores a pointer to the new file in
  56. // *result and returns OK. On failure stores NULL in *result and
  57. // returns non-OK.
  58. //
  59. // The returned file will only be accessed by one thread at a time.
  60. virtual Status NewWritableFile(const std::string& fname,
  61. WritableFile** result) = 0;
  62. // Returns true iff the named file exists.
  63. virtual bool FileExists(const std::string& fname) = 0;
  64. // Store in *result the names of the children of the specified directory.
  65. // The names are relative to "dir".
  66. // Original contents of *results are dropped.
  67. virtual Status GetChildren(const std::string& dir,
  68. std::vector<std::string>* result) = 0;
  69. // Delete the named file.
  70. virtual Status DeleteFile(const std::string& fname) = 0;
  71. // Create the specified directory.
  72. virtual Status CreateDir(const std::string& dirname) = 0;
  73. // Delete the specified directory.
  74. virtual Status DeleteDir(const std::string& dirname) = 0;
  75. // Store the size of fname in *file_size.
  76. virtual Status GetFileSize(const std::string& fname, uint64_t* file_size) = 0;
  77. // Rename file src to target.
  78. virtual Status RenameFile(const std::string& src,
  79. const std::string& target) = 0;
  80. // Lock the specified file. Used to prevent concurrent access to
  81. // the same db by multiple processes. On failure, stores NULL in
  82. // *lock and returns non-OK.
  83. //
  84. // On success, stores a pointer to the object that represents the
  85. // acquired lock in *lock and returns OK. The caller should call
  86. // UnlockFile(*lock) to release the lock. If the process exits,
  87. // the lock will be automatically released.
  88. //
  89. // If somebody else already holds the lock, finishes immediately
  90. // with a failure. I.e., this call does not wait for existing locks
  91. // to go away.
  92. //
  93. // May create the named file if it does not already exist.
  94. virtual Status LockFile(const std::string& fname, FileLock** lock) = 0;
  95. // Release the lock acquired by a previous successful call to LockFile.
  96. // REQUIRES: lock was returned by a successful LockFile() call
  97. // REQUIRES: lock has not already been unlocked.
  98. virtual Status UnlockFile(FileLock* lock) = 0;
  99. // Arrange to run "(*function)(arg)" once in a background thread.
  100. //
  101. // "function" may run in an unspecified thread. Multiple functions
  102. // added to the same Env may run concurrently in different threads.
  103. // I.e., the caller may not assume that background work items are
  104. // serialized.
  105. virtual void Schedule(
  106. void (*function)(void* arg),
  107. void* arg) = 0;
  108. // Start a new thread, invoking "function(arg)" within the new thread.
  109. // When "function(arg)" returns, the thread will be destroyed.
  110. virtual void StartThread(void (*function)(void* arg), void* arg) = 0;
  111. // *path is set to a temporary directory that can be used for testing. It may
  112. // or many not have just been created. The directory may or may not differ
  113. // between runs of the same process, but subsequent calls will return the
  114. // same directory.
  115. virtual Status GetTestDirectory(std::string* path) = 0;
  116. // Create and return a log file for storing informational messages.
  117. virtual Status NewLogger(const std::string& fname, Logger** result) = 0;
  118. // Returns the number of micro-seconds since some fixed point in time. Only
  119. // useful for computing deltas of time.
  120. virtual uint64_t NowMicros() = 0;
  121. // Sleep/delay the thread for the perscribed number of micro-seconds.
  122. virtual void SleepForMicroseconds(int micros) = 0;
  123. private:
  124. // No copying allowed
  125. Env(const Env&);
  126. void operator=(const Env&);
  127. };
  128. // A file abstraction for reading sequentially through a file
  129. class SequentialFile {
  130. public:
  131. SequentialFile() { }
  132. virtual ~SequentialFile();
  133. // Read up to "n" bytes from the file. "scratch[0..n-1]" may be
  134. // written by this routine. Sets "*result" to the data that was
  135. // read (including if fewer than "n" bytes were successfully read).
  136. // May set "*result" to point at data in "scratch[0..n-1]", so
  137. // "scratch[0..n-1]" must be live when "*result" is used.
  138. // If an error was encountered, returns a non-OK status.
  139. //
  140. // REQUIRES: External synchronization
  141. virtual Status Read(size_t n, Slice* result, char* scratch) = 0;
  142. // Skip "n" bytes from the file. This is guaranteed to be no
  143. // slower that reading the same data, but may be faster.
  144. //
  145. // If end of file is reached, skipping will stop at the end of the
  146. // file, and Skip will return OK.
  147. //
  148. // REQUIRES: External synchronization
  149. virtual Status Skip(uint64_t n) = 0;
  150. };
  151. // A file abstraction for randomly reading the contents of a file.
  152. class RandomAccessFile {
  153. public:
  154. RandomAccessFile() { }
  155. virtual ~RandomAccessFile();
  156. // Read up to "n" bytes from the file starting at "offset".
  157. // "scratch[0..n-1]" may be written by this routine. Sets "*result"
  158. // to the data that was read (including if fewer than "n" bytes were
  159. // successfully read). May set "*result" to point at data in
  160. // "scratch[0..n-1]", so "scratch[0..n-1]" must be live when
  161. // "*result" is used. If an error was encountered, returns a non-OK
  162. // status.
  163. //
  164. // Safe for concurrent use by multiple threads.
  165. virtual Status Read(uint64_t offset, size_t n, Slice* result,
  166. char* scratch) const = 0;
  167. };
  168. // A file abstraction for sequential writing. The implementation
  169. // must provide buffering since callers may append small fragments
  170. // at a time to the file.
  171. class WritableFile {
  172. public:
  173. WritableFile() { }
  174. virtual ~WritableFile();
  175. virtual Status Append(const Slice& data) = 0;
  176. virtual Status Close() = 0;
  177. virtual Status Flush() = 0;
  178. virtual Status Sync() = 0;
  179. private:
  180. // No copying allowed
  181. WritableFile(const WritableFile&);
  182. void operator=(const WritableFile&);
  183. };
  184. // An interface for writing log messages.
  185. class Logger {
  186. public:
  187. Logger() { }
  188. virtual ~Logger();
  189. // Write an entry to the log file with the specified format.
  190. virtual void Logv(const char* format, va_list ap) = 0;
  191. private:
  192. // No copying allowed
  193. Logger(const Logger&);
  194. void operator=(const Logger&);
  195. };
  196. // Identifies a locked file.
  197. class FileLock {
  198. public:
  199. FileLock() { }
  200. virtual ~FileLock();
  201. private:
  202. // No copying allowed
  203. FileLock(const FileLock&);
  204. void operator=(const FileLock&);
  205. };
  206. // Log the specified data to *info_log if info_log is non-NULL.
  207. extern void Log(Logger* info_log, const char* format, ...)
  208. # if defined(__GNUC__) || defined(__clang__)
  209. __attribute__((__format__ (__printf__, 2, 3)))
  210. # endif
  211. ;
  212. // A utility routine: write "data" to the named file.
  213. extern Status WriteStringToFile(Env* env, const Slice& data,
  214. const std::string& fname);
  215. // A utility routine: read contents of named file into *data
  216. extern Status ReadFileToString(Env* env, const std::string& fname,
  217. std::string* data);
  218. // An implementation of Env that forwards all calls to another Env.
  219. // May be useful to clients who wish to override just part of the
  220. // functionality of another Env.
  221. class EnvWrapper : public Env {
  222. public:
  223. // Initialize an EnvWrapper that delegates all calls to *t
  224. explicit EnvWrapper(Env* t) : target_(t) { }
  225. virtual ~EnvWrapper();
  226. // Return the target to which this Env forwards all calls
  227. Env* target() const { return target_; }
  228. // The following text is boilerplate that forwards all methods to target()
  229. Status NewSequentialFile(const std::string& f, SequentialFile** r) {
  230. return target_->NewSequentialFile(f, r);
  231. }
  232. Status NewRandomAccessFile(const std::string& f, RandomAccessFile** r) {
  233. return target_->NewRandomAccessFile(f, r);
  234. }
  235. Status NewWritableFile(const std::string& f, WritableFile** r) {
  236. return target_->NewWritableFile(f, r);
  237. }
  238. bool FileExists(const std::string& f) { return target_->FileExists(f); }
  239. Status GetChildren(const std::string& dir, std::vector<std::string>* r) {
  240. return target_->GetChildren(dir, r);
  241. }
  242. Status DeleteFile(const std::string& f) { return target_->DeleteFile(f); }
  243. Status CreateDir(const std::string& d) { return target_->CreateDir(d); }
  244. Status DeleteDir(const std::string& d) { return target_->DeleteDir(d); }
  245. Status GetFileSize(const std::string& f, uint64_t* s) {
  246. return target_->GetFileSize(f, s);
  247. }
  248. Status RenameFile(const std::string& s, const std::string& t) {
  249. return target_->RenameFile(s, t);
  250. }
  251. Status LockFile(const std::string& f, FileLock** l) {
  252. return target_->LockFile(f, l);
  253. }
  254. Status UnlockFile(FileLock* l) { return target_->UnlockFile(l); }
  255. void Schedule(void (*f)(void*), void* a) {
  256. return target_->Schedule(f, a);
  257. }
  258. void StartThread(void (*f)(void*), void* a) {
  259. return target_->StartThread(f, a);
  260. }
  261. virtual Status GetTestDirectory(std::string* path) {
  262. return target_->GetTestDirectory(path);
  263. }
  264. virtual Status NewLogger(const std::string& fname, Logger** result) {
  265. return target_->NewLogger(fname, result);
  266. }
  267. uint64_t NowMicros() {
  268. return target_->NowMicros();
  269. }
  270. void SleepForMicroseconds(int micros) {
  271. target_->SleepForMicroseconds(micros);
  272. }
  273. private:
  274. Env* target_;
  275. };
  276. } // namespace leveldb
  277. #endif // STORAGE_LEVELDB_INCLUDE_ENV_H_