[thirdparty/git.git] / reftable / reftable-writer.h

/*
Copyright 2020 Google LLC

Use of this source code is governed by a BSD-style
license that can be found in the LICENSE file or at
https://developers.google.com/open-source/licenses/bsd
*/

#ifndef REFTABLE_WRITER_H
#define REFTABLE_WRITER_H

#include "reftable-record.h"

#include <stdint.h>
#include <unistd.h> /* ssize_t */

/* Writing single reftables */

/* reftable_write_options sets options for writing a single reftable. */
struct reftable_write_options {
	/* boolean: do not pad out blocks to block size. */
	unsigned unpadded : 1;

	/* the blocksize. Should be less than 2^24. */
	uint32_t block_size;

	/* boolean: do not generate a SHA1 => ref index. */
	unsigned skip_index_objects : 1;

	/* how often to write complete keys in each block. */
	int restart_interval;

	/* 4-byte identifier ("sha1", "s256") of the hash.
	 * Defaults to SHA1 if unset
	 */
	uint32_t hash_id;

	/* boolean: do not check ref names for validity or dir/file conflicts.
	 */
	unsigned skip_name_check : 1;

	/* boolean: copy log messages exactly. If unset, check that the message
	 *   is a single line, and add '\n' if missing.
	 */
	unsigned exact_log_message : 1;
};

/* reftable_block_stats holds statistics for a single block type */
struct reftable_block_stats {
	/* total number of entries written */
	int entries;
	/* total number of key restarts */
	int restarts;
	/* total number of blocks */
	int blocks;
	/* total number of index blocks */
	int index_blocks;
	/* depth of the index */
	int max_index_level;

	/* offset of the first block for this type */
	uint64_t offset;
	/* offset of the top level index block for this type, or 0 if not
	 * present */
	uint64_t index_offset;
};

/* stats holds overall statistics for a single reftable */
struct reftable_stats {
	/* total number of blocks written. */
	int blocks;
	/* stats for ref data */
	struct reftable_block_stats ref_stats;
	/* stats for the SHA1 to ref map. */
	struct reftable_block_stats obj_stats;
	/* stats for index blocks */
	struct reftable_block_stats idx_stats;
	/* stats for log blocks */
	struct reftable_block_stats log_stats;

	/* disambiguation length of shortened object IDs. */
	int object_id_len;
};

/* reftable_new_writer creates a new writer */
struct reftable_writer *
reftable_new_writer(ssize_t (*writer_func)(void *, const void *, size_t),
		    void *writer_arg, struct reftable_write_options *opts);

/* Set the range of update indices for the records we will add. When writing a
   table into a stack, the min should be at least
   reftable_stack_next_update_index(), or REFTABLE_API_ERROR is returned.

   For transactional updates to a stack, typically min==max, and the
   update_index can be obtained by inspeciting the stack. When converting an
   existing ref database into a single reftable, this would be a range of
   update-index timestamps.
 */
void reftable_writer_set_limits(struct reftable_writer *w, uint64_t min,
				uint64_t max);

/*
  Add a reftable_ref_record. The record should have names that come after
  already added records.

  The update_index must be within the limits set by
  reftable_writer_set_limits(), or REFTABLE_API_ERROR is returned. It is an
  REFTABLE_API_ERROR error to write a ref record after a log record.
*/
int reftable_writer_add_ref(struct reftable_writer *w,
			    struct reftable_ref_record *ref);

/*
  Convenience function to add multiple reftable_ref_records; the function sorts
  the records before adding them, reordering the records array passed in.
*/
int reftable_writer_add_refs(struct reftable_writer *w,
			     struct reftable_ref_record *refs, int n);

/*
  adds reftable_log_records. Log records are keyed by (refname, decreasing
  update_index). The key for the record added must come after the already added
  log records.
*/
int reftable_writer_add_log(struct reftable_writer *w,
			    struct reftable_log_record *log);

/*
  Convenience function to add multiple reftable_log_records; the function sorts
  the records before adding them, reordering records array passed in.
*/
int reftable_writer_add_logs(struct reftable_writer *w,
			     struct reftable_log_record *logs, int n);

/* reftable_writer_close finalizes the reftable. The writer is retained so
 * statistics can be inspected. */
int reftable_writer_close(struct reftable_writer *w);

/* writer_stats returns the statistics on the reftable being written.

   This struct becomes invalid when the writer is freed.
 */
const struct reftable_stats *writer_stats(struct reftable_writer *w);

/* reftable_writer_free deallocates memory for the writer */
void reftable_writer_free(struct reftable_writer *w);

#endif
Commit	Line	Data
f14bd719 HWN	1	/*
	2	Copyright 2020 Google LLC
	3
	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
	7	*/
	8
	9	#ifndef REFTABLE_WRITER_H
	10	#define REFTABLE_WRITER_H
	11
	12	#include "reftable-record.h"
	13
	14	#include <stdint.h>
	15	#include <unistd.h> /* ssize_t */
	16
	17	/* Writing single reftables */
	18
	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;
	23
	24	/* the blocksize. Should be less than 2^24. */
	25	uint32_t block_size;
	26
	27	/* boolean: do not generate a SHA1 => ref index. */
	28	unsigned skip_index_objects : 1;
	29
	30	/* how often to write complete keys in each block. */
	31	int restart_interval;
	32
	33	/* 4-byte identifier ("sha1", "s256") of the hash.
	34	* Defaults to SHA1 if unset
	35	*/
	36	uint32_t hash_id;
	37
	38	/* boolean: do not check ref names for validity or dir/file conflicts.
	39	*/
	40	unsigned skip_name_check : 1;
	41
	42	/* boolean: copy log messages exactly. If unset, check that the message
	43	* is a single line, and add '\n' if missing.
	44	*/
	45	unsigned exact_log_message : 1;
	46	};
	47
	48	/* reftable_block_stats holds statistics for a single block type */
	49	struct reftable_block_stats {
	50	/* total number of entries written */
	51	int entries;
	52	/* total number of key restarts */
	53	int restarts;
	54	/* total number of blocks */
	55	int blocks;
	56	/* total number of index blocks */
	57	int index_blocks;
	58	/* depth of the index */
	59	int max_index_level;
	60
	61	/* offset of the first block for this type */
	62	uint64_t offset;
	63	/* offset of the top level index block for this type, or 0 if not
	64	* present */
65	uint64_t index_offset;
66	};
67
68	/* stats holds overall statistics for a single reftable */
69	struct reftable_stats {
70	/* total number of blocks written. */
71	int blocks;
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;
80
81	/* disambiguation length of shortened object IDs. */
82	int object_id_len;
83	};
84
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);
89
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.
93
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.
98	*/
99	void reftable_writer_set_limits(struct reftable_writer *w, uint64_t min,
100	uint64_t max);
101
102	/*
103	Add a reftable_ref_record. The record should have names that come after
104	already added records.
105
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.
109	*/
110	int reftable_writer_add_ref(struct reftable_writer *w,
111	struct reftable_ref_record *ref);
112
113	/*
114	Convenience function to add multiple reftable_ref_records; the function sorts
115	the records before adding them, reordering the records array passed in.
116	*/
117	int reftable_writer_add_refs(struct reftable_writer *w,
118	struct reftable_ref_record *refs, int n);
119
120	/*
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
123	log records.
124	*/
125	int reftable_writer_add_log(struct reftable_writer *w,
126	struct reftable_log_record *log);
127
128	/*
129	Convenience function to add multiple reftable_log_records; the function sorts
130	the records before adding them, reordering records array passed in.
131	*/
132	int reftable_writer_add_logs(struct reftable_writer *w,
133	struct reftable_log_record *logs, int n);
134
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);
138
139	/* writer_stats returns the statistics on the reftable being written.
140
141	This struct becomes invalid when the writer is freed.
142	*/
143	const struct reftable_stats writer_stats(struct reftable_writer w);
144
145	/* reftable_writer_free deallocates memory for the writer */
146	void reftable_writer_free(struct reftable_writer *w);
147
148	#endif