【leveldb】Options、ReadOptions、WriteOptions（三）

• Options：主要用于控制DB的一些操作。
• ReadOptions：用于控制读操作属性。
• WriteOptions：用于控制写操作属性。

一、Options

// Options to control the behavior of a database (passed to DB::Open)
 <!用于控制DB的一些特性>
struct LEVELDB_EXPORT Options {
  // Create an Options object with default values for all fields.
  Options();

  // -------------------
  // Parameters that affect behavior

  // Comparator used to define the order of keys in the table.
  // Default: a comparator that uses lexicographic byte-wise ordering
  //
  // REQUIRES: The client must ensure that the comparator supplied
  // here has the same name and orders keys *exactly* the same as the
  // comparator provided to previous open calls on the same DB.
  <!key的排序方式，默认使用字典字节序排序，\
  一个数据库的排序方式确定之后不要再改变>
  const Comparator* comparator;

  // If true, the database will be created if it is missing.
  <!如果是true，数据库打开时，若数据库丢失会重新创建一份>
  bool create_if_missing = false;

  // If true, an error is raised if the database already exists.
  <!如果是true，数据库打开时如果存在则报错。>
  bool error_if_exists = false;

  // If true, the implementation will do aggressive checking of the
  // data it is processing and will stop early if it detects any
  // errors.  This may have unforeseen ramifications: for example, a
  // corruption of one DB entry may cause a large number of entries to
  // become unreadable or for the entire DB to become unopenable.
  <!如果为true，在数据处理过程中会严格检查数据，检查到任何错误都会提前停止，\
    这可能会到来无法预料的后果，例如一个条目的损害可能导致大量的条目无法读取\
    或者整个数据库无法打开了，所以这里应该是建议false>
  bool paranoid_checks = false;

  // Use the specified object to interact with the environment,
  // e.g. to read/write files, schedule background work, etc.
  // Default: Env::Default()
  <!使用指定的对象与环境交互，比如读写文件，安排后台工作等\
    默认使用Env默认值。一些复杂的操作用户可自己指定而不依赖于默认环境。>
  Env* env;

  // Any internal progress/error information generated by the db will
  // be written to info_log if it is non-null, or to a file stored
  // in the same directory as the DB contents if info_log is null.
  <!如果日志不为空，则将db产生的处理和错误日志写与指定文件，
    如果为空，则在同一目录下创建一个文件作为db内容写入>
  Logger* info_log = nullptr;

  // -------------------
  // Parameters that affect performance

  // Amount of data to build up in memory (backed by an unsorted log
  // on disk) before converting to a sorted on-disk file.
  //
  // Larger values increase performance, especially during bulk loads.
  // Up to two write buffers may be held in memory at the same time,
  // so you may wish to adjust this parameter to control memory usage.
  // Also, a larger write buffer will result in a longer recovery time
  // the next time the database is opened.
  <!这个大小应该是memtable和immutable大小。
    在大容量负载期间，增大这个值可以提升性能，
    最多可保持两份写缓冲区在内存中，通过调节此值
    可控制内存使用大小，唯一不好的是如果写缓冲区太大，
    下次打开数据库时会耗时更久。>
  size_t write_buffer_size = 4 * 1024 * 1024;

  // Number of open files that can be used by the DB.  You may need to
  // increase this if your database has a large working set (budget
  // one open file per 2MB of working set).
  <!DB可打开的最大文件数，如果系统工作集很大，可考虑增大此值，\
    每个打开的文件大概会占用2MB的工作集大小>
  int max_open_files = 1000;

  // Control over blocks (user data is stored in a set of blocks, and
  // a block is the unit of reading from disk).

  // If non-null, use the specified cache for blocks.
  // If null, leveldb will automatically create and use an 8MB internal cache.
  <!block是DB的控制块，是与磁盘交互的最小单元，用户数据存储在这个控制块中。
    用户可指定一个cache，如果不指定，系统默认创建一个8MB的内部cache>
  Cache* block_cache = nullptr;

  // Approximate size of user data packed per block.  Note that the
  // block size specified here corresponds to uncompressed data.  The
  // actual size of the unit read from disk may be smaller if
  // compression is enabled.  This parameter can be changed dynamically.
  <!每个block块的大小，这里指的是为压缩数据大小。如果开启了数据压缩，
    则一个从磁盘读取的块大小可能是小于未压缩之前大小的。此参数可动态改变>
  size_t block_size = 4 * 1024;

  // Number of keys between restart points for delta encoding of keys.
  // This parameter can be changed dynamically.  Most clients should
  // leave this parameter alone.
  <!block重启点之间的key的个数，至于什么是重启点可参考（leveldb 二）中的说明>
  int block_restart_interval = 16;

  // Leveldb will write up to this amount of bytes to a file before
  // switching to a new one.
  // Most clients should leave this parameter alone.  However if your
  // filesystem is more efficient with larger files, you could
  // consider increasing the value.  The downside will be longer
  // compactions and hence longer latency/performance hiccups.
  // Another reason to increase this parameter might be when you are
  // initially populating a large database.
  <!落地磁盘文件最大大小，超过此大小重新一个新文件写。
    若文件系统在大文件方面表现好，可增大此值。值的增大会带来以下问题：
    1、更长的压缩耗时，2、更长的性能中断。增大此值的一个原因可能是
    一开始就要填充一个大的数据库>
  size_t max_file_size = 2 * 1024 * 1024;

  // Compress blocks using the specified compression algorithm.  This
  // parameter can be changed dynamically.
  //
  // Default: kSnappyCompression, which gives lightweight but fast
  // compression.
  //
  // Typical speeds of kSnappyCompression on an Intel(R) Core(TM)2 2.4GHz:
  //    ~200-500MB/s compression
  //    ~400-800MB/s decompression
  // Note that these speeds are significantly faster than most
  // persistent storage speeds, and therefore it is typically never
  // worth switching to kNoCompression.  Even if the input data is
  // incompressible, the kSnappyCompression implementation will
  // efficiently detect that and will switch to uncompressed mode.
  <!压缩block的方式。压缩速率指标如上，作者是是建议压缩的，即使输入数据不可压缩
    压缩算法也可以自己检测出来而切换到不压缩模式>
  CompressionType compression = kSnappyCompression;

  // EXPERIMENTAL: If true, append to existing MANIFEST and log files
  // when a database is opened.  This can significantly speed up open.
  //
  // Default: currently false, but may become true later.
  <!如果为true，直接使用文件追加的方式，可使打开DB更快，
    作者默认默认false>
  bool reuse_logs = false;

  // If non-null, use the specified filter policy to reduce disk reads.
  // Many applications will benefit from passing the result of
  // NewBloomFilterPolicy() here.
  <!指定过滤策略来减少磁盘的读取，作者推荐使用NewBloomFilterPolicy（）>
  const FilterPolicy* filter_policy = nullptr;
};

二、ReadOptions

控制读方式选项

// Options that control read operations
struct LEVELDB_EXPORT ReadOptions {
  ReadOptions() = default;

  // If true, all data read from underlying storage will be
  // verified against corresponding checksums.
  <!如果为ture，所有读取数据都会校验>
  bool verify_checksums = false;

  // Should the data read for this iteration be cached in memory?
  // Callers may wish to set this field to false for bulk scans.
  <!从迭代器读取的数据是否要缓存在内存中，
    数据批量扫描可能希望为false>
  bool fill_cache = true;

  // If "snapshot" is non-null, read as of the supplied snapshot
  // (which must belong to the DB that is being read and which must
  // not have been released).  If "snapshot" is null, use an implicit
  // snapshot of the state at the beginning of this read operation.
  <!快照，有快照就读取快照数据，没快照就正常读取>
  const Snapshot* snapshot = nullptr;
};

三、WriteOptions

// Options that control write operations
struct LEVELDB_EXPORT WriteOptions {
  WriteOptions() = default;

  // If true, the write will be flushed from the operating system
  // buffer cache (by calling WritableFile::Sync()) before the write
  // is considered complete.  If this flag is true, writes will be
  // slower.
  //
  // If this flag is false, and the machine crashes, some recent
  // writes may be lost.  Note that if it is just the process that
  // crashes (i.e., the machine does not reboot), no writes will be
  // lost even if sync==false.
  //
  // In other words, a DB write with sync==false has similar
  // crash semantics as the "write()" system call.  A DB write
  // with sync==true has similar crash semantics to a "write()"
  // system call followed by "fsync()".
  <!是否写同步，同步写是忙于异步写的，但不会造成数据丢失，
    如果是异步写，只有在机器重启的情况下才会造成数据丢失，
    其它情况这不会丢失>
  bool sync = false;
};