// Copyright (c) 2011 The LevelDB Authors. All rights reserved.

// Use of this source code is governed by a BSD-style license that can be

// found in the LICENSE file. See the AUTHORS file for names of contributors.

//

// An Env is an interface used by the leveldb implementation to access

// operating system functionality like the filesystem etc.  Callers

// may wish to provide a custom Env object when opening a database to

// get fine gain control; e.g., to rate limit file system operations.

//

// All Env implementations are safe for concurrent access from

// multiple threads without any external synchronization.

#ifndef STORAGE_LEVELDB_INCLUDE_ENV_H_

#define STORAGE_LEVELDB_INCLUDE_ENV_H_

#include <stdarg.h>

#include <stdint.h>

#include <string>

#include <vector>

#include "leveldb/export.h"

#include "leveldb/status.h"

#if defined(_WIN32)

// The leveldb::Env class below contains a DeleteFile method.

// At the same time, <windows.h>, a fairly popular header

// file for Windows applications, defines a DeleteFile macro.

//

// Without any intervention on our part, the result of this

// unfortunate coincidence is that the name of the

// leveldb::Env::DeleteFile method seen by the compiler depends on

// whether <windows.h> was included before or after the LevelDB

// headers.

//

// To avoid headaches, we undefined DeleteFile (if defined) and

// redefine it at the bottom of this file. This way <windows.h>

// can be included before this file (or not at all) and the

// exported method will always be leveldb::Env::DeleteFile.

#if defined(DeleteFile)

#undef DeleteFile

#define LEVELDB_DELETEFILE_UNDEFINED

#endif  // defined(DeleteFile)

#endif  // defined(_WIN32)

namespace leveldb {

class FileLock;

class Logger;

class RandomAccessFile;

class SequentialFile;

class Slice;

class WritableFile;

class LEVELDB_EXPORT Env {

 public:

  Env() = default;

  Env(const Env&) = delete;

  Env& operator=(const Env&) = delete;

  virtual ~Env();

  // Return a default environment suitable for the current operating

  // system.  Sophisticated users may wish to provide their own Env

  // implementation instead of relying on this default environment.

  //

  // The result of Default() belongs to leveldb and must never be deleted.

  static Env* Default();

  // Create an object that sequentially reads the file with the specified name.

  // On success, stores a pointer to the new file in *result and returns OK.

  // On failure stores nullptr in *result and returns non-OK.  If the file does

  // not exist, returns a non-OK status.  Implementations should return a

  // NotFound status when the file does not exist.

  //

  // The returned file will only be accessed by one thread at a time.

  virtual Status NewSequentialFile(const std::string& fname,

                                   SequentialFile** result) = 0;

  // Create an object supporting random-access reads from the file with the

  // specified name.  On success, stores a pointer to the new file in

  // *result and returns OK.  On failure stores nullptr in *result and

  // returns non-OK.  If the file does not exist, returns a non-OK

  // status.  Implementations should return a NotFound status when the file does

  // not exist.

  //

  // The returned file may be concurrently accessed by multiple threads.

  virtual Status NewRandomAccessFile(const std::string& fname,

                                     RandomAccessFile** result) = 0;

  // Create an object that writes to a new file with the specified

  // name.  Deletes any existing file with the same name and creates a

  // new file.  On success, stores a pointer to the new file in

  // *result and returns OK.  On failure stores nullptr in *result and

  // returns non-OK.

  //

  // The returned file will only be accessed by one thread at a time.

  virtual Status NewWritableFile(const std::string& fname,

                                 WritableFile** result) = 0;

  // Create an object that either appends to an existing file, or

  // writes to a new file (if the file does not exist to begin with).

  // On success, stores a pointer to the new file in *result and

  // returns OK.  On failure stores nullptr in *result and returns

  // non-OK.

  //

  // The returned file will only be accessed by one thread at a time.

  //

  // May return an IsNotSupportedError error if this Env does

  // not allow appending to an existing file.  Users of Env (including

  // the leveldb implementation) must be prepared to deal with

  // an Env that does not support appending.

  virtual Status NewAppendableFile(const std::string& fname,

                                   WritableFile** result);

  // Returns true iff the named file exists.

  virtual bool FileExists(const std::string& fname) = 0;

  // Store in *result the names of the children of the specified directory.

  // The names are relative to "dir".

  // Original contents of *results are dropped.

  virtual Status GetChildren(const std::string& dir,

                             std::vector<std::string>* result) = 0;

  // Delete the named file.

  virtual Status DeleteFile(const std::string& fname) = 0;

  // Create the specified directory.

  virtual Status CreateDir(const std::string& dirname) = 0;

  // Delete the specified directory.

  virtual Status DeleteDir(const std::string& dirname) = 0;

  // Store the size of fname in *file_size.

  virtual Status GetFileSize(const std::string& fname, uint64_t* file_size) = 0;

  // Rename file src to target.

  virtual Status RenameFile(const std::string& src,

                            const std::string& target) = 0;

  // Lock the specified file.  Used to prevent concurrent access to

  // the same db by multiple processes.  On failure, stores nullptr in

  // *lock and returns non-OK.

  //

  // On success, stores a pointer to the object that represents the

  // acquired lock in *lock and returns OK.  The caller should call

  // UnlockFile(*lock) to release the lock.  If the process exits,

  // the lock will be automatically released.

  //

  // If somebody else already holds the lock, finishes immediately

  // with a failure.  I.e., this call does not wait for existing locks

  // to go away.

  //

  // May create the named file if it does not already exist.

  virtual Status LockFile(const std::string& fname, FileLock** lock) = 0;

  // Release the lock acquired by a previous successful call to LockFile.

  // REQUIRES: lock was returned by a successful LockFile() call

  // REQUIRES: lock has not already been unlocked.

  virtual Status UnlockFile(FileLock* lock) = 0;

  // Arrange to run "(*function)(arg)" once in a background thread.

  //

  // "function" may run in an unspecified thread.  Multiple functions

  // added to the same Env may run concurrently in different threads.

  // I.e., the caller may not assume that background work items are

  // serialized.

  virtual void Schedule(void (*function)(void* arg), void* arg) = 0;

  // Start a new thread, invoking "function(arg)" within the new thread.

  // When "function(arg)" returns, the thread will be destroyed.

  virtual void StartThread(void (*function)(void* arg), void* arg) = 0;

  // *path is set to a temporary directory that can be used for testing. It may

  // or may not have just been created. The directory may or may not differ

  // between runs of the same process, but subsequent calls will return the

  // same directory.

  virtual Status GetTestDirectory(std::string* path) = 0;

  // Create and return a log file for storing informational messages.

  virtual Status NewLogger(const std::string& fname, Logger** result) = 0;

  // Returns the number of micro-seconds since some fixed point in time. Only

  // useful for computing deltas of time.

  virtual uint64_t NowMicros() = 0;

  // Sleep/delay the thread for the prescribed number of micro-seconds.

  virtual void SleepForMicroseconds(int micros) = 0;

};

// A file abstraction for reading sequentially through a file

class LEVELDB_EXPORT SequentialFile {

 public:

  SequentialFile() = default;

  SequentialFile(const SequentialFile&) = delete;

  SequentialFile& operator=(const SequentialFile&) = delete;

  virtual ~SequentialFile();

  // Read up to "n" bytes from the file.  "scratch[0..n-1]" may be

  // written by this routine.  Sets "*result" to the data that was

  // read (including if fewer than "n" bytes were successfully read).

  // May set "*result" to point at data in "scratch[0..n-1]", so

  // "scratch[0..n-1]" must be live when "*result" is used.

  // If an error was encountered, returns a non-OK status.

  //

  // REQUIRES: External synchronization

  virtual Status Read(size_t n, Slice* result, char* scratch) = 0;

  // Skip "n" bytes from the file. This is guaranteed to be no

  // slower that reading the same data, but may be faster.

  //

  // If end of file is reached, skipping will stop at the end of the

  // file, and Skip will return OK.

  //

  // REQUIRES: External synchronization

  virtual Status Skip(uint64_t n) = 0;

  // Get a name for the file, only for error reporting

  virtual std::string GetName() const = 0;

};

// A file abstraction for randomly reading the contents of a file.

class LEVELDB_EXPORT RandomAccessFile {

 public:

  RandomAccessFile() = default;

  RandomAccessFile(const RandomAccessFile&) = delete;

  RandomAccessFile& operator=(const RandomAccessFile&) = delete;

  virtual ~RandomAccessFile();

  // Read up to "n" bytes from the file starting at "offset".

  // "scratch[0..n-1]" may be written by this routine.  Sets "*result"

  // to the data that was read (including if fewer than "n" bytes were

  // successfully read).  May set "*result" to point at data in

  // "scratch[0..n-1]", so "scratch[0..n-1]" must be live when

  // "*result" is used.  If an error was encountered, returns a non-OK

  // status.

  //

  // Safe for concurrent use by multiple threads.

  virtual Status Read(uint64_t offset, size_t n, Slice* result,

                      char* scratch) const = 0;

  // Get a name for the file, only for error reporting

  virtual std::string GetName() const = 0;

};

// A file abstraction for sequential writing.  The implementation

// must provide buffering since callers may append small fragments

// at a time to the file.

class LEVELDB_EXPORT WritableFile {

 public:

  WritableFile() = default;

  WritableFile(const WritableFile&) = delete;

  WritableFile& operator=(const WritableFile&) = delete;

  virtual ~WritableFile();

  virtual Status Append(const Slice& data) = 0;

  virtual Status Close() = 0;

  virtual Status Flush() = 0;

  virtual Status Sync() = 0;

  // Get a name for the file, only for error reporting

  virtual std::string GetName() const = 0;

};

// An interface for writing log messages.

class LEVELDB_EXPORT Logger {

 public:

  Logger() = default;

  Logger(const Logger&) = delete;

  Logger& operator=(const Logger&) = delete;

  virtual ~Logger();

  // Write an entry to the log file with the specified format.

  virtual void Logv(const char* format, va_list ap) = 0;

};

// Identifies a locked file.

class LEVELDB_EXPORT FileLock {

 public:

  FileLock() = default;

  FileLock(const FileLock&) = delete;

  FileLock& operator=(const FileLock&) = delete;

  virtual ~FileLock();

};

// Log the specified data to *info_log if info_log is non-null.

void Log(Logger* info_log, const char* format, ...)

#if defined(__GNUC__) || defined(__clang__)

    __attribute__((__format__(__printf__, 2, 3)))

#endif

    ;

// A utility routine: write "data" to the named file.

LEVELDB_EXPORT Status WriteStringToFile(Env* env, const Slice& data,

                                        const std::string& fname);

// A utility routine: read contents of named file into *data

LEVELDB_EXPORT Status ReadFileToString(Env* env, const std::string& fname,

                                       std::string* data);

// An implementation of Env that forwards all calls to another Env.

// May be useful to clients who wish to override just part of the

// functionality of another Env.

class LEVELDB_EXPORT EnvWrapper : public Env {

 public:

  // Initialize an EnvWrapper that delegates all calls to *t.

  explicit EnvWrapper(Env* t) : target_(t) {}

  virtual ~EnvWrapper();

  // Return the target to which this Env forwards all calls.

  Env* target() const { return target_; }

  // The following text is boilerplate that forwards all methods to target().

  Status NewSequentialFile(const std::string& f, SequentialFile** r) override {

    return target_->NewSequentialFile(f, r);

  }

  Status NewRandomAccessFile(const std::string& f,

                             RandomAccessFile** r) override {

    return target_->NewRandomAccessFile(f, r);

  }

  Status NewWritableFile(const std::string& f, WritableFile** r) override {

    return target_->NewWritableFile(f, r);

  }

  Status NewAppendableFile(const std::string& f, WritableFile** r) override {

    return target_->NewAppendableFile(f, r);

  }

  bool FileExists(const std::string& f) override {

    return target_->FileExists(f);

  }

  Status GetChildren(const std::string& dir,

                     std::vector<std::string>* r) override {

    return target_->GetChildren(dir, r);

  }

  Status DeleteFile(const std::string& f) override {

    return target_->DeleteFile(f);

  }

  Status CreateDir(const std::string& d) override {

    return target_->CreateDir(d);

  }

  Status DeleteDir(const std::string& d) override {

    return target_->DeleteDir(d);

  }

  Status GetFileSize(const std::string& f, uint64_t* s) override {

    return target_->GetFileSize(f, s);

  }

  Status RenameFile(const std::string& s, const std::string& t) override {

    return target_->RenameFile(s, t);

  }

  Status LockFile(const std::string& f, FileLock** l) override {

    return target_->LockFile(f, l);

  }

  Status UnlockFile(FileLock* l) override { return target_->UnlockFile(l); }

  void Schedule(void (*f)(void*), void* a) override {

    return target_->Schedule(f, a);

  }

  void StartThread(void (*f)(void*), void* a) override {

    return target_->StartThread(f, a);

  }

  Status GetTestDirectory(std::string* path) override {

    return target_->GetTestDirectory(path);

  }

  Status NewLogger(const std::string& fname, Logger** result) override {

    return target_->NewLogger(fname, result);

  }

  uint64_t NowMicros() override { return target_->NowMicros(); }

  void SleepForMicroseconds(int micros) override {

    target_->SleepForMicroseconds(micros);

  }

 private:

  Env* target_;

};

}  // namespace leveldb

// Redefine DeleteFile if necessary.

#if defined(_WIN32) && defined(LEVELDB_DELETEFILE_UNDEFINED)

#if defined(UNICODE)

#define DeleteFile DeleteFileW

#else

#define DeleteFile DeleteFileA

#endif  // defined(UNICODE)

#endif  // defined(_WIN32) && defined(LEVELDB_DELETEFILE_UNDEFINED)

#endif  // STORAGE_LEVELDB_INCLUDE_ENV_H_