refactor(parquet): extract page_decode_setup_state substruct

[vyasr]

Description

This PR looks large, but is entirely trivial. It simply moves some fields of page_state_s into a new struct, and an instance of that new struct is added to page_state_s, requiring every call site to now access the field through that struct member. Once this PR is merged, subsequent PRs will be able to introduce other such structs while simultaneously modifying device functions and kernels to actually reduce the shared memory footprint of those kernels (and eventually, to simplify the implementation of some of these common helper device functions), but this first PR is purely setup for that.

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8eccf896-00c4-48cf-94eb-933c9d13e8b0

📥 Commits

Reviewing files that changed from the base of the PR and between 3a6b48e and 9e45f1a.

📒 Files selected for processing (1)

• cpp/src/io/parquet/page_delta_decode.cu

🚧 Files skipped from review as they are similar to previous changes (1)

• cpp/src/io/parquet/page_delta_decode.cu

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes
  • Improved reliability and consistency of GPU-accelerated Parquet decoding across fixed-width, string (including large strings), dictionary, boolean, and delta-encoded data.
  • Corrected handling of skipped rows/values, nulls, page boundaries, and offset computations, improving results on nested and list structures.
  • Improved decoding bounds, validity/index generation, and error propagation during page preprocessing and decode, reducing failures on complex files.

Walkthrough

Parquet GPU decoding now stores page, column, range, sizing, and error metadata under page_state_s::setup. Preprocessing, fixed-width, standard, DELTA, and string decoding paths consistently consume the nested state.

Changes

Parquet decode state migration

Layer / File(s)	Summary
Setup-state contract and initialization cpp/src/io/parquet/page_decode.cuh	Adds page_decode_setup_state, nests metadata under page_state_s::setup, and updates setup initialization, level decoding, sizing, dictionary handling, offsets, and errors.
Page-size and string-bound preprocessing cpp/src/io/parquet/decode_preprocess.cu, cpp/src/io/parquet/page_string_decode.cu	Uses setup-scoped state for page sizes, pruned-page batches, level preprocessing, string bounds, and string offsets.
Fixed-width and generic value decoding cpp/src/io/parquet/decode_fixed.cu	Migrates fixed-width value, validity, row-index, skip-ahead, dictionary, boolean, string, null-fill, and decode-loop state accesses to setup.
Standard page decode dispatch cpp/src/io/parquet/page_data.cu, cpp/src/io/parquet/page_data.cuh	Updates standard page dispatch, type selection, decimal handling, nesting offsets, string categorization, timestamp dispatch, and error propagation.
DELTA page decoding cpp/src/io/parquet/page_delta_decode.cu	Migrates DELTA binary and string decoding bounds, counters, skipped values, buffers, offsets, and errors to setup-backed state.
String offset and output helpers cpp/src/io/parquet/page_string_utils.cuh	Updates string offset conversion, large-string initialization, destination indexing, fixed-length-byte-array dispatch, and split-stream sizing.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• rapidsai/cudf#23241: Touches connected Parquet string bounds and page-containment logic.
• rapidsai/cudf#23314: Modifies the same DELTA decode kernels.
• rapidsai/cudf#23470: Refactors related page_state_s fields in page_decode.cuh.

Suggested labels: cuIO

Suggested reviewers: qbacpey, mattgara, vuule

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 17.39% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: introducing page_decode_setup_state and refactoring parquet decode state access.
Description check	✅ Passed	The description matches the changeset and accurately describes the state refactor and its setup-only purpose.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cpp/src/io/parquet/page_delta_decode.cu`:
- Around line 504-506: Update the use_char_ll heuristic in the page delta decode
setup to guard against s->setup.page.num_valids being zero. Select the
non-character-parallel path when there are no valid values, and only perform the
average-length division when num_valids is nonzero.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 62550d8d-e039-4670-b07d-ad2ae1629143

📥 Commits

Reviewing files that changed from the base of the PR and between 982a387 and eab52ec.

📒 Files selected for processing (8)

• cpp/src/io/parquet/decode_fixed.cu
• cpp/src/io/parquet/decode_preprocess.cu
• cpp/src/io/parquet/page_data.cu
• cpp/src/io/parquet/page_data.cuh
• cpp/src/io/parquet/page_decode.cuh
• cpp/src/io/parquet/page_delta_decode.cu
• cpp/src/io/parquet/page_string_decode.cu
• cpp/src/io/parquet/page_string_utils.cuh

[mhaseeb123]

@vyasr I think there's a comment from @coderabbitai that might be worth looking at. Also please note we might want to let #23314 merge (touches some common code in this PR) and apply changes to the new code as well

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

repo="rapidsai/cudf"

echo "== PR `#23471` CodeRabbit review comments =="
gh api --paginate "repos/${repo}/pulls/23471/comments" \
  --jq '.[] | select(.user.login == "coderabbitai[bot]" or .user.login == "coderabbitai") | {url: .html_url, path: .path, line: .line, body: .body}' || true

echo
echo "== PR `#23471` general CodeRabbit comments =="
gh api --paginate "repos/${repo}/issues/23471/comments" \
  --jq '.[] | select(.user.login == "coderabbitai[bot]" or .user.login == "coderabbitai") | {url: .html_url, body: .body}' || true

echo
echo "== PR `#23314` status and changed files =="
gh pr view 23314 --repo "$repo" --json state,mergedAt,mergeable,baseRefName,headRefName,url,title \
  --jq '{state, mergedAt, mergeable, baseRefName, headRefName, url, title}'
gh pr diff 23314 --repo "$repo" --name-only

Length of output: 10772

---

@mhaseeb123 Confirmed. The outstanding CodeRabbit finding is a valid-looking guard in cpp/src/io/parquet/page_delta_decode.cu at Lines 505–506: the average string-length heuristic must not divide by s->setup.page.num_valids when an all-null page has zero valid values.

PR #23314 is still open and mergeable, and it modifies that same DELTA decode file (as well as page_string_decode.cu). I agree with merging #23314 first, then rebasing this PR and applying/verifying the zero-valid-value guard in the updated code to avoid duplicate conflict resolution.

---

✏️ Learnings added

Learnt from: mhaseeb123
URL: https://github.com/rapidsai/cudf/pull/23471

Timestamp: 2026-07-29T18:34:52.092Z
Learning: For the RAPIDS cuDF Parquet decoder, PR `#23314` (`parquet-delta-large-mini-blocks`) modifies the DELTA decode kernels, including `cpp/src/io/parquet/page_delta_decode.cu`; dependent refactors should be rebased after it merges and revalidate any changes in those shared paths.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

[vyasr]

/merge