2 Copyright 2020 Google LLC
4 Use of this source code is governed by a BSD-style
5 license that can be found in the LICENSE file or at
6 https://developers.google.com/open-source/licenses/bsd
9 #ifndef REFTABLE_WRITER_H
10 #define REFTABLE_WRITER_H
12 #include "reftable-record.h"
15 #include <unistd.h> /* ssize_t */
17 /* Writing single reftables */
19 /* reftable_write_options sets options for writing a single reftable. */
20 struct reftable_write_options
{
21 /* boolean: do not pad out blocks to block size. */
22 unsigned unpadded
: 1;
24 /* the blocksize. Should be less than 2^24. */
27 /* boolean: do not generate a SHA1 => ref index. */
28 unsigned skip_index_objects
: 1;
30 /* how often to write complete keys in each block. */
33 /* 4-byte identifier ("sha1", "s256") of the hash.
34 * Defaults to SHA1 if unset
38 /* boolean: do not check ref names for validity or dir/file conflicts.
40 unsigned skip_name_check
: 1;
42 /* boolean: copy log messages exactly. If unset, check that the message
43 * is a single line, and add '\n' if missing.
45 unsigned exact_log_message
: 1;
48 /* reftable_block_stats holds statistics for a single block type */
49 struct reftable_block_stats
{
50 /* total number of entries written */
52 /* total number of key restarts */
54 /* total number of blocks */
56 /* total number of index blocks */
58 /* depth of the index */
61 /* offset of the first block for this type */
63 /* offset of the top level index block for this type, or 0 if not
65 uint64_t index_offset
;
68 /* stats holds overall statistics for a single reftable */
69 struct reftable_stats
{
70 /* total number of blocks written. */
72 /* stats for ref data */
73 struct reftable_block_stats ref_stats
;
74 /* stats for the SHA1 to ref map. */
75 struct reftable_block_stats obj_stats
;
76 /* stats for index blocks */
77 struct reftable_block_stats idx_stats
;
78 /* stats for log blocks */
79 struct reftable_block_stats log_stats
;
81 /* disambiguation length of shortened object IDs. */
85 /* reftable_new_writer creates a new writer */
86 struct reftable_writer
*
87 reftable_new_writer(ssize_t (*writer_func
)(void *, const void *, size_t),
88 void *writer_arg
, struct reftable_write_options
*opts
);
90 /* Set the range of update indices for the records we will add. When writing a
91 table into a stack, the min should be at least
92 reftable_stack_next_update_index(), or REFTABLE_API_ERROR is returned.
94 For transactional updates to a stack, typically min==max, and the
95 update_index can be obtained by inspeciting the stack. When converting an
96 existing ref database into a single reftable, this would be a range of
97 update-index timestamps.
99 void reftable_writer_set_limits(struct reftable_writer
*w
, uint64_t min
,
103 Add a reftable_ref_record. The record should have names that come after
104 already added records.
106 The update_index must be within the limits set by
107 reftable_writer_set_limits(), or REFTABLE_API_ERROR is returned. It is an
108 REFTABLE_API_ERROR error to write a ref record after a log record.
110 int reftable_writer_add_ref(struct reftable_writer
*w
,
111 struct reftable_ref_record
*ref
);
114 Convenience function to add multiple reftable_ref_records; the function sorts
115 the records before adding them, reordering the records array passed in.
117 int reftable_writer_add_refs(struct reftable_writer
*w
,
118 struct reftable_ref_record
*refs
, int n
);
121 adds reftable_log_records. Log records are keyed by (refname, decreasing
122 update_index). The key for the record added must come after the already added
125 int reftable_writer_add_log(struct reftable_writer
*w
,
126 struct reftable_log_record
*log
);
129 Convenience function to add multiple reftable_log_records; the function sorts
130 the records before adding them, reordering records array passed in.
132 int reftable_writer_add_logs(struct reftable_writer
*w
,
133 struct reftable_log_record
*logs
, int n
);
135 /* reftable_writer_close finalizes the reftable. The writer is retained so
136 * statistics can be inspected. */
137 int reftable_writer_close(struct reftable_writer
*w
);
139 /* writer_stats returns the statistics on the reftable being written.
141 This struct becomes invalid when the writer is freed.
143 const struct reftable_stats
*writer_stats(struct reftable_writer
*w
);
145 /* reftable_writer_free deallocates memory for the writer */
146 void reftable_writer_free(struct reftable_writer
*w
);