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

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