reftable/reader: rename data structure to "table"

The `struct reftable_reader` subsystem encapsulates a table that has
been read from the disk. As such, the current name of that structure is
somewhat hard to understand as it only talks about the fact that we read
something from disk, without really giving an indicator _what_ that is.

Furthermore, this naming schema doesn't really fit well into how the
other structures are named: `reftable_merged_table`, `reftable_stack`,
`reftable_block` and `reftable_record` are all named after what they
encapsulate.

Rename the subsystem to `reftable_table`, which directly gives a hint
that the data structure is about handling the individual tables part of
the stack.

While this change results in a lot of churn, it prepares for us exposing
the APIs to third-party callers now that the reftable library is a
standalone library that can be linked against by other projects.

Signed-off-by: Patrick Steinhardt <[email protected]>
Signed-off-by: Junio C Hamano <[email protected]>

Author: pks-t

Makefile

@@ -1374,10 +1374,10 @@ UNIT_TEST_PROGRAMS += t-reftable-basics
 UNIT_TEST_PROGRAMS += t-reftable-block
 UNIT_TEST_PROGRAMS += t-reftable-merged
 UNIT_TEST_PROGRAMS += t-reftable-pq
-UNIT_TEST_PROGRAMS += t-reftable-reader
 UNIT_TEST_PROGRAMS += t-reftable-readwrite
 UNIT_TEST_PROGRAMS += t-reftable-record
 UNIT_TEST_PROGRAMS += t-reftable-stack
+UNIT_TEST_PROGRAMS += t-reftable-table
 UNIT_TEST_PROGRAMS += t-trailer
 UNIT_TEST_PROGRAMS += t-urlmatch-normalization
 UNIT_TEST_PROGS = $(patsubst %,$(UNIT_TEST_BIN)/%$X,$(UNIT_TEST_PROGRAMS))
@@ -2729,10 +2729,10 @@ REFTABLE_OBJS += reftable/blocksource.o
 REFTABLE_OBJS += reftable/iter.o
 REFTABLE_OBJS += reftable/merged.o
 REFTABLE_OBJS += reftable/pq.o
-REFTABLE_OBJS += reftable/reader.o
 REFTABLE_OBJS += reftable/record.o
 REFTABLE_OBJS += reftable/stack.o
 REFTABLE_OBJS += reftable/system.o
+REFTABLE_OBJS += reftable/table.o
 REFTABLE_OBJS += reftable/tree.o
 REFTABLE_OBJS += reftable/writer.o
 

meson.build

@@ -410,10 +410,10 @@ libgit_sources = [
   'reftable/iter.c',
   'reftable/merged.c',
   'reftable/pq.c',
-  'reftable/reader.c',
   'reftable/record.c',
   'reftable/stack.c',
   'reftable/system.c',
+  'reftable/table.c',
   'reftable/tree.c',
   'reftable/writer.c',
   'remote.c',

reftable/iter.c

@@ -12,8 +12,8 @@
 
 #include "block.h"
 #include "constants.h"
-#include "reader.h"
 #include "reftable-error.h"
+#include "table.h"
 
 int iterator_seek(struct reftable_iterator *it, struct reftable_record *want)
 {
@@ -130,8 +130,8 @@ static int indexed_table_ref_iter_next_block(struct indexed_table_ref_iter *it)
 	reftable_block_done(&it->block_reader.block);
 
 	off = it->offsets[it->offset_idx++];
-	err = reader_init_block_reader(it->r, &it->block_reader, off,
-				       BLOCK_TYPE_REF);
+	err = table_init_block_reader(it->table, &it->block_reader, off,
+				      BLOCK_TYPE_REF);
 	if (err < 0) {
 		return err;
 	}
@@ -181,7 +181,7 @@ static int indexed_table_ref_iter_next(void *p, struct reftable_record *rec)
 }
 
 int indexed_table_ref_iter_new(struct indexed_table_ref_iter **dest,
-			       struct reftable_reader *r, uint8_t *oid,
+			       struct reftable_table *t, uint8_t *oid,
 			       int oid_len, uint64_t *offsets, int offset_len)
 {
 	struct indexed_table_ref_iter empty = INDEXED_TABLE_REF_ITER_INIT;
@@ -195,7 +195,7 @@ int indexed_table_ref_iter_new(struct indexed_table_ref_iter **dest,
 	}
 
 	*itr = empty;
-	itr->r = r;
+	itr->table = t;
 
 	err = reftable_buf_add(&itr->oid, oid, oid_len);
 	if (err < 0)

reftable/iter.h

@@ -59,7 +59,7 @@ void iterator_from_filtering_ref_iterator(struct reftable_iterator *,
  * but using the object index.
  */
 struct indexed_table_ref_iter {
-	struct reftable_reader *r;
+	struct reftable_table *table;
 	struct reftable_buf oid;
 
 	/* mutable */
@@ -83,7 +83,7 @@ void iterator_from_indexed_table_ref_iter(struct reftable_iterator *it,
 
 /* Takes ownership of `offsets` */
 int indexed_table_ref_iter_new(struct indexed_table_ref_iter **dest,
-			       struct reftable_reader *r, uint8_t *oid,
+			       struct reftable_table *t, uint8_t *oid,
 			       int oid_len, uint64_t *offsets, int offset_len);
 
 #endif

reftable/merged.c

@@ -11,11 +11,11 @@
 #include "constants.h"
 #include "iter.h"
 #include "pq.h"
-#include "reader.h"
 #include "record.h"
 #include "reftable-merged.h"
 #include "reftable-error.h"
 #include "system.h"
+#include "table.h"
 
 struct merged_subiter {
 	struct reftable_iterator iter;
@@ -192,18 +192,18 @@ static void iterator_from_merged_iter(struct reftable_iterator *it,
 }
 
 int reftable_merged_table_new(struct reftable_merged_table **dest,
-			      struct reftable_reader **readers, size_t n,
+			      struct reftable_table **tables, size_t n,
 			      enum reftable_hash hash_id)
 {
 	struct reftable_merged_table *m = NULL;
 	uint64_t last_max = 0;
 	uint64_t first_min = 0;
 
 	for (size_t i = 0; i < n; i++) {
-		uint64_t min = reftable_reader_min_update_index(readers[i]);
-		uint64_t max = reftable_reader_max_update_index(readers[i]);
+		uint64_t min = reftable_table_min_update_index(tables[i]);
+		uint64_t max = reftable_table_max_update_index(tables[i]);
 
-		if (reftable_reader_hash_id(readers[i]) != hash_id) {
+		if (reftable_table_hash_id(tables[i]) != hash_id) {
 			return REFTABLE_FORMAT_ERROR;
 		}
 		if (i == 0 || min < first_min) {
@@ -218,8 +218,8 @@ int reftable_merged_table_new(struct reftable_merged_table **dest,
 	if (!m)
 		return REFTABLE_OUT_OF_MEMORY_ERROR;
 
-	m->readers = readers;
-	m->readers_len = n;
+	m->tables = tables;
+	m->tables_len = n;
 	m->min = first_min;
 	m->max = last_max;
 	m->hash_id = hash_id;
@@ -254,20 +254,20 @@ int merged_table_init_iter(struct reftable_merged_table *mt,
 	struct merged_iter *mi = NULL;
 	int ret;
 
-	if (mt->readers_len) {
-		REFTABLE_CALLOC_ARRAY(subiters, mt->readers_len);
+	if (mt->tables_len) {
+		REFTABLE_CALLOC_ARRAY(subiters, mt->tables_len);
 		if (!subiters) {
 			ret = REFTABLE_OUT_OF_MEMORY_ERROR;
 			goto out;
 		}
 	}
 
-	for (size_t i = 0; i < mt->readers_len; i++) {
+	for (size_t i = 0; i < mt->tables_len; i++) {
 		ret = reftable_record_init(&subiters[i].rec, typ);
 		if (ret < 0)
 			goto out;
 
-		ret = reader_init_iter(mt->readers[i], &subiters[i].iter, typ);
+		ret = table_init_iter(mt->tables[i], &subiters[i].iter, typ);
 		if (ret < 0)
 			goto out;
 	}
@@ -280,14 +280,14 @@ int merged_table_init_iter(struct reftable_merged_table *mt,
 	mi->advance_index = -1;
 	mi->suppress_deletions = mt->suppress_deletions;
 	mi->subiters = subiters;
-	mi->subiters_len = mt->readers_len;
+	mi->subiters_len = mt->tables_len;
 
 	iterator_from_merged_iter(it, mi);
 	ret = 0;
 
 out:
 	if (ret < 0) {
-		for (size_t i = 0; subiters && i < mt->readers_len; i++) {
+		for (size_t i = 0; subiters && i < mt->tables_len; i++) {
 			reftable_iterator_destroy(&subiters[i].iter);
 			reftable_record_release(&subiters[i].rec);
 		}

reftable/merged.h

@@ -13,8 +13,8 @@
 #include "reftable-basics.h"
 
 struct reftable_merged_table {
-	struct reftable_reader **readers;
-	size_t readers_len;
+	struct reftable_table **tables;
+	size_t tables_len;
 	enum reftable_hash hash_id;
 
 	/* If unset, produce deletions. This is useful for compaction. For the

reftable/reftable-merged.h

@@ -26,14 +26,14 @@
 /* A merged table is implements seeking/iterating over a stack of tables. */
 struct reftable_merged_table;
 
-struct reftable_reader;
+struct reftable_table;
 
 /*
- * reftable_merged_table_new creates a new merged table. The readers must be
+ * reftable_merged_table_new creates a new merged table. The tables must be
  * kept alive as long as the merged table is still in use.
  */
 int reftable_merged_table_new(struct reftable_merged_table **dest,
-			      struct reftable_reader **readers, size_t n,
+			      struct reftable_table **tables, size_t n,
 			      enum reftable_hash hash_id);
 
 /* Initialize a merged table iterator for reading refs. */

reftable/reftable-reader.h

@@ -0,0 +1,72 @@
+/*
+ * 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_TABLE_H
+#define REFTABLE_TABLE_H
+
+#include "reftable-iterator.h"
+#include "reftable-blocksource.h"
+
+/*
+ * Reading single tables
+ *
+ * The follow routines are for reading single files. For an
+ * application-level interface, skip ahead to struct
+ * reftable_merged_table and struct reftable_stack.
+ */
+
+/* The table struct is a handle to an open reftable file. */
+struct reftable_table;
+
+/* reftable_table_new opens a reftable for reading. If successful,
+ * returns 0 code and sets pp. The name is used for creating a
+ * stack. Typically, it is the basename of the file. The block source
+ * `src` is owned by the table, and is closed on calling
+ * reftable_table_destroy(). On error, the block source `src` is
+ * closed as well.
+ */
+int reftable_table_new(struct reftable_table **out,
+		       struct reftable_block_source *src, const char *name);
+
+/*
+ * Manage the reference count of the reftable table. A newly initialized
+ * table starts with a refcount of 1 and will be deleted once the refcount has
+ * reached 0.
+ *
+ * This is required because tables may have longer lifetimes than the stack
+ * they belong to. The stack may for example be reloaded while the old tables
+ * are still being accessed by an iterator.
+ */
+void reftable_table_incref(struct reftable_table *table);
+void reftable_table_decref(struct reftable_table *table);
+
+/* Initialize a reftable iterator for reading refs. */
+int reftable_table_init_ref_iterator(struct reftable_table *t,
+				     struct reftable_iterator *it);
+
+/* Initialize a reftable iterator for reading logs. */
+int reftable_table_init_log_iterator(struct reftable_table *t,
+				     struct reftable_iterator *it);
+
+/* returns the hash ID used in this table. */
+enum reftable_hash reftable_table_hash_id(struct reftable_table *t);
+
+/* return an iterator for the refs pointing to `oid`. */
+int reftable_table_refs_for(struct reftable_table *t,
+			    struct reftable_iterator *it, uint8_t *oid);
+
+/* return the max_update_index for a table */
+uint64_t reftable_table_max_update_index(struct reftable_table *t);
+
+/* return the min_update_index for a table */
+uint64_t reftable_table_min_update_index(struct reftable_table *t);
+
+/* print blocks onto stdout for debugging. */
+int reftable_table_print_blocks(const char *tablename);
+
+#endif