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#include "leveldb/options.h"
18#include "leveldb/status.h"
19
20namespace leveldb {
21
22class BlockBuilder;
23class BlockHandle;
24class WritableFile;
25
26class TableBuilder {
27 public:
28  // Create a builder that will store the contents of the table it is
29  // building in *file.  Does not close the file.  It is up to the
30  // caller to close the file after calling Finish().
31  TableBuilder(const Options& options, WritableFile* file);
32
33  // REQUIRES: Either Finish() or Abandon() has been called.
34  ~TableBuilder();
35
36  // Change the options used by this builder.  Note: only some of the
37  // option fields can be changed after construction.  If a field is
38  // not allowed to change dynamically and its value in the structure
39  // passed to the constructor is different from its value in the
40  // structure passed to this method, this method will return an error
41  // without changing any fields.
42  Status ChangeOptions(const Options& options);
43
44  // Add key,value to the table being constructed.
45  // REQUIRES: key is after any previously added key according to comparator.
46  // REQUIRES: Finish(), Abandon() have not been called
47  void Add(const Slice& key, const Slice& value);
48
49  // Advanced operation: flush any buffered key/value pairs to file.
50  // Can be used to ensure that two adjacent entries never live in
51  // the same data block.  Most clients should not need to use this method.
52  // REQUIRES: Finish(), Abandon() have not been called
53  void Flush();
54
55  // Return non-ok iff some error has been detected.
56  Status status() const;
57
58  // Finish building the table.  Stops using the file passed to the
59  // constructor after this function returns.
60  // REQUIRES: Finish(), Abandon() have not been called
61  Status Finish();
62
63  // Indicate that the contents of this builder should be abandoned.  Stops
64  // using the file passed to the constructor after this function returns.
65  // If the caller is not going to call Finish(), it must call Abandon()
66  // before destroying this builder.
67  // REQUIRES: Finish(), Abandon() have not been called
68  void Abandon();
69
70  // Number of calls to Add() so far.
71  uint64_t NumEntries() const;
72
73  // Size of the file generated so far.  If invoked after a successful
74  // Finish() call, returns the size of the final generated file.
75  uint64_t FileSize() const;
76
77 private:
78  bool ok() const { return status().ok(); }
79  void WriteBlock(BlockBuilder* block, BlockHandle* handle);
80  void WriteRawBlock(const Slice& data, CompressionType, BlockHandle* handle);
81
82  struct Rep;
83  Rep* rep_;
84
85  // No copying allowed
86  TableBuilder(const TableBuilder&);
87  void operator=(const TableBuilder&);
88};
89
90}  // namespace leveldb
91
92#endif  // STORAGE_LEVELDB_INCLUDE_TABLE_BUILDER_H_
93