From 0a54af9765e82500e1e35dd758f84afdf1dbda6e Mon Sep 17 00:00:00 2001 From: Christoph Pader Date: Mon, 16 Nov 2026 16:21:20 +0100 Subject: [PATCH] perf: run prepared async executions on the connection worker A prepared statement's executeAsync and executeRawAsync ran on Nitro's shared thread pool, which does not keep call order, so the JavaScript queue had to run them one at a time and every execution waited for the previous result. They now run on the connection's FIFO worker like executeAsync, and the queue treats them as statements, so several can be submitted without waiting. The worker still runs them one at a time in call order. Co-Authored-By: Claude Opus 5.5 --- .../docs/guides/prepared-statements.mdx | 2 +- .../cpp/NitroSQLiteOperations.cpp | 4 ++ .../cpp/NitroSQLiteOperations.hpp | 2 + .../cpp/hybridObjects/HybridNitroSQLite.cpp | 31 +------------ .../HybridNitroSQLitePreparedStatement.cpp | 11 +++-- .../HybridNitroSQLitePreparedStatement.hpp | 4 +- .../NitroSQLiteConnectionOperation.hpp | 45 +++++++++++++++++++ .../src/__tests__/prepare.test.ts | 23 ++++++++++ .../src/operations/prepare.ts | 8 ++-- .../NitroSQLitePreparedStatement.nitro.ts | 3 +- 10 files changed, 92 insertions(+), 41 deletions(-) create mode 100644 packages/react-native-nitro-sqlite/cpp/hybridObjects/NitroSQLiteConnectionOperation.hpp diff --git a/docs/content/docs/guides/prepared-statements.mdx b/docs/content/docs/guides/prepared-statements.mdx index ed1e8fe0..297710a9 100644 --- a/docs/content/docs/guides/prepared-statements.mdx +++ b/docs/content/docs/guides/prepared-statements.mdx @@ -48,7 +48,7 @@ try { ## Connection ordering and cleanup -On a managed connection, `executeAsync()` reserves that connection's queue until it completes. It waits for earlier work and prevents later work from starting. While async work is pending, synchronous `prepare()`, `execute()`, `finalize()`, and `close()` on that connection throw a busy error. Await the last execution before finalizing, then finalize before closing the connection. `isFinalized` reports whether the statement has been finalized; executing it afterward throws. +On a managed connection, `executeAsync()` runs in submission order with the connection's other async calls. It waits for earlier work, and later work starts only after it completes. While async work is pending, synchronous `prepare()`, `execute()`, `finalize()`, and `close()` on that connection throw a busy error. Await the last execution before finalizing, then finalize before closing the connection. `isFinalized` reports whether the statement has been finalized; executing it afterward throws. Do not await a prepared statement's `executeAsync()` from inside `db.transaction()` on the same connection. It waits behind the transaction, while the transaction waits for your callback. Use the callback's `tx.execute()` or `tx.executeAsync()` instead. See [transactions](/docs/guides/transactions) and [connection ordering](/docs/guides/sync-and-async#connection-ordering). diff --git a/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.cpp b/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.cpp index 798bce81..7a12d955 100644 --- a/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.cpp +++ b/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.cpp @@ -455,6 +455,10 @@ NitroSQLiteRawQueryResult SQLitePreparedStatement::executeRaw(const std::optiona return executeBound(params, executeStatementRaw); } +const SQLiteConnectionPtr& SQLitePreparedStatement::connection() const noexcept { + return _state->connection; +} + void SQLitePreparedStatement::finalize() { std::lock_guard lock(_state->mutex); std::lock_guard connectionLock(_state->connection->mutex); diff --git a/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.hpp b/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.hpp index 9631c34e..369f6055 100644 --- a/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.hpp +++ b/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.hpp @@ -33,6 +33,8 @@ class SQLitePreparedStatement { void finalize(); /** Check whether the native statement has been released. */ bool isFinalized() const; + /** The connection this statement was prepared on. */ + const SQLiteConnectionPtr& connection() const noexcept; /** Report this object's native memory size to the Nitro runtime. */ size_t getExternalMemorySize() const noexcept; diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp index fd2c3c5d..342ba201 100644 --- a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp @@ -7,6 +7,7 @@ #include "../NitroSQLiteMacros.hpp" #include "../NitroSQLiteOperations.hpp" #include "HybridNitroSQLitePreparedStatement.hpp" +#include "NitroSQLiteConnectionOperation.hpp" #include #include #include @@ -60,36 +61,6 @@ static std::vector copyArrayBufferParamsForBackground(const std::vec return copiedCommands; } -template -static std::shared_ptr> enqueueConnectionOperation(const SQLiteConnectionPtr& connection, Operation&& operation) { - auto promise = Promise::create(); - try { - connection->enqueueAsync([promise, operation = std::forward(operation)]() mutable { - std::optional result; - try { - result.emplace(operation()); - } catch (...) { - promise->reject(std::current_exception()); - return; - } - // Resolving may dispatch to JavaScript and throw after the native promise - // has settled. Do not try to reject that same promise again. - try { - promise->resolve(std::move(*result)); - } catch (...) { - if (promise->isPending()) { - promise->reject(std::current_exception()); - return; - } - throw; - } - }); - } catch (...) { - promise->reject(std::current_exception()); - } - return promise; -} - const std::string getDocPath(const std::optional& location) { if (location && location->find('\0') != std::string::npos) { throw NitroSQLiteException(NitroSQLiteExceptionType::DatabaseCannotBeOpened, "Database location contains a NUL byte"); diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.cpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.cpp index 70003b71..133ca35a 100644 --- a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.cpp +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.cpp @@ -1,4 +1,5 @@ #include "HybridNitroSQLitePreparedStatement.hpp" +#include "NitroSQLiteConnectionOperation.hpp" #include namespace margelo::nitro::rnnitrosqlite { @@ -38,8 +39,10 @@ HybridNitroSQLitePreparedStatement::executeAsync(const std::optional::async( - [statement, copiedParams]() -> NitroSQLiteQueryResult { return statement->execute(copiedParams); }); + // The connection's worker keeps executions in call order, so JavaScript can submit several without + // waiting for each result. + return enqueueConnectionOperation( + statement->connection(), [statement, copiedParams]() -> NitroSQLiteQueryResult { return statement->execute(copiedParams); }); } NitroSQLiteRawQueryResult HybridNitroSQLitePreparedStatement::executeRaw(const std::optional& params) { @@ -51,8 +54,8 @@ HybridNitroSQLitePreparedStatement::executeRawAsync(const std::optional::async( - [statement, copiedParams]() -> NitroSQLiteRawQueryResult { return statement->executeRaw(copiedParams); }); + return enqueueConnectionOperation( + statement->connection(), [statement, copiedParams]() -> NitroSQLiteRawQueryResult { return statement->executeRaw(copiedParams); }); } void HybridNitroSQLitePreparedStatement::finalize() { diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.hpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.hpp index c5e65822..0a09c138 100644 --- a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.hpp +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.hpp @@ -15,11 +15,11 @@ class HybridNitroSQLitePreparedStatement : public HybridNitroSQLitePreparedState /** Execute with new bindings on the calling thread. */ NitroSQLiteQueryResult execute(const std::optional& params) override; - /** Execute with new bindings on a background thread. */ + /** Execute with new bindings on the connection's worker, in call order. */ std::shared_ptr> executeAsync(const std::optional& params) override; /** Execute with new bindings on the calling thread, returning rows as arrays of column values. */ NitroSQLiteRawQueryResult executeRaw(const std::optional& params) override; - /** Execute with new bindings on a background thread, returning rows as arrays of column values. */ + /** Execute with new bindings on the connection's worker, returning rows as arrays of column values. */ std::shared_ptr> executeRawAsync(const std::optional& params) override; /** Release the native statement. */ void finalize() override; diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/NitroSQLiteConnectionOperation.hpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/NitroSQLiteConnectionOperation.hpp new file mode 100644 index 00000000..4886f8ef --- /dev/null +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/NitroSQLiteConnectionOperation.hpp @@ -0,0 +1,45 @@ +#pragma once + +#include "../NitroSQLiteDatabaseConnections.hpp" +#include +#include +#include +#include +#include + +namespace margelo::nitro::rnnitrosqlite { + +/** Run @p operation on the connection's FIFO worker and settle the returned promise with its result. + * Calls on one connection run in submission order, one at a time. + */ +template +std::shared_ptr> enqueueConnectionOperation(const SQLiteConnectionPtr& connection, Operation&& operation) { + auto promise = Promise::create(); + try { + connection->enqueueAsync([promise, operation = std::forward(operation)]() mutable { + std::optional result; + try { + result.emplace(operation()); + } catch (...) { + promise->reject(std::current_exception()); + return; + } + // Resolving may dispatch to JavaScript and throw after the native promise + // has settled. Do not try to reject that same promise again. + try { + promise->resolve(std::move(*result)); + } catch (...) { + if (promise->isPending()) { + promise->reject(std::current_exception()); + return; + } + throw; + } + }); + } catch (...) { + promise->reject(std::current_exception()); + } + return promise; +} + +} // namespace margelo::nitro::rnnitrosqlite diff --git a/packages/react-native-nitro-sqlite/src/__tests__/prepare.test.ts b/packages/react-native-nitro-sqlite/src/__tests__/prepare.test.ts index f6902e6c..abb99d91 100644 --- a/packages/react-native-nitro-sqlite/src/__tests__/prepare.test.ts +++ b/packages/react-native-nitro-sqlite/src/__tests__/prepare.test.ts @@ -97,6 +97,29 @@ it('keeps synchronous calls from overtaking an asynchronous execution', async () statement.finalize() }) +it('submits several executions before waiting for native results', async () => { + const native = mockStatement() + let finishFirst: (() => void) | undefined + jest.mocked(native.executeAsync).mockImplementationOnce( + () => + new Promise((resolve) => { + finishFirst = () => resolve(nativeResult([{ value: 1 }])) + }), + ) + jest.mocked(HybridNitroSQLite.prepare).mockReturnValue(native) + const statement = prepare(dbName, query) + + const first = statement.executeAsync([1]) + const second = statement.executeAsync([2]) + const raw = statement.executeRawAsync([3]) + expect(native.executeAsync).toHaveBeenCalledTimes(2) + expect(native.executeRawAsync).toHaveBeenCalledTimes(1) + + finishFirst!() + await Promise.all([first, second, raw]) + statement.finalize() +}) + it('runs raw executions through the statement queue', async () => { const native = mockStatement() jest.mocked(HybridNitroSQLite.prepare).mockReturnValue(native) diff --git a/packages/react-native-nitro-sqlite/src/operations/prepare.ts b/packages/react-native-nitro-sqlite/src/operations/prepare.ts index bb82f14d..20011a7e 100644 --- a/packages/react-native-nitro-sqlite/src/operations/prepare.ts +++ b/packages/react-native-nitro-sqlite/src/operations/prepare.ts @@ -9,7 +9,7 @@ import type { import type { NitroSQLiteRawQueryResult } from '../specs/NitroSQLiteQueryResult.nitro' import { buildJSQueryResult } from './execute' import { rejectWithNitroSQLiteError } from '../nativePromise' -import { queueOperationAsync, startOperationSync } from '../DatabaseQueue' +import { queueStatementAsync, startOperationSync } from '../DatabaseQueue' import type { DatabaseQueueKey } from '../DatabaseQueue' /** @@ -47,10 +47,12 @@ export function prepare( } }, // Chained instead of `async`, which would add promise layers to every execution. + // Native code runs executions on the connection's worker in call order, so they + // queue as statements and several can be submitted without waiting for each result. executeAsync: ( params?: SQLiteQueryParams, ): Promise> => - queueOperationAsync(queueKey, () => + queueStatementAsync(queueKey, () => nativeStatement .executeAsync(params) .then((result) => buildJSQueryResult(result)), @@ -67,7 +69,7 @@ export function prepare( executeRawAsync: ( params?: SQLiteQueryParams, ): Promise => - queueOperationAsync(queueKey, () => + queueStatementAsync(queueKey, () => nativeStatement.executeRawAsync(params), ).catch(rejectWithNitroSQLiteError), finalize: () => { diff --git a/packages/react-native-nitro-sqlite/src/specs/NitroSQLitePreparedStatement.nitro.ts b/packages/react-native-nitro-sqlite/src/specs/NitroSQLitePreparedStatement.nitro.ts index e4ce3c62..c8c287bc 100644 --- a/packages/react-native-nitro-sqlite/src/specs/NitroSQLitePreparedStatement.nitro.ts +++ b/packages/react-native-nitro-sqlite/src/specs/NitroSQLitePreparedStatement.nitro.ts @@ -20,7 +20,8 @@ export interface NitroSQLitePreparedStatement * @returns Native query rows, affected row count, insert ID, and metadata. */ execute(params?: SQLiteQueryParams): NitroSQLiteQueryResult - /** Execute on a background thread, replacing the previous parameter bindings. + /** Execute on the connection's background thread, replacing the previous parameter bindings. + * Executions run in call order with the connection's other async calls. * Rejects after finalization or connection closure. * @param params Values bound to positional placeholders. * @returns A promise of the native query result.