[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;

	/* Default mode for creating files. If unset, use 0666 (+umask) */
	unsigned int default_permissions;

	/* 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),
		    int (*flush_func)(void *),
		    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 *reftable_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
cd1799de HWN	38	/* Default mode for creating files. If unset, use 0666 (+umask) */
	39	unsigned int default_permissions;
	40
f14bd719 HWN	41	/* boolean: do not check ref names for validity or dir/file conflicts.
	42	*/
	43	unsigned skip_name_check : 1;
	44
	45	/* boolean: copy log messages exactly. If unset, check that the message
	46	* is a single line, and add '\n' if missing.
	47	*/
	48	unsigned exact_log_message : 1;
	49	};
	50
	51	/* reftable_block_stats holds statistics for a single block type */
	52	struct reftable_block_stats {
	53	/* total number of entries written */
	54	int entries;
	55	/* total number of key restarts */
	56	int restarts;
	57	/* total number of blocks */
	58	int blocks;
	59	/* total number of index blocks */
	60	int index_blocks;
	61	/* depth of the index */
	62	int max_index_level;
	63
	64	/* offset of the first block for this type */
	65	uint64_t offset;
	66	/* offset of the top level index block for this type, or 0 if not
	67	* present */
	68	uint64_t index_offset;
	69	};
	70
	71	/* stats holds overall statistics for a single reftable */
	72	struct reftable_stats {
	73	/* total number of blocks written. */
	74	int blocks;
	75	/* stats for ref data */
	76	struct reftable_block_stats ref_stats;
	77	/* stats for the SHA1 to ref map. */
	78	struct reftable_block_stats obj_stats;
	79	/* stats for index blocks */
	80	struct reftable_block_stats idx_stats;
	81	/* stats for log blocks */
	82	struct reftable_block_stats log_stats;
	83
	84	/* disambiguation length of shortened object IDs. */
	85	int object_id_len;
	86	};
	87
	88	/* reftable_new_writer creates a new writer */
	89	struct reftable_writer *
	90	reftable_new_writer(ssize_t (writer_func)(void , const void *, size_t),
1df18a1c	91	int (flush_func)(void ),
f14bd719 HWN	92	void writer_arg, struct reftable_write_options opts);
	93
	94	/* Set the range of update indices for the records we will add. When writing a
	95	table into a stack, the min should be at least
	96	reftable_stack_next_update_index(), or REFTABLE_API_ERROR is returned.
	97
	98	For transactional updates to a stack, typically min==max, and the
	99	update_index can be obtained by inspeciting the stack. When converting an
	100	existing ref database into a single reftable, this would be a range of
	101	update-index timestamps.
	102	*/
	103	void reftable_writer_set_limits(struct reftable_writer *w, uint64_t min,
	104	uint64_t max);
	105
	106	/*
	107	Add a reftable_ref_record. The record should have names that come after
	108	already added records.
	109
	110	The update_index must be within the limits set by
	111	reftable_writer_set_limits(), or REFTABLE_API_ERROR is returned. It is an
	112	REFTABLE_API_ERROR error to write a ref record after a log record.
	113	*/
	114	int reftable_writer_add_ref(struct reftable_writer *w,
	115	struct reftable_ref_record *ref);
	116
	117	/*
	118	Convenience function to add multiple reftable_ref_records; the function sorts
	119	the records before adding them, reordering the records array passed in.
	120	*/
	121	int reftable_writer_add_refs(struct reftable_writer *w,
	122	struct reftable_ref_record *refs, int n);
	123
	124	/*
	125	adds reftable_log_records. Log records are keyed by (refname, decreasing
	126	update_index). The key for the record added must come after the already added
	127	log records.
	128	*/
	129	int reftable_writer_add_log(struct reftable_writer *w,
	130	struct reftable_log_record *log);
	131
	132	/*
	133	Convenience function to add multiple reftable_log_records; the function sorts
	134	the records before adding them, reordering records array passed in.
	135	*/
	136	int reftable_writer_add_logs(struct reftable_writer *w,
	137	struct reftable_log_record *logs, int n);
	138
	139	/* reftable_writer_close finalizes the reftable. The writer is retained so
	140	* statistics can be inspected. */
	141	int reftable_writer_close(struct reftable_writer *w);
	142
	143	/* writer_stats returns the statistics on the reftable being written.
	144
	145	This struct becomes invalid when the writer is freed.
	146	*/
73a4c188	147	const struct reftable_stats reftable_writer_stats(struct reftable_writer w);
f14bd719 HWN	148
	149	/* reftable_writer_free deallocates memory for the writer */
	150	void reftable_writer_free(struct reftable_writer *w);
	151
	152	#endif