Skip to content

feat: add async cursor prefetch mechanism - #20897

Open
clintropolis wants to merge 1 commit into
apache:masterfrom
clintropolis:cursor-factory-prefetch
Open

clintropolis wants to merge 1 commit into
apache:masterfrom
clintropolis:cursor-factory-prefetch

Conversation

@clintropolis

@clintropolis clintropolis commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Description

This PR adds CursorFactory#prefetch which starts the loading that a later makeCursorHolderAsync(spec) would otherwise do on demand for partial loading V10 segments. This is a building block for load-ahead prefetch in MSQ leaf stages (which will come in a follow-up).

Comment on lines +1218 to +1226
@SuppressWarnings("unused")
ListenableFuture<?> unused = gatedExec.submit(() -> {
try {
gate.await();
}
catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
});

@FrankChen021 FrankChen021 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No actionable issues found in this review. The prefetch lifecycle and shared async cursor machinery preserve bundle ownership across success, failure, and cancellation, while wrapper factories pass the same transformed specifications used by async cursor construction.

Reviewed 18 of 18 changed files.


This is an automated review by Codex GPT-5.6-Luna(max)

@FrankChen021 FrankChen021 added the Approval Recommended Used when AI completes a review and reports no findings label Nov 13, 2026
@capistrant
capistrant self-requested a review November 16, 2026 17:39

@capistrant capistrant left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mostly have suggested some minor javadoc tweaks (non-blocking opinions) plus some general questions about the contract of CursorPrefetch. Biggest potentially blocking concern has an inline comment in the partial cursor factory prefetch method on handling of some synchronous failures and whether it breaks the stated prefetch contract. Overall tho, seems cool

Comment on lines +74 to +77
/**
* The spec passed to the delegate: the caller's spec with {@link #policy} applied. Used by every delegating method
* here.
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit suggestion

Suggested change
/**
* The spec passed to the delegate: the caller's spec with {@link #policy} applied. Used by every delegating method
* here.
*/
/**
* The caller's spec with {@link #policy} applied.
*/

Comment on lines +120 to +124
/**
* The spec passed to the base cursor factory: the caller's spec rewritten for the unnest input column, with only
* the base-table half of its filters (see {@link #computeFilterSplit}). Shared by every holder path, which also need
* {@code filterSplit} for the post-unnest half.
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit suggestion

Suggested change
/**
* The spec passed to the base cursor factory: the caller's spec rewritten for the unnest input column, with only
* the base-table half of its filters (see {@link #computeFilterSplit}). Shared by every holder path, which also need
* {@code filterSplit} for the post-unnest half.
*/
/**
* The spec passed to the base cursor factory: the caller's spec rewritten for the unnest input column, with only
* the base-table half of its filters (see {@link #computeFilterSplit}).
*/

Comment on lines +112 to +114
/**
* The spec passed to the base cursor factory for {@code spec}, computing the filter split itself.
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I'd remove this as it feels self explanatory if the reader just looks at the called delegateSpec

Comment on lines +123 to +125
/**
* The spec passed to the base cursor factory for {@code spec}; see {@link #planCursor}.
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I'd consider dropping this as unneeded

Comment on lines +82 to +84
* <b>Prefetch.</b> {@link #prefetch} shares the async path's machinery but, instead of a cursor holder, produces a
* {@link CursorPrefetch} that owns the bundle holds. A later {@link #makeCursorHolderAsync} for the same spec (made
* while the prefetch is still open) plans no downloads as everything is resident.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the intended contract around starting a cursor holder build when a prefetch is not done, if any? If such a thing does happen, wouldn't the holder build plan downloads for whatever is not pre-fetched yet? I suppose it wouldn't actually be downloaded because it would realize it is resident thanks to prefetch before kicking off its own download.

if (plan.bundles().isEmpty()) {
return CursorPrefetch.none();
}
final PendingDownloads pending = acquireHoldsAndSubmitRuns(plan.bundles());

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this can throw synchronously, correct? Does it doing so violate the best effort contract of CursorPrefetch that states:

<li>The handle is ready ({@link #isReady()}) once the warm-up is complete, whether it succeeded or failed;
 *   {@link #get()} returns {@link Stats} on success and throws the failure otherwise.</li>

Might we want to try/catch here and create a failed prefetch?

The planCurstorPrefetch above also could fail to plan. that seems potentially different in that it may be un-recoverable at cursor build time if it can't even plan now. so maybe it throwing eagerly is ok as long as it is handled nicely?

Comment on lines +35 to +38
* <li>Keep the handle open for as long as the warmed-up parts should stay resident. Closing it after it is ready
* releases the holds that pin them. The cursor build that benefits from the warm-up takes its own pins on the
* calling thread, so close the handle only once that {@code makeCursorHolderAsync} call has returned, or the parts
* may be evicted in between and loaded twice.</li>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are callers going to be fully responsible for responsible use of Prefetch handles, then? No real objection here, other than it just feels like an area to keep close eye on when creating followups that use this prefetch mechanism

Assertions.assertTrue(base.prefetchCanceled.get(), "closing the prefetch before it's ready cancels the base");
}
catch (Throwable t) {
prefetch.close();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: if the final assertion fails this will clobber the assertion fail reason with an Already Closed exception

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Approval Recommended Used when AI completes a review and reports no findings Area - Segment Format and Ser/De

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants