From 38a06aa2254ed363762c9f735df3638eb22b73b2 Mon Sep 17 00:00:00 2001 From: Siying Dong Date: Thu, 23 May 2019 16:22:13 -0700 Subject: [PATCH] Improve comments of classes for PlainTable (#5339) Summary: Simply add some comments. Pull Request resolved: https://github.com/facebook/rocksdb/pull/5339 Differential Revision: D15485315 Pulled By: siying fbshipit-source-id: 4594b1c4c967e6bd08aa7fa08a37df3481df1938 --- table/plain_table_builder.h | 3 +++ table/plain_table_factory.h | 14 +++++++++++++- table/plain_table_index.h | 26 ++++++++++++++++++++++++-- table/plain_table_key_coding.h | 15 ++++++++++++--- table/plain_table_reader.h | 13 +++++++------ 5 files changed, 59 insertions(+), 12 deletions(-) diff --git a/table/plain_table_builder.h b/table/plain_table_builder.h index ca0879a4e..9a5b44b9c 100644 --- a/table/plain_table_builder.h +++ b/table/plain_table_builder.h @@ -24,6 +24,9 @@ class BlockHandle; class WritableFile; class TableBuilder; +// The builder class of PlainTable. For description of PlainTable format +// See comments of class PlainTableFactory, where instances of +// PlainTableReader are created. class PlainTableBuilder: public TableBuilder { public: // Create a builder that will store the contents of the table it is diff --git a/table/plain_table_factory.h b/table/plain_table_factory.h index dade15660..1bd155f93 100644 --- a/table/plain_table_factory.h +++ b/table/plain_table_factory.h @@ -24,7 +24,19 @@ class WritableFile; class Table; class TableBuilder; -// IndexedTable requires fixed length key, configured as a constructor +// PlainTableFactory is the entrance function to the PlainTable format of +// SST files. It returns instances PlainTableBuilder as the builder +// class and PlainTableReader as the reader class, where the format is +// actually implemented. +// +// The PlainTable is designed for memory-mapped file systems, e.g. tmpfs. +// Data is not organized in blocks, which allows fast access. Because of +// following downsides +// 1. Data compression is not supported. +// 2. Data is not checksumed. +// it is not recommended to use this format on other type of file systems. +// +// PlainTable requires fixed length key, configured as a constructor // parameter of the factory class. Output file format: // +-------------+-----------------+ // | version | user_key_length | diff --git a/table/plain_table_index.h b/table/plain_table_index.h index 360d99827..1457fd00d 100644 --- a/table/plain_table_index.h +++ b/table/plain_table_index.h @@ -20,6 +20,12 @@ namespace rocksdb { +// The file contains two classes PlainTableIndex and PlainTableIndexBuilder +// The two classes implement the index format of PlainTable. +// For descripton of PlainTable format, see comments of class +// PlainTableFactory +// +// // PlainTableIndex contains buckets size of index_size_, each is a // 32-bit integer. The lower 31 bits contain an offset value (explained below) // and the first bit of the integer indicates type of the offset. @@ -55,6 +61,10 @@ namespace rocksdb { // .... // record N file offset: fixedint32 // + +// The class loads the index block from a PlainTable SST file, and executes +// the index lookup. +// The class is used by PlainTableReader class. class PlainTableIndex { public: enum IndexSearchResult { @@ -72,11 +82,22 @@ class PlainTableIndex { index_(nullptr), sub_index_(nullptr) {} + // The function that executes the lookup the hash table. + // The hash key is `prefix_hash`. The function fills the hash bucket + // content in `bucket_value`, which is up to the caller to interpret. IndexSearchResult GetOffset(uint32_t prefix_hash, uint32_t* bucket_value) const; - Status InitFromRawData(Slice data); + // Initialize data from `index_data`, which points to raw data for + // index stored in the SST file. + Status InitFromRawData(Slice index_data); + // Decode the sub index for specific hash bucket. + // The `offset` is the value returned as `bucket_value` by GetOffset() + // and is only valid when the return value is `kSubindex`. + // The return value is the pointer to the starting address of the + // sub-index. `upper_bound` is filled with the value indicating how many + // entries the sub-index has. const char* GetSubIndexBasePtrAndUpperBound(uint32_t offset, uint32_t* upper_bound) const { const char* index_ptr = &sub_index_[offset]; @@ -106,9 +127,10 @@ class PlainTableIndex { // After calling Finish(), it returns Slice, which is usually // used either to initialize PlainTableIndex or // to save index to sst file. -// For more details about the index, please refer to: +// For more details about the index, please refer to: // https://github.com/facebook/rocksdb/wiki/PlainTable-Format // #wiki-in-memory-index-format +// The class is used by PlainTableBuilder class. class PlainTableIndexBuilder { public: PlainTableIndexBuilder(Arena* arena, const ImmutableCFOptions& ioptions, diff --git a/table/plain_table_key_coding.h b/table/plain_table_key_coding.h index 9a27ad06b..93f8f7af4 100644 --- a/table/plain_table_key_coding.h +++ b/table/plain_table_key_coding.h @@ -11,6 +11,11 @@ #include "db/dbformat.h" #include "table/plain_table_reader.h" +// The file contains three helper classes of PlainTable format, +// PlainTableKeyEncoder, PlainTableKeyDecoder and PlainTableFileReader. +// These classes issue the lowest level of operations of PlainTable. +// Actual data format of the key is documented in comments of class +// PlainTableFactory. namespace rocksdb { class WritableFile; @@ -18,8 +23,8 @@ struct ParsedInternalKey; struct PlainTableReaderFileInfo; enum PlainTableEntryType : unsigned char; -// Helper class to write out a key to an output file -// Actual data format of the key is documented in plain_table_factory.h +// Helper class for PlainTable format to write out a key to an output file +// The class is used in PlainTableBuilder. class PlainTableKeyEncoder { public: explicit PlainTableKeyEncoder(EncodingType encoding_type, @@ -53,6 +58,10 @@ class PlainTableKeyEncoder { IterKey pre_prefix_; }; +// The class does raw file reads for PlainTableReader. +// It hides whether it is a mmap-read, or a non-mmap read. +// The class is implemented in a way to favor the performance of mmap case. +// The class is used by PlainTableReader. class PlainTableFileReader { public: explicit PlainTableFileReader(const PlainTableReaderFileInfo* _file_info) @@ -122,7 +131,7 @@ class PlainTableFileReader { }; // A helper class to decode keys from input buffer -// Actual data format of the key is documented in plain_table_factory.h +// The class is used by PlainTableBuilder. class PlainTableKeyDecoder { public: explicit PlainTableKeyDecoder(const PlainTableReaderFileInfo* file_info, diff --git a/table/plain_table_reader.h b/table/plain_table_reader.h index 14760f20a..12b22aaf1 100644 --- a/table/plain_table_reader.h +++ b/table/plain_table_reader.h @@ -56,16 +56,17 @@ struct PlainTableReaderFileInfo { file(std::move(_file)) {} }; +// The reader class of PlainTable. For description of PlainTable format +// See comments of class PlainTableFactory, where instances of +// PlainTableReader are created. +class PlainTableReader: public TableReader { + public: // Based on following output file format shown in plain_table_factory.h -// When opening the output file, IndexedTableReader creates a hash table -// from key prefixes to offset of the output file. IndexedTable will decide +// When opening the output file, PlainTableReader creates a hash table +// from key prefixes to offset of the output file. PlainTable will decide // whether it points to the data offset of the first key with the key prefix // or the offset of it. If there are too many keys share this prefix, it will // create a binary search-able index from the suffix to offset on disk. -// -// The implementation of IndexedTableReader requires output file is mmaped -class PlainTableReader: public TableReader { - public: static Status Open(const ImmutableCFOptions& ioptions, const EnvOptions& env_options, const InternalKeyComparator& internal_comparator,