Release the GVL when executing a prepared statement.

[doxavore]

This change allows the Ruby VM to continue executing other Ruby threads while the DuckDB prepared statement is being executed.

There are many other methods that are candidates for this same treatment. This PR addresses only execution of a prepared statement, which is also what DuckDB::Connection#query uses. If accepted, we could adopt a similar approach for other high-value functions.

Ideally, we'd also be able to give Ruby the duckdb_interrupt function to handle signals, etc, but it seems there is nothing in the DuckDB C API that lets us interrupt a prepared statement, only a connection. (And it doesn't seem safe to interrupt a connection without reliably being able to know our given prepared statement is the active query on the connection.)

Locally, this doesn't seem to have an effect on the performance of benchmarks, but presumably someone doing a whole lot of tiny transactions may be better able to detect it.

This fixes #873 specifically, but we'll want to follow up with more if we determine this is a path we want to take.

Summary by CodeRabbit

• New Features

  • Enabled non-blocking execution for prepared statements, improving responsiveness and performance.
  • Enhanced error reporting to provide clearer feedback on execution issues.

• Chores

  • Updated threading support to better manage concurrent operations.

[coderabbitai]

Walkthrough

This PR introduces a new structure (duckdb_prepared_statement_execute_nogvl_args) and a new function (duckdb_prepared_statement_execute_nogvl) in the DuckDB C extension to execute prepared statements without blocking the Ruby VM. The implementation makes use of rb_thread_call_without_gvl to manage the execution context, and updates error handling to capture the execution state correctly. Additionally, the header file ruby/thread.h is included in the Ruby interface header to support threading functionality.

Changes

File	Change Summary
ext/duckdb/prepared_statement.c	Added new structure duckdb_prepared_statement_execute_nogvl_args and function duckdb_prepared_statement_execute_nogvl; updated error handling in duckdb_prepared_statement_execute to use the new structure.
ext/duckdb/ruby-duckdb.h	Included ruby/thread.h to provide threading support within the Ruby environment.

Sequence Diagram(s)

sequenceDiagram
    participant RubyThread as Ruby Thread
    participant GVL as Ruby VM (GVL)
    participant Exec as execute_nogvl
    participant DB as DuckDB Statement

    RubyThread->>GVL: Call execute prepared statement
    GVL->>Exec: Release GVL via rb_thread_call_without_gvl
    Exec->>DB: Execute prepared statement
    DB-->>Exec: Return result or error
    Exec-->>GVL: Return execution outcome
    GVL-->>RubyThread: Resume with result/error

Loading

Assessment against linked issues

Objective	Addressed	Explanation
Use rb_thread_call_without_gvl to release the GVL during long I/O calls (#873)	✅

Possibly related issues

• use duckdb_extension.h when building ruby-duckdb native library #882: This issue focuses on using duckdb_extension.h for building the native library; the current changes concentrate on non-blocking execution and do not address header deprecation or substitution.

Poem

I'm a rabbit in the code garden, so spry,
Hopping through threads with a gleam in my eye.
Prepared statements now skip the wait,
Releasing the GVL, they execute first-rate.
With non-blocking leaps and error fixes in sight,
I celebrate these changes from morning till night!
🐇✨

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d8100e4 and 65ae079.

📒 Files selected for processing (2)

• ext/duckdb/prepared_statement.c (1 hunks)
• ext/duckdb/ruby-duckdb.h (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (18)

• GitHub Check: test (head, 1.0.0)
• GitHub Check: test (head, 1.1.1)
• GitHub Check: test (head, 1.1.3)
• GitHub Check: test (head, 1.2.0)
• GitHub Check: test (mingw, 1.0.0)
• GitHub Check: test (mingw, 1.1.1)
• GitHub Check: test (mingw, 1.1.3)
• GitHub Check: test (mingw, 1.2.0)
• GitHub Check: test (3.3.6, 1.0.0)
• GitHub Check: test (3.3.6, 1.1.1)
• GitHub Check: test (3.3.6, 1.1.3)
• GitHub Check: test (3.3.6, 1.2.0)
• GitHub Check: test (3.2.6, 1.0.0)
• GitHub Check: test (3.2.6, 1.1.1)
• GitHub Check: test (3.2.6, 1.1.3)
• GitHub Check: test (3.2.6, 1.2.0)
• GitHub Check: test (3.1.6, 1.1.3)
• GitHub Check: test (3.1.6, 1.2.0)

🔇 Additional comments (7)

ext/duckdb/prepared_statement.c (6)

105-111: Struct creation looks good.
The struct cleanly encapsulates all required state for non-blocking execution, and the field naming is clear.

---

112-118: Non-blocking function is well-structured.
No Ruby calls are performed inside the no-GVL function, which aligns with best practices for rb_thread_call_without_gvl.

---

122-122: Local error pointer declared.
Declaring this pointer improves clarity in subsequent error handling.

---

128-133: Argument initialization is correct.
Defaulting retval to DuckDBError is a safe approach, and fields are appropriately assigned.

---

134-135: Releasing the GVL.
Using rb_thread_call_without_gvl is a solid choice for concurrency, allowing other Ruby threads to run during query execution.

---

137-145: Error handling is thorough.
Retrieving the error from duckdb_result_error or falling back to duckdb_prepare_error ensures complete error diagnostics.

ext/duckdb/ruby-duckdb.h (1)

8-8: Thread header inclusion is appropriate.
Including ruby/thread.h is necessary to safely use rb_thread_call_without_gvl.

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR. (Beta)
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[suketa]

@doxavore

Thank you for your great work!!!