reftable/reftable-reader.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_READER_H
  10 #define REFTABLE_READER_H
  11
  12 #include "reftable-iterator.h"
  13 #include "reftable-blocksource.h"
  14
  15 /*
  16  * Reading single tables
  17  *
  18  * The follow routines are for reading single files. For an
  19  * application-level interface, skip ahead to struct
  20  * reftable_merged_table and struct reftable_stack.
  21  */
  22
  23 /* The reader struct is a handle to an open reftable file. */
  24 struct reftable_reader;
  25
  26 /* Generic table. */
  27 struct reftable_table;
  28
  29 /* reftable_new_reader opens a reftable for reading. If successful,
  30  * returns 0 code and sets pp. The name is used for creating a
  31  * stack. Typically, it is the basename of the file. The block source
  32  * `src` is owned by the reader, and is closed on calling
  33  * reftable_reader_destroy(). On error, the block source `src` is
  34  * closed as well.
  35  */
  36 int reftable_new_reader(struct reftable_reader **pp,
  37                         struct reftable_block_source *src, const char *name);
  38
  39 /* reftable_reader_seek_ref returns an iterator where 'name' would be inserted
  40    in the table.  To seek to the start of the table, use name = "".
  41
  42    example:
  43
  44    struct reftable_reader *r = NULL;
  45    int err = reftable_new_reader(&r, &src, "filename");
  46    if (err < 0) { ... }
  47    struct reftable_iterator it  = {0};
  48    err = reftable_reader_seek_ref(r, &it, "refs/heads/master");
  49    if (err < 0) { ... }
  50    struct reftable_ref_record ref  = {0};
  51    while (1) {
  52    err = reftable_iterator_next_ref(&it, &ref);
  53    if (err > 0) {
  54    break;
  55    }
  56    if (err < 0) {
  57    ..error handling..
  58    }
  59    ..found..
  60    }
  61    reftable_iterator_destroy(&it);
  62    reftable_ref_record_release(&ref);
  63 */
  64 int reftable_reader_seek_ref(struct reftable_reader *r,
  65                              struct reftable_iterator *it, const char *name);
  66
  67 /* returns the hash ID used in this table. */
  68 uint32_t reftable_reader_hash_id(struct reftable_reader *r);
  69
  70 /* seek to logs for the given name, older than update_index. To seek to the
  71    start of the table, use name = "".
  72 */
  73 int reftable_reader_seek_log_at(struct reftable_reader *r,
  74                                 struct reftable_iterator *it, const char *name,
  75                                 uint64_t update_index);
  76
  77 /* seek to newest log entry for given name. */
  78 int reftable_reader_seek_log(struct reftable_reader *r,
  79                              struct reftable_iterator *it, const char *name);
  80
  81 /* closes and deallocates a reader. */
  82 void reftable_reader_free(struct reftable_reader *);
  83
  84 /* return an iterator for the refs pointing to `oid`. */
  85 int reftable_reader_refs_for(struct reftable_reader *r,
  86                              struct reftable_iterator *it, uint8_t *oid);
  87
  88 /* return the max_update_index for a table */
  89 uint64_t reftable_reader_max_update_index(struct reftable_reader *r);
  90
  91 /* return the min_update_index for a table */
  92 uint64_t reftable_reader_min_update_index(struct reftable_reader *r);
  93
  94 /* creates a generic table from a file reader. */
  95 void reftable_table_from_reader(struct reftable_table *tab,
  96                                 struct reftable_reader *reader);
  97
  98 /* print table onto stdout for debugging. */
  99 int reftable_reader_print_file(const char *tablename);
 100
 101 #endif