freshlybakedca.ke
Git fork
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_STACK_H
10#define REFTABLE_STACK_H
11
12#include "reftable-writer.h"
13
14/*
15 * The stack presents an interface to a mutable sequence of reftables.
16
17 * A stack can be mutated by pushing a table to the top of the stack.
18
19 * The reftable_stack automatically compacts files on disk to ensure good
20 * amortized performance.
21 *
22 * For windows and other platforms that cannot have open files as rename
23 * destinations, concurrent access from multiple processes needs the rand()
24 * random seed to be randomized.
25 */
26struct reftable_stack;
27
28/* open a new reftable stack. The tables along with the table list will be
29 * stored in 'dir'. Typically, this should be .git/reftables.
30 */
31int reftable_new_stack(struct reftable_stack **dest, const char *dir,
32 const struct reftable_write_options *opts);
33
34/* returns the update_index at which a next table should be written. */
35uint64_t reftable_stack_next_update_index(struct reftable_stack *st);
36
37/* holds a transaction to add tables at the top of a stack. */
38struct reftable_addition;
39
40enum {
41 /*
42 * Reload the stack when the stack is out-of-date after locking it.
43 */
44 REFTABLE_STACK_NEW_ADDITION_RELOAD = (1 << 0),
45};
46
47/*
48 * returns a new transaction to add reftables to the given stack. As a side
49 * effect, the ref database is locked. Accepts REFTABLE_STACK_NEW_ADDITION_*
50 * flags.
51 */
52int reftable_stack_new_addition(struct reftable_addition **dest,
53 struct reftable_stack *st,
54 unsigned int flags);
55
56/* Adds a reftable to transaction. */
57int reftable_addition_add(struct reftable_addition *add,
58 int (*write_table)(struct reftable_writer *wr,
59 void *arg),
60 void *arg);
61
62/* Commits the transaction, releasing the lock. After calling this,
63 * reftable_addition_destroy should still be called.
64 */
65int reftable_addition_commit(struct reftable_addition *add);
66
67/* Release all non-committed data from the transaction, and deallocate the
68 * transaction. Releases the lock if held. */
69void reftable_addition_destroy(struct reftable_addition *add);
70
71/*
72 * Add a new table to the stack. The write_table function must call
73 * reftable_writer_set_limits, add refs and return an error value.
74 * The flags are passed through to `reftable_stack_new_addition()`.
75 */
76int reftable_stack_add(struct reftable_stack *st,
77 int (*write_table)(struct reftable_writer *wr,
78 void *write_arg),
79 void *write_arg, unsigned flags);
80
81struct reftable_iterator;
82
83/*
84 * Initialize an iterator for the merged tables contained in the stack that can
85 * be used to iterate through refs. The iterator is valid until the next reload
86 * or write.
87 */
88int reftable_stack_init_ref_iterator(struct reftable_stack *st,
89 struct reftable_iterator *it);
90
91/*
92 * Initialize an iterator for the merged tables contained in the stack that can
93 * be used to iterate through logs. The iterator is valid until the next reload
94 * or write.
95 */
96int reftable_stack_init_log_iterator(struct reftable_stack *st,
97 struct reftable_iterator *it);
98
99/* returns the merged_table for seeking. This table is valid until the
100 * next write or reload, and should not be closed or deleted.
101 */
102struct reftable_merged_table *
103reftable_stack_merged_table(struct reftable_stack *st);
104
105/* frees all resources associated with the stack. */
106void reftable_stack_destroy(struct reftable_stack *st);
107
108/* Reloads the stack if necessary. This is very cheap to run if the stack was up
109 * to date */
110int reftable_stack_reload(struct reftable_stack *st);
111
112/* Policy for expiring reflog entries. */
113struct reftable_log_expiry_config {
114 /* Drop entries older than this timestamp */
115 uint64_t time;
116
117 /* Drop older entries */
118 uint64_t min_update_index;
119};
120
121/* compacts all reftables into a giant table. Expire reflog entries if config is
122 * non-NULL */
123int reftable_stack_compact_all(struct reftable_stack *st,
124 struct reftable_log_expiry_config *config);
125
126/* heuristically compact unbalanced table stack. */
127int reftable_stack_auto_compact(struct reftable_stack *st);
128
129/* delete stale .ref tables. */
130int reftable_stack_clean(struct reftable_stack *st);
131
132/* convenience function to read a single ref. Returns < 0 for error, 0 for
133 * success, and 1 if ref not found. */
134int reftable_stack_read_ref(struct reftable_stack *st, const char *refname,
135 struct reftable_ref_record *ref);
136
137/* convenience function to read a single log. Returns < 0 for error, 0 for
138 * success, and 1 if ref not found. */
139int reftable_stack_read_log(struct reftable_stack *st, const char *refname,
140 struct reftable_log_record *log);
141
142/* statistics on past compactions. */
143struct reftable_compaction_stats {
144 uint64_t bytes; /* total number of bytes written */
145 uint64_t entries_written; /* total number of entries written, including
146 failures. */
147 int attempts; /* how often we tried to compact */
148 int failures; /* failures happen on concurrent updates */
149};
150
151/* return statistics for compaction up till now. */
152struct reftable_compaction_stats *
153reftable_stack_compaction_stats(struct reftable_stack *st);
154
155/* Return the hash of the stack. */
156enum reftable_hash reftable_stack_hash_id(struct reftable_stack *st);
157
158#endif