1  // Copyright (c) 2011 The LevelDB Authors. All rights reserved.
 2  // Use of this source code is governed by a BSD-style license that can be
 3  // found in the LICENSE file. See the AUTHORS file for names of contributors.
 4  //
 5  // TableBuilder provides the interface used to build a Table
 6  // (an immutable and sorted map from keys to values).
 7  //
 8  // Multiple threads can invoke const methods on a TableBuilder without
 9  // external synchronization, but if any of the threads may call a
10  // non-const method, all threads accessing the same TableBuilder must use
11  // external synchronization.
12  
13  #ifndef STORAGE_LEVELDB_INCLUDE_TABLE_BUILDER_H_
14  #define STORAGE_LEVELDB_INCLUDE_TABLE_BUILDER_H_
15  
16  #include <stdint.h>
17  
18  #include "leveldb/export.h"
19  #include "leveldb/options.h"
20  #include "leveldb/status.h"
21  
22  namespace leveldb {
23  
24  class BlockBuilder;
25  class BlockHandle;
26  class WritableFile;
27  
28  class LEVELDB_EXPORT TableBuilder {
29   public:
30    // Create a builder that will store the contents of the table it is
31    // building in *file.  Does not close the file.  It is up to the
32    // caller to close the file after calling Finish().
33    TableBuilder(const Options& options, WritableFile* file);
34  
35    TableBuilder(const TableBuilder&) = delete;
36    TableBuilder& operator=(const TableBuilder&) = delete;
37  
38    // REQUIRES: Either Finish() or Abandon() has been called.
39    ~TableBuilder();
40  
41    // Change the options used by this builder.  Note: only some of the
42    // option fields can be changed after construction.  If a field is
43    // not allowed to change dynamically and its value in the structure
44    // passed to the constructor is different from its value in the
45    // structure passed to this method, this method will return an error
46    // without changing any fields.
47    Status ChangeOptions(const Options& options);
48  
49    // Add key,value to the table being constructed.
50    // REQUIRES: key is after any previously added key according to comparator.
51    // REQUIRES: Finish(), Abandon() have not been called
52    void Add(const Slice& key, const Slice& value);
53  
54    // Advanced operation: flush any buffered key/value pairs to file.
55    // Can be used to ensure that two adjacent entries never live in
56    // the same data block.  Most clients should not need to use this method.
57    // REQUIRES: Finish(), Abandon() have not been called
58    void Flush();
59  
60    // Return non-ok iff some error has been detected.
61    Status status() const;
62  
63    // Finish building the table.  Stops using the file passed to the
64    // constructor after this function returns.
65    // REQUIRES: Finish(), Abandon() have not been called
66    Status Finish();
67  
68    // Indicate that the contents of this builder should be abandoned.  Stops
69    // using the file passed to the constructor after this function returns.
70    // If the caller is not going to call Finish(), it must call Abandon()
71    // before destroying this builder.
72    // REQUIRES: Finish(), Abandon() have not been called
73    void Abandon();
74  
75    // Number of calls to Add() so far.
76    uint64_t NumEntries() const;
77  
78    // Size of the file generated so far.  If invoked after a successful
79    // Finish() call, returns the size of the final generated file.
80    uint64_t FileSize() const;
81  
82   private:
83    bool ok() const { return status().ok(); }
84    void WriteBlock(BlockBuilder* block, BlockHandle* handle);
85    void WriteRawBlock(const Slice& data, CompressionType, BlockHandle* handle);
86  
87    struct Rep;
88    Rep* rep_;
89  };
90  
91  }  // namespace leveldb
92  
93  #endif  // STORAGE_LEVELDB_INCLUDE_TABLE_BUILDER_H_