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                        struct reftable_write_options config);
  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 /*
  41  * returns a new transaction to add reftables to the given stack. As a side
  42  * effect, the ref database is locked.
  43  */
  44 int reftable_stack_new_addition(struct reftable_addition **dest,
  45                                 struct reftable_stack *st);
  46
  47 /* Adds a reftable to transaction. */
  48 int reftable_addition_add(struct reftable_addition *add,
  49                           int (*write_table)(struct reftable_writer *wr,
  50                                              void *arg),
  51                           void *arg);
  52
  53 /* Commits the transaction, releasing the lock. After calling this,
  54  * reftable_addition_destroy should still be called.
  55  */
  56 int reftable_addition_commit(struct reftable_addition *add);
  57
  58 /* Release all non-committed data from the transaction, and deallocate the
  59  * transaction. Releases the lock if held. */
  60 void reftable_addition_destroy(struct reftable_addition *add);
  61
  62 /* add a new table to the stack. The write_table function must call
  63  * reftable_writer_set_limits, add refs and return an error value. */
  64 int reftable_stack_add(struct reftable_stack *st,
  65                        int (*write_table)(struct reftable_writer *wr,
  66                                           void *write_arg),
  67                        void *write_arg);
  68
  69 /* returns the merged_table for seeking. This table is valid until the
  70  * next write or reload, and should not be closed or deleted.
  71  */
  72 struct reftable_merged_table *
  73 reftable_stack_merged_table(struct reftable_stack *st);
  74
  75 /* frees all resources associated with the stack. */
  76 void reftable_stack_destroy(struct reftable_stack *st);
  77
  78 /* Reloads the stack if necessary. This is very cheap to run if the stack was up
  79  * to date */
  80 int reftable_stack_reload(struct reftable_stack *st);
  81
  82 /* Policy for expiring reflog entries. */
  83 struct reftable_log_expiry_config {
  84         /* Drop entries older than this timestamp */
  85         uint64_t time;
  86
  87         /* Drop older entries */
  88         uint64_t min_update_index;
  89 };
  90
  91 /* compacts all reftables into a giant table. Expire reflog entries if config is
  92  * non-NULL */
  93 int reftable_stack_compact_all(struct reftable_stack *st,
  94                                struct reftable_log_expiry_config *config);
  95
  96 /* heuristically compact unbalanced table stack. */
  97 int reftable_stack_auto_compact(struct reftable_stack *st);
  98
  99 /* delete stale .ref tables. */
 100 int reftable_stack_clean(struct reftable_stack *st);
 101
 102 /* convenience function to read a single ref. Returns < 0 for error, 0 for
 103  * success, and 1 if ref not found. */
 104 int reftable_stack_read_ref(struct reftable_stack *st, const char *refname,
 105                             struct reftable_ref_record *ref);
 106
 107 /* convenience function to read a single log. Returns < 0 for error, 0 for
 108  * success, and 1 if ref not found. */
 109 int reftable_stack_read_log(struct reftable_stack *st, const char *refname,
 110                             struct reftable_log_record *log);
 111
 112 /* statistics on past compactions. */
 113 struct reftable_compaction_stats {
 114         uint64_t bytes; /* total number of bytes written */
 115         uint64_t entries_written; /* total number of entries written, including
 116                                      failures. */
 117         int attempts; /* how often we tried to compact */
 118         int failures; /* failures happen on concurrent updates */
 119 };
 120
 121 /* return statistics for compaction up till now. */
 122 struct reftable_compaction_stats *
 123 reftable_stack_compaction_stats(struct reftable_stack *st);
 124
 125 /* print the entire stack represented by the directory */
 126 int reftable_stack_print_directory(const char *stackdir, uint32_t hash_id);
 127
 128 #endif