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   // Return non-ok iff some error happens during IO.
72   IOStatus io_status() const override;
73 
74   // Finish building the table.  Stops using the file passed to the
75   // constructor after this function returns.
76   // REQUIRES: Finish(), Abandon() have not been called
77   Status Finish() override;
78 
79   // Indicate that the contents of this builder should be abandoned.  Stops
80   // using the file passed to the constructor after this function returns.
81   // If the caller is not going to call Finish(), it must call Abandon()
82   // before destroying this builder.
83   // REQUIRES: Finish(), Abandon() have not been called
84   void Abandon() override;
85 
86   // Number of calls to Add() so far.
87   uint64_t NumEntries() const override;
88 
89   // Size of the file generated so far.  If invoked after a successful
90   // Finish() call, returns the size of the final generated file.
91   uint64_t FileSize() const override;
92 
93   bool NeedCompact() const override;
94 
95   // Get table properties
96   TableProperties GetTableProperties() const override;
97 
98   // Get file checksum
99   std::string GetFileChecksum() const override;
100 
101   // Get file checksum function name
102   const char* GetFileChecksumFuncName() const override;
103 
104  private:
ok()105   bool ok() const { return status().ok(); }
106 
107   // Transition state from buffered to unbuffered. See `Rep::State` API comment
108   // for details of the states.
109   // REQUIRES: `rep_->state == kBuffered`
110   void EnterUnbuffered();
111 
112   // Call block's Finish() method
113   // and then write the compressed block contents to file.
114   void WriteBlock(BlockBuilder* block, BlockHandle* handle, bool is_data_block);
115 
116   // Compress and write block content to the file.
117   void WriteBlock(const Slice& block_contents, BlockHandle* handle,
118                   bool is_data_block);
119   // Directly write data to the file.
120   void WriteRawBlock(const Slice& data, CompressionType, BlockHandle* handle,
121                      bool is_data_block = false);
122   Status InsertBlockInCache(const Slice& block_contents,
123                             const CompressionType type,
124                             const BlockHandle* handle);
125 
126   void WriteFilterBlock(MetaIndexBuilder* meta_index_builder);
127   void WriteIndexBlock(MetaIndexBuilder* meta_index_builder,
128                        BlockHandle* index_block_handle);
129   void WritePropertiesBlock(MetaIndexBuilder* meta_index_builder);
130   void WriteCompressionDictBlock(MetaIndexBuilder* meta_index_builder);
131   void WriteRangeDelBlock(MetaIndexBuilder* meta_index_builder);
132   void WriteFooter(BlockHandle& metaindex_block_handle,
133                    BlockHandle& index_block_handle);
134 
135   struct Rep;
136   class BlockBasedTablePropertiesCollectorFactory;
137   class BlockBasedTablePropertiesCollector;
138   Rep* rep_;
139 
140   // Advanced operation: flush any buffered key/value pairs to file.
141   // Can be used to ensure that two adjacent entries never live in
142   // the same data block.  Most clients should not need to use this method.
143   // REQUIRES: Finish(), Abandon() have not been called
144   void Flush();
145 
146   // Some compression libraries fail when the raw size is bigger than int. If
147   // uncompressed size is bigger than kCompressionSizeLimit, don't compress it
148   const uint64_t kCompressionSizeLimit = std::numeric_limits<int>::max();
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