Re: index prefetching

On Tue, Oct 13, 2026 at 10:40 AM Tomas Vondra <tomas(at)vondra(dot)me> wrote:
> Not sure. It probably does, but it's a bit unclear as it's explaining it
> as a tableam_index_pos_advance precondition, i.e. what "valid" means at
> the moment of calling that function.

We assert that caller's position is 'valid' at the top of
tableam_index_pos_advance. The simplest definition of 'valid' is "safe
to pass to tableam_index_pos_advance, also safe to use the position's
'batch' field as an argument to tableam_index_batch_loaded". The
'valid' field isn't really defined in terms of
tableam_index_pos_advance, but a more general definition would also be
less simple. I preferred the more general definition, partly because
'valid' appears in a different file to tableam_index_pos_advance.

What do you think is missing here, specifically?

> The description you posted above (esp. value=true means it's safe to
> call _advance) seems clearer to me. Maybe it's ultimately saying the
> same thing, but it seems clearer to me, maybe we could use some fo the
> in a comment somewhere.

Currently, we describe it as follows:

+/*
+ * Location of a BatchMatchingItem within the scan's ring buffer
+ */
+typedef struct BatchRingItemPos
+{
+ /* Position references a valid IndexScanDescData.batchbuf[] entry? */
+ bool valid;

I think that this is pretty clear: a given BatchRingItemPos whose
'valid' field is true has a 'batch' uint8 index into
IndexScanDescData.batchbuf[]. We can expect to find a valid
IndexScanBatch for that position through batchringbuf. And, we can get
to the next loaded batch (if any) by passing 'batch + 1' to functions
like tableam_index_batch_loaded or tableam_index_batch. Otherwise,
when 'valid' is false, the remaining BatchRingItemPos fields should be
assumed to contain only garbage uninitialized bytes (which is often
the case).

The reason we don't say very much about the meaning of
BatchRingItemPos's IndexScanBatch.items[]-wise index here (its 'item'
field) is that the routines to manipulate it live elsewhere (in
tableam_indexscan.h, not in relscan.h). So the rules regarding what
'item' means are described by comments within
tableam_index_pos_advance.

--
Peter Geoghegan