reftable/reftable-stack.h

   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  */
  26 struct 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  */
  31 int 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. */
  35 uint64_t reftable_stack_next_update_index(struct reftable_stack *st);
  36
  37 /* holds a transaction to add tables at the top of a stack. */
  38 struct reftable_addition;
  39
  40 enum {
  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  */
  52 int reftable_stack_new_addition(struct reftable_addition **dest,
  53                                 struct reftable_stack *st,
  54                                 unsigned int flags);
  55
  56 /* Adds a reftable to transaction. */
  57 int 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  */
  65 int 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. */
  69 void reftable_addition_destroy(struct reftable_addition *add);
  70
  71 /* add a new table to the stack. The write_table function must call
  72  * reftable_writer_set_limits, add refs and return an error value. */
  73 int reftable_stack_add(struct reftable_stack *st,
  74                        int (*write_table)(struct reftable_writer *wr,
  75                                           void *write_arg),
  76                        void *write_arg);
  77
  78 struct reftable_iterator;
  79
  80 /*
  81  * Initialize an iterator for the merged tables contained in the stack that can
  82  * be used to iterate through refs. The iterator is valid until the next reload
  83  * or write.
  84  */
  85 int reftable_stack_init_ref_iterator(struct reftable_stack *st,
  86                                      struct reftable_iterator *it);
  87
  88 /*
  89  * Initialize an iterator for the merged tables contained in the stack that can
  90  * be used to iterate through logs. The iterator is valid until the next reload
  91  * or write.
  92  */
  93 int reftable_stack_init_log_iterator(struct reftable_stack *st,
  94                                      struct reftable_iterator *it);
  95
  96 /* returns the merged_table for seeking. This table is valid until the
  97  * next write or reload, and should not be closed or deleted.
  98  */
  99 struct reftable_merged_table *
 100 reftable_stack_merged_table(struct reftable_stack *st);
 101
 102 /* frees all resources associated with the stack. */
 103 void reftable_stack_destroy(struct reftable_stack *st);
 104
 105 /* Reloads the stack if necessary. This is very cheap to run if the stack was up
 106  * to date */
 107 int reftable_stack_reload(struct reftable_stack *st);
 108
 109 /* Policy for expiring reflog entries. */
 110 struct reftable_log_expiry_config {
 111         /* Drop entries older than this timestamp */
 112         uint64_t time;
 113
 114         /* Drop older entries */
 115         uint64_t min_update_index;
 116 };
 117
 118 /* compacts all reftables into a giant table. Expire reflog entries if config is
 119  * non-NULL */
 120 int reftable_stack_compact_all(struct reftable_stack *st,
 121                                struct reftable_log_expiry_config *config);
 122
 123 /* heuristically compact unbalanced table stack. */
 124 int reftable_stack_auto_compact(struct reftable_stack *st);
 125
 126 /* delete stale .ref tables. */
 127 int reftable_stack_clean(struct reftable_stack *st);
 128
 129 /* convenience function to read a single ref. Returns < 0 for error, 0 for
 130  * success, and 1 if ref not found. */
 131 int reftable_stack_read_ref(struct reftable_stack *st, const char *refname,
 132                             struct reftable_ref_record *ref);
 133
 134 /* convenience function to read a single log. Returns < 0 for error, 0 for
 135  * success, and 1 if ref not found. */
 136 int reftable_stack_read_log(struct reftable_stack *st, const char *refname,
 137                             struct reftable_log_record *log);
 138
 139 /* statistics on past compactions. */
 140 struct reftable_compaction_stats {
 141         uint64_t bytes; /* total number of bytes written */
 142         uint64_t entries_written; /* total number of entries written, including
 143                                      failures. */
 144         int attempts; /* how often we tried to compact */
 145         int failures; /* failures happen on concurrent updates */
 146 };
 147
 148 /* return statistics for compaction up till now. */
 149 struct reftable_compaction_stats *
 150 reftable_stack_compaction_stats(struct reftable_stack *st);
 151
 152 /* Return the hash of the stack. */
 153 enum reftable_hash reftable_stack_hash_id(struct reftable_stack *st);
 154
 155 #endif