Skip to content

Add sync-first TDS cursor APIs - #306

Draft
Saurabh Singh (saurabh500) wants to merge 2 commits into
dev/saurabh500/tds-cursor-hot-pathfrom
dev/saurabh500/tds-sync-first-cursor
Draft

Add sync-first TDS cursor APIs#306
Saurabh Singh (saurabh500) wants to merge 2 commits into
dev/saurabh500/tds-cursor-hot-pathfrom
dev/saurabh500/tds-sync-first-cursor

Conversation

@saurabh500

Copy link
Copy Markdown
Contributor

Description

Layer 3 of a separate experimental performance stack.

Adds explicit non-blocking pull-cursor APIs to TdsClient:

  • try_next_row_cursor
  • try_read_row_column
  • CursorPoll::{Ready, Pending}

The ready path parses already-buffered ROW/NBCROW headers and common unencrypted non-PLP scalar, string, and binary columns without entering Tokio or constructing an async cursor future. A pending attempt consumes neither transport bytes nor cursor state; callers continue with the existing async next_row_cursor / read_row_column methods.

Strict row-at-a-time and column-at-a-time streaming is preserved. This does not batch, prefetch, or materialize whole rows.

Stack parent: #304

Correctness boundaries

  • PLP, encrypted, skipped, unsupported, incomplete, and control-token paths remain on the existing async implementation.
  • Buffered decoding commits TdsReadBuffer consumption only after a complete value is available.
  • Packet-boundary and NBCROW bitmap misses leave partial bytes intact for async continuation.
  • Cancellation is deferred to the async path without consuming state.
  • Explicit zero-timeout budgets retain ready-first semantics.

Measurement context

A preceding proof-of-concept that synchronously polled cursor futures demonstrated a large opportunity, but depended on executor/waker behavior. This layer replaces that evidence-only mechanism with a cursor-specific, documented TDS state-machine API. Final ODBC throughput is intentionally deferred to the next layer that adopts these APIs.

Related Issues

Related to #304.

Validation

  • cargo fmt --all -- --check
  • 13 focused sync-cursor, buffered-decoder, packet-boundary, NBCROW, timeout, and cancellation tests
  • cargo clippy -p mssql-tds --frozen --all-features --all-targets -- -D warnings
  • RUSTFLAGS='--cfg fuzzing' cargo check -p mssql-tds --lib
  • Full mssql-tds library suite: 1,681 passed; four pre-existing certificate-fixture tests failed because tests/test_certificates/valid_cert.pem and .der are absent

Checklist

  • Formatting passes
  • Clippy passes with warnings denied
  • Focused tests pass
  • Strict per-row/per-column streaming is preserved
  • Pending paths are non-destructive

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@saurabh500
Saurabh Singh (saurabh500) changed the base branch from saurabh500-experimental-tds-perf-baseline to dev/saurabh500/tds-cursor-hot-path August 15, 2026 18:30
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 74171bdf-edce-41bc-83e0-bece80fc85ca
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant