refactor(parquet): extract page_decode_nesting_state and compose full_page_decode_state replacing page_state_s

[vyasr]

Description

This PR completes the incremental narrowing pattern from #23471, #23479, #23495, and #23496 by retiring page_state_s entirely. It extracts page_decode_nesting_state (the nesting decode cache and pointer) and composes full_page_decode_state from page_decode_setup_state, page_decode_stream_state, page_decode_nesting_state, page_decode_progress_state, and page_decode_output_state. Every full-decode kernel (decode_page_data, decode_split_page_data_kernel, decode_page_data_generic, decode_delta_binary, decode_delta_byte_array, decode_delta_length_byte_array, compute_string_page_bounds, compute_page_sizes) now takes this composed state instead of the ad-hoc page_state_s, and the old struct is deleted.

The composition also folds page_state_s's stand-alone level-decoding fields (lvl_start[2], lvl_end) into the already-existing page_decode_stream_state::abs_lvl_start / abs_lvl_end arrays, and drops the unused first_output_value field. Together with the composition's tighter layout this removes 32 bytes of shared memory from every full-decode kernel on every generated architecture, with no register-count regressions.

A fresh cuobjdump -res-usage comparison against upstream/main shows the same 32-byte shmem reduction on all eight migrated kernels on every generated architecture. Register usage does not increase anywhere; one variant of decode_split_page_data_kernel on sm_86 drops by 8 registers:

Kernel	Arch summary	shmem delta	register changes
decode_page_data	all generated arch variants	-32 bytes	unchanged
decode_split_page_data_kernel	all generated arch variants	-32 bytes	unchanged except sm_86: one template variant 48 -> 40
decode_page_data_generic	all generated arch variants (44 template variants)	-32 bytes	unchanged
compute_page_sizes	all generated arch variants	-32 bytes	unchanged
compute_string_page_bounds	all generated arch variants	-32 bytes	unchanged
decode_delta_binary	all generated arch variants	-32 bytes	unchanged
decode_delta_byte_array	all generated arch variants	-32 bytes	unchanged
decode_delta_length_byte_array	all generated arch variants	-32 bytes	unchanged

Representative sm_80 measurements:

Kernel	shmem before	shmem after	delta	regs before	regs after
decode_page_data	4112	4080	-32	56	56
decode_split_page_data_kernel	4112	4080	-32	56	56
decode_page_data_generic (min variant)	2104	2072	-32	62	62
decode_page_data_generic (max variant)	13024	12992	-32	64	64
compute_page_sizes	3240	3208	-32	32	32
compute_string_page_bounds	3256	3224	-32	32	32
decode_delta_binary	2700	2668	-32	56	56
decode_delta_byte_array	5068	5036	-32	72	72
decode_delta_length_byte_array	3392	3360	-32	64	64

With this PR the page_state_s type is fully removed. All Parquet decode and preprocess kernels now use one of four purpose-built shared-memory states (level_scan_state, string_size_scan_state, string_offset_scan_state, full_page_decode_state), each holding only the substructs it actually needs.

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: 69f75c53-86ba-444e-8c77-f384166f3c99

📥 Commits

Reviewing files that changed from the base of the PR and between 2d1d02a and 4d53814.

📒 Files selected for processing (1)

• cpp/src/io/parquet/page_decode.cuh

---

📝 Walkthrough

Summary by CodeRabbit

• Refactor
  • Improved Parquet page decoding across nested, flat, delta, and string data workflows.
  • Streamlined page-boundary and containment handling for more consistent processing.
  • Added more focused processing paths for decoding, scanning, and preprocessing page data.
  • Preserved existing decoding behavior while improving handling of empty and partially bounded pages.

Walkthrough

This PR decomposes Parquet page decode state into composable structures. Decode and preprocessing helpers now accept generic state pointers. Nesting metadata uses the nested state layout. Bounds checks receive explicit page and row metadata.

Changes

Parquet page state refactor

Layer / File(s)	Summary
Composed state contracts and setup cpp/src/io/parquet/page_decode.cuh, cpp/src/io/parquet/page_state_composed.cuh, cpp/src/io/parquet/page_data.cuh	Page state is split into setup, nesting, progress, output, stream, and scan-state components. Setup and helper functions initialize or use available components.
Page bounds and preprocessing cpp/src/io/parquet/decode_preprocess.cu, cpp/src/io/parquet/page_string_decode.cu, cpp/src/io/parquet/page_delta_decode.cu	Preprocessing and string-size kernels use composed state storage. Bounds and containment helpers receive explicit page and column row metadata.
Fixed-width and delta page decoding cpp/src/io/parquet/decode_fixed.cu, cpp/src/io/parquet/page_data.cu, cpp/src/io/parquet/page_delta_decode.cu	Decode kernels use full_page_decode_state. Nesting, validity, progress, null handling, and output access use s->nesting.nesting_info.
String decode state access cpp/src/io/parquet/page_string_utils.cuh	String conversion and decoding helpers accept generic state pointers and use the composed nesting state.

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

Possibly related PRs

• rapidsai/cudf#23241: Introduces related page-bound and containment interfaces for Parquet decoding.
• rapidsai/cudf#23479: Directly overlaps the Parquet page-state decomposition and preprocessing changes.
• rapidsai/cudf#23496: Refactors the same Parquet decode state components and kernels.

Suggested reviewers: vuule, wence-, bdice, pointkernel

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% 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
Description check	✅ Passed	The description clearly explains the removal of page_state_s, the new composed states, affected kernels, and shared-memory improvements.
Title check	✅ Passed	The title clearly summarizes the main refactoring: extracting page_decode_nesting_state and replacing page_state_s with full_page_decode_state.
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

🧹 Nitpick comments (1)

cpp/src/io/parquet/page_decode.cuh (1)

1285-1292: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Remove the duplicate data_out assignment.

Line 1286 and Line 1292 store the same value into nesting_info->data_out. The second store is dead. It also suggests that the string_out assignment at Line 1288 depends on the order of the two stores, which it does not.

♻️ Proposed cleanup

             if (s->setup.col.column_data_base != nullptr) {
               nesting_info->data_out = static_cast<uint8_t*>(s->setup.col.column_data_base[idx]);
               if (s->setup.col.column_string_base != nullptr) {
                 nesting_info->string_out =
                   static_cast<uint8_t*>(s->setup.col.column_string_base[idx]);
               }
 
-              nesting_info->data_out = static_cast<uint8_t*>(s->setup.col.column_data_base[idx]);
-
               if (nesting_info->data_out != nullptr) {

🤖 Prompt for 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.

In `@cpp/src/io/parquet/page_decode.cuh` around lines 1285 - 1292, Remove the
redundant second assignment to nesting_info->data_out in the column data
initialization block, while preserving the first assignment and the conditional
nesting_info->string_out assignment.

🤖 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_decode.cuh`:
- Around line 184-190: Update the Doxygen parameter lists for is_bounds_page,
is_page_contained, and page_has_rows_to_process to document PageInfo const& page
and size_t chunk_start_row, and remove the obsolete `@param` s entry. Keep the
remaining parameter descriptions accurate and ensure every parameter in each
signature is documented.

---

Nitpick comments:
In `@cpp/src/io/parquet/page_decode.cuh`:
- Around line 1285-1292: Remove the redundant second assignment to
nesting_info->data_out in the column data initialization block, while preserving
the first assignment and the conditional nesting_info->string_out assignment.

🪄 Autofix

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: 117517d7-63cf-42d6-83c0-a7684063f1a6

📥 Commits

Reviewing files that changed from the base of the PR and between 7ec9b08 and 2d1d02a.

📒 Files selected for processing (9)

• 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_state_composed.cuh
• cpp/src/io/parquet/page_string_decode.cu
• cpp/src/io/parquet/page_string_utils.cuh

[vyasr]

/merge