1 //  Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
2 //  This source code is licensed under both the GPLv2 (found in the
3 //  COPYING file in the root directory) and Apache 2.0 License
4 //  (found in the LICENSE.Apache file in the root directory).
5 //
6 // Copyright (c) 2011 The LevelDB Authors. All rights reserved.
7 // Use of this source code is governed by a BSD-style license that can be
8 // found in the LICENSE file. See the AUTHORS file for names of contributors.
9 
10 #pragma once
11 #include <stdint.h>
12 #include <limits>
13 #include <string>
14 #include <utility>
15 #include <vector>
16 
17 #include "db/version_edit.h"
18 #include "rocksdb/flush_block_policy.h"
19 #include "rocksdb/listener.h"
20 #include "rocksdb/options.h"
21 #include "rocksdb/status.h"
22 #include "table/meta_blocks.h"
23 #include "table/table_builder.h"
24 #include "util/compression.h"
25 
26 namespace ROCKSDB_NAMESPACE {
27 
28 class BlockBuilder;
29 class BlockHandle;
30 class WritableFile;
31 struct BlockBasedTableOptions;
32 
33 extern const uint64_t kBlockBasedTableMagicNumber;
34 extern const uint64_t kLegacyBlockBasedTableMagicNumber;
35 
36 class BlockBasedTableBuilder : public TableBuilder {
37  public:
38   // Create a builder that will store the contents of the table it is
39   // building in *file.  Does not close the file.  It is up to the
40   // caller to close the file after calling Finish().
41   BlockBasedTableBuilder(
42       const ImmutableCFOptions& ioptions, const MutableCFOptions& moptions,
43       const BlockBasedTableOptions& table_options,
44       const InternalKeyComparator& internal_comparator,
45       const std::vector<std::unique_ptr<IntTblPropCollectorFactory>>*
46           int_tbl_prop_collector_factories,
47       uint32_t column_family_id, WritableFileWriter* file,
48       const CompressionType compression_type,
49       const uint64_t sample_for_compression,
50       const CompressionOptions& compression_opts, const bool skip_filters,
51       const std::string& column_family_name, const int level_at_creation,
52       const uint64_t creation_time = 0, const uint64_t oldest_key_time = 0,
53       const uint64_t target_file_size = 0,
54       const uint64_t file_creation_time = 0);
55 
56   // No copying allowed
57   BlockBasedTableBuilder(const BlockBasedTableBuilder&) = delete;
58   BlockBasedTableBuilder& operator=(const BlockBasedTableBuilder&) = delete;
59 
60   // REQUIRES: Either Finish() or Abandon() has been called.
61   ~BlockBasedTableBuilder();
62 
63   // Add key,value to the table being constructed.
64   // REQUIRES: key is after any previously added key according to comparator.
65   // REQUIRES: Finish(), Abandon() have not been called
66   void Add(const Slice& key, const Slice& value) override;
67 
68   // Return non-ok iff some error has been detected.
69   Status status() const override;
70 
71   // Finish building the table.  Stops using the file passed to the
72   // constructor after this function returns.
73   // REQUIRES: Finish(), Abandon() have not been called
74   Status Finish() override;
75 
76   // Indicate that the contents of this builder should be abandoned.  Stops
77   // using the file passed to the constructor after this function returns.
78   // If the caller is not going to call Finish(), it must call Abandon()
79   // before destroying this builder.
80   // REQUIRES: Finish(), Abandon() have not been called
81   void Abandon() override;
82 
83   // Number of calls to Add() so far.
84   uint64_t NumEntries() const override;
85 
86   // Size of the file generated so far.  If invoked after a successful
87   // Finish() call, returns the size of the final generated file.
88   uint64_t FileSize() const override;
89 
90   bool NeedCompact() const override;
91 
92   // Get table properties
93   TableProperties GetTableProperties() const override;
94 
95   // Get file checksum
GetFileChecksum()96   const std::string& GetFileChecksum() const override { return file_checksum_; }
97 
98   // Get file checksum function name
99   const char* GetFileChecksumFuncName() const override;
100 
101  private:
ok()102   bool ok() const { return status().ok(); }
103 
104   // Transition state from buffered to unbuffered. See `Rep::State` API comment
105   // for details of the states.
106   // REQUIRES: `rep_->state == kBuffered`
107   void EnterUnbuffered();
108 
109   // Call block's Finish() method
110   // and then write the compressed block contents to file.
111   void WriteBlock(BlockBuilder* block, BlockHandle* handle, bool is_data_block);
112 
113   // Compress and write block content to the file.
114   void WriteBlock(const Slice& block_contents, BlockHandle* handle,
115                   bool is_data_block);
116   // Directly write data to the file.
117   void WriteRawBlock(const Slice& data, CompressionType, BlockHandle* handle,
118                      bool is_data_block = false);
119   Status InsertBlockInCache(const Slice& block_contents,
120                             const CompressionType type,
121                             const BlockHandle* handle);
122 
123   void WriteFilterBlock(MetaIndexBuilder* meta_index_builder);
124   void WriteIndexBlock(MetaIndexBuilder* meta_index_builder,
125                        BlockHandle* index_block_handle);
126   void WritePropertiesBlock(MetaIndexBuilder* meta_index_builder);
127   void WriteCompressionDictBlock(MetaIndexBuilder* meta_index_builder);
128   void WriteRangeDelBlock(MetaIndexBuilder* meta_index_builder);
129   void WriteFooter(BlockHandle& metaindex_block_handle,
130                    BlockHandle& index_block_handle);
131 
132   struct Rep;
133   class BlockBasedTablePropertiesCollectorFactory;
134   class BlockBasedTablePropertiesCollector;
135   Rep* rep_;
136 
137   // Advanced operation: flush any buffered key/value pairs to file.
138   // Can be used to ensure that two adjacent entries never live in
139   // the same data block.  Most clients should not need to use this method.
140   // REQUIRES: Finish(), Abandon() have not been called
141   void Flush();
142 
143   // Some compression libraries fail when the raw size is bigger than int. If
144   // uncompressed size is bigger than kCompressionSizeLimit, don't compress it
145   const uint64_t kCompressionSizeLimit = std::numeric_limits<int>::max();
146 
147   // Store file checksum. If checksum is disabled, its value is "0".
148   std::string file_checksum_ = kUnknownFileChecksum;
149 };
150 
151 Slice CompressBlock(const Slice& raw, const CompressionInfo& info,
152                     CompressionType* type, uint32_t format_version,
153                     bool do_sample, std::string* compressed_output,
154                     std::string* sampled_output_fast,
155                     std::string* sampled_output_slow);
156 
157 }  // namespace ROCKSDB_NAMESPACE
158