From 53f027bb440e392bb6a9d2f302ffd995f5749417 Mon Sep 17 00:00:00 2001 From: Glenn444 Date: Fri, 16 Oct 2026 23:52:22 +0300 Subject: [PATCH 1/5] Join the connection's worker thread on close instead of at GC close(), delete() and invalidate() drained the ThreadPool but left its worker running; it was only joined in ~ThreadPool, when the last shared_ptr (JS object, prepared statements, pending promise tasks) was released. Apps that open/close repeatedly in a long-lived process kept one idle thread per closed database until GC (an iOS background kill had 1,006 idle do_work threads). - ThreadPool::shutdown(): sets done under the mutex, wakes and joins the worker; idempotent and safe to call concurrently. close/delete/ invalidate call it after wait_finished(); ~ThreadPool calls it too. - queue_work on a shut pool throws (callers queue from a Promise executor, so the promise rejects instead of never settling). - A task that drops the last reference to its own pool no longer self-joins (std::system_error -> terminate): the worker detaches and do_work returns without touching the freed pool. Fixes #469 Co-Authored-By: Claude Opus 5.5 --- cpp/OPDatabase.cpp | 4 ++++ cpp/OPThreadPool.cpp | 54 ++++++++++++++++++++++++++++++++++++++------ cpp/OPThreadPool.hpp | 10 ++++++++ 3 files changed, 61 insertions(+), 7 deletions(-) diff --git a/cpp/OPDatabase.cpp b/cpp/OPDatabase.cpp index c4a21bb0..1fbf4224 100644 --- a/cpp/OPDatabase.cpp +++ b/cpp/OPDatabase.cpp @@ -363,6 +363,8 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, // Without this, a queued/running execute() on the thread pool may // dereference the freed sqlite3* pointer → heap corruption / SIGABRT. thread_pool->wait_finished(); + // Free the worker thread now rather than when the JS object is collected. + thread_pool->shutdown(); release_hooks(); #ifdef OP_SQLITE_USE_LIBSQL opsqlite_libsql_close(db); @@ -420,6 +422,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, // Drain any in-flight async queries before closing/removing the db handle. // Without this, queued/running work may dereference a freed sqlite handle. thread_pool->wait_finished(); + thread_pool->shutdown(); if (delete_db_name.empty()) { throw std::runtime_error("[op-sqlite][delete] delete() is not supported " @@ -891,6 +894,7 @@ void OPDatabase::invalidate() { // Drain in-flight thread pool work before closing the db handle. thread_pool->wait_finished(); + thread_pool->shutdown(); release_hooks(); #ifdef OP_SQLITE_USE_LIBSQL diff --git a/cpp/OPThreadPool.cpp b/cpp/OPThreadPool.cpp index 6b7fd24a..621bd8f3 100644 --- a/cpp/OPThreadPool.cpp +++ b/cpp/OPThreadPool.cpp @@ -1,5 +1,7 @@ #include "OPThreadPool.hpp" +#include + namespace opsqlite { ThreadPool::ThreadPool() : done(false) { @@ -27,23 +29,47 @@ ThreadPool::ThreadPool() : done(false) { } } +// Set on a worker whose own pool was destroyed by the task it just ran (the +// task held the last shared_ptr to the pool, e.g. a promise task). do_work() +// must then return without touching the freed pool. +static thread_local bool pool_destroyed_on_worker = false; + // The destructor joins all the threads so the process (or in our RN case, this // main-thread/runtime generation) can exit gracefully. This will be executed if // there is any exception (e.g. creating the threads) -ThreadPool::~ThreadPool() { - // So threads know it's time to shut down - done = true; +ThreadPool::~ThreadPool() { shutdown(); } + +void ThreadPool::shutdown() { + std::vector to_join; + { + std::lock_guard g(work_queue_mutex); + if (shut_down) { + return; + } + shut_down = true; + // Set under the mutex so a worker between its predicate check and its + // wait cannot miss the wake-up below. + done = true; + to_join.swap(threads); + } // Wake up all the threads, so they can finish and be joined work_pending.notify_all(); - for (auto &thread : threads) { - if (thread.joinable()) { + for (auto &thread : to_join) { + if (!thread.joinable()) { + continue; + } + if (thread.get_id() == std::this_thread::get_id()) { + // The last reference was dropped by a task on this very worker: joining + // ourselves throws std::system_error (terminate). Detach; do_work() + // returns as soon as it sees the flag. + thread.detach(); + pool_destroyed_on_worker = true; + } else { thread.join(); } } - - threads.clear(); } // This function will be called by the server every time there is a request @@ -52,6 +78,13 @@ void ThreadPool::queue_work(const std::function &task) { // Grab the mutex std::lock_guard g(work_queue_mutex); + // A shut down pool has no worker: a task queued now would never run and its + // promise would never settle. Callers queue from a Promise executor, so the + // throw rejects the promise. + if (done) { + throw std::runtime_error("[op-sqlite] database is closed"); + } + // Push the request to the queue work_queue.push(task); @@ -92,6 +125,13 @@ void ThreadPool::do_work() { // while task-owned resources are still pending destruction. task = nullptr; + // Releasing the task may have destroyed this pool (it held the last + // reference). If so, `this` is gone: touch nothing. + if (pool_destroyed_on_worker) { + pool_destroyed_on_worker = false; + return; + } + { std::lock_guard g(work_queue_mutex); --busy; diff --git a/cpp/OPThreadPool.hpp b/cpp/OPThreadPool.hpp index 2294f794..6912790f 100644 --- a/cpp/OPThreadPool.hpp +++ b/cpp/OPThreadPool.hpp @@ -18,6 +18,13 @@ class ThreadPool { ~ThreadPool(); void queue_work(const std::function &task); void wait_finished(); + // Stops and joins the worker now. Called by close()/delete()/invalidate(): + // the pool is shared with prepared statements and pending promises, so the + // destructor may run much later (only when the JS object is garbage + // collected), and until then every closed database kept a parked thread. + // Idempotent and safe to call concurrently. Work queued afterwards is + // rejected. + void shutdown(); private: unsigned int busy{}; @@ -39,6 +46,9 @@ class ThreadPool { // Atomic because do_work() reads it in `while (!done)` outside the mutex. std::atomic done; + // Set (under work_queue_mutex) by the first shutdown(); later calls return. + bool shut_down{false}; + // Function used by the threads to grab work from the queue void do_work(); }; From deb3846a8de3a9342ebac2238803dd02cd25daff Mon Sep 17 00:00:00 2001 From: Glenn444 Date: Sat, 24 Oct 2026 21:10:45 +0300 Subject: [PATCH 2/5] ThreadPool: drain on shutdown, wait for concurrent joins, never self-join Addresses the review of #470 (points 1-4 and 6-10). shutdown() is now the single way to stop a pool. It refuses new work, lets the worker run every task that is already queued (so no promise is left unsettled and a later wait_finished() cannot block), then joins. close(), delete() and invalidate() call just that instead of wait_finished() followed by shutdown(). - Concurrent callers: the join runs under join_mutex, so a second shutdown() (or the destructor after it) returns only once the first caller's join has completed, never while the worker still uses the mutex, condition variable or queue. - Called on the worker itself (e.g. a database invalidated from a task), shutdown() does not join: it runs the remaining queued tasks inline and returns. do_work() then releases `busy` as usual and exits, and a later shutdown() or the destructor joins it. The thread_local self-release flag and the detach branch are gone; the header documents the rule that makes them unnecessary: a task must never own its pool (none does: tasks capture the database or statement by raw pointer). - `shut_down` is dropped; `done` is the only flag and is now read under the mutex only. - queue_work() on a stopped pool throws ThreadPoolStoppedError ("[op-sqlite] thread pool is stopped"). promisify and flushPendingReactiveQueries map it to the same "[op-sqlite][] database is closed" error as throw_if_closed, thrown from the Promise executor so the promise rejects. promisify takes the function name for that. - delete() checks the remote-only case before invalidating, interrupting or stopping the pool, so an unsupported delete() leaves the database open and usable. - The constructor joins any thread it already started if a later one fails to start: the destructor does not run when a constructor throws. scripts/thread_pool_check.cpp (run by scripts/test-thread-pool.sh, under TSan and ASan) covers 300 closed-but-referenced pools, queue_work after shutdown, draining queued tasks on shutdown() and in the destructor, two concurrent shutdowns followed by the destructor, shutdown() from a task on the worker, and a constructor whose thread cannot start. Co-Authored-By: Claude Fable 5.1 --- cpp/OPDatabase.cpp | 43 +-- cpp/OPMacros.hpp | 1 + cpp/OPPreparedStatementHostObject.cpp | 4 +- cpp/OPThreadPool.cpp | 124 +++++---- cpp/OPThreadPool.hpp | 59 +++- cpp/OPUtils.cpp | 21 +- cpp/OPUtils.hpp | 10 +- scripts/test-thread-pool.sh | 25 ++ scripts/thread_pool_check.cpp | 374 ++++++++++++++++++++++++++ 9 files changed, 570 insertions(+), 91 deletions(-) create mode 100755 scripts/test-thread-pool.sh create mode 100644 scripts/thread_pool_check.cpp diff --git a/cpp/OPDatabase.cpp b/cpp/OPDatabase.cpp index 1fbf4224..2bfba5eb 100644 --- a/cpp/OPDatabase.cpp +++ b/cpp/OPDatabase.cpp @@ -181,8 +181,7 @@ void OPDatabase::sync_update_hook_registration() { void OPDatabase::throw_if_closed(const char *function_name) const { if (invalidated) { - throw std::runtime_error(std::string("[op-sqlite][") + function_name + - "] database is closed"); + throw std::runtime_error(database_closed_message(function_name)); } } @@ -362,8 +361,8 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, // Drain any in-flight async queries before closing the db handle. // Without this, a queued/running execute() on the thread pool may // dereference the freed sqlite3* pointer → heap corruption / SIGABRT. - thread_pool->wait_finished(); - // Free the worker thread now rather than when the JS object is collected. + // shutdown() runs everything already queued, then joins the worker now + // rather than when the JS object is collected. thread_pool->shutdown(); release_hooks(); #ifdef OP_SQLITE_USE_LIBSQL @@ -412,6 +411,13 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, throw std::runtime_error("[op-sqlite] Delete no longer takes arguments"); } + // Checked before anything is torn down: the database stays open and usable + // when delete() is not supported. + if (delete_db_name.empty()) { + throw std::runtime_error("[op-sqlite][delete] delete() is not supported " + "for remote-only databases"); + } + invalidated = true; // Abort pending native SQLite work before waiting on the thread pool. #if !defined(OP_SQLITE_USE_LIBSQL) && !defined(OP_SQLITE_USE_TURSO) @@ -421,14 +427,8 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, #endif // Drain any in-flight async queries before closing/removing the db handle. // Without this, queued/running work may dereference a freed sqlite handle. - thread_pool->wait_finished(); thread_pool->shutdown(); - if (delete_db_name.empty()) { - throw std::runtime_error("[op-sqlite][delete] delete() is not supported " - "for remote-only databases"); - } - release_hooks(); #ifdef OP_SQLITE_USE_LIBSQL opsqlite_libsql_remove(db, delete_db_name, base_path); @@ -450,7 +450,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, : std::vector(); return promisify( - rt, thread_pool, + rt, "executeRaw", thread_pool, [this, query, params]() { std::vector> results; #ifdef OP_SQLITE_USE_LIBSQL @@ -525,7 +525,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, : std::vector(); return promisify( - rt, thread_pool, + rt, "execute", thread_pool, [this, query, params]() { #ifdef OP_SQLITE_USE_LIBSQL auto status = opsqlite_libsql_execute(db, query, ¶ms); @@ -549,7 +549,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, : std::vector(); return promisify( - rt, thread_pool, + rt, "executeWithHostObjects", thread_pool, [this, query, params]() { std::vector results; std::shared_ptr> metadata = @@ -597,7 +597,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, to_batch_arguments(rt, batchParams, &commands); return promisify( - rt, thread_pool, + rt, "executeBatch", thread_pool, [this, commands]() { #ifdef OP_SQLITE_USE_LIBSQL auto batchResult = opsqlite_libsql_execute_batch(db, &commands); @@ -658,7 +658,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, const std::string sqlFileName = args[0].asString(rt).utf8(rt); return promisify( - rt, thread_pool, + rt, "loadFile", thread_pool, [this, sqlFileName]() { return import_sql_file(db, sqlFileName); }, [](jsi::Runtime &rt, std::any prev) { auto result = std::any_cast(std::move(prev)); @@ -865,7 +865,14 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, flush_pending_reactive_queries(resolve); }; - thread_pool->queue_work(task); + try { + thread_pool->queue_work(task); + } catch (const ThreadPoolStoppedError &) { + // Thrown from the executor, so the promise rejects with the same error + // as every other call on a closed database. + throw std::runtime_error( + database_closed_message("flushPendingReactiveQueries")); + } return {}; })); @@ -892,8 +899,8 @@ void OPDatabase::invalidate() { } #endif - // Drain in-flight thread pool work before closing the db handle. - thread_pool->wait_finished(); + // Drain in-flight thread pool work and join the worker before closing the + // db handle. thread_pool->shutdown(); release_hooks(); diff --git a/cpp/OPMacros.hpp b/cpp/OPMacros.hpp index 7537e24b..022173ef 100644 --- a/cpp/OPMacros.hpp +++ b/cpp/OPMacros.hpp @@ -5,3 +5,4 @@ #define HFN(c1) jsi::Function::createFromHostFunction(rt, jsi::PropNameID::forAscii(rt, ""), 0, [c1](jsi::Runtime &rt, const jsi::Value &that, const jsi::Value *args, size_t count) -> jsi::Value #define HFN2(c1, c2) jsi::Function::createFromHostFunction(rt, jsi::PropNameID::forAscii(rt, ""), 0, [c1, c2](jsi::Runtime &rt, const jsi::Value &that, const jsi::Value *args, size_t count) -> jsi::Value #define HFN3(c1, c2, c3) jsi::Function::createFromHostFunction(rt, jsi::PropNameID::forAscii(rt, ""), 0, [c1, c2, c3](jsi::Runtime &rt, const jsi::Value &that, const jsi::Value *args, size_t count) -> jsi::Value +#define HFN4(c1, c2, c3, c4) jsi::Function::createFromHostFunction(rt, jsi::PropNameID::forAscii(rt, ""), 0, [c1, c2, c3, c4](jsi::Runtime &rt, const jsi::Value &that, const jsi::Value *args, size_t count) -> jsi::Value diff --git a/cpp/OPPreparedStatementHostObject.cpp b/cpp/OPPreparedStatementHostObject.cpp index a9ec17b6..06b7a692 100644 --- a/cpp/OPPreparedStatementHostObject.cpp +++ b/cpp/OPPreparedStatementHostObject.cpp @@ -32,7 +32,7 @@ jsi::Value PreparedStatementHostObject::get(jsi::Runtime &rt, std::vector params = to_variant_vec(rt, js_params); return promisify( - rt, _thread_pool, + rt, "bind", _thread_pool, [this, params]() { #ifdef OP_SQLITE_USE_LIBSQL opsqlite_libsql_bind_statement(_stmt, ¶ms); @@ -77,7 +77,7 @@ jsi::Value PreparedStatementHostObject::get(jsi::Runtime &rt, } return promisify( - rt, _thread_pool, + rt, "execute", _thread_pool, [this]() { std::vector results; auto metadata = std::make_shared>(); diff --git a/cpp/OPThreadPool.cpp b/cpp/OPThreadPool.cpp index 621bd8f3..7bfd4e13 100644 --- a/cpp/OPThreadPool.cpp +++ b/cpp/OPThreadPool.cpp @@ -1,10 +1,10 @@ #include "OPThreadPool.hpp" -#include +#include namespace opsqlite { -ThreadPool::ThreadPool() : done(false) { +ThreadPool::ThreadPool() { // This returns the number of threads supported by the system. If the // function can't figure out this information, it returns 0. 0 is not good, // so we create at least 1 @@ -20,56 +20,86 @@ ThreadPool::ThreadPool() : done(false) { // You can achieve more performance when using more threads but you run // into race conditions. This request was brought forth by PowerSync. auto number_of_threads = 1; - for (unsigned i = 0; i < number_of_threads; ++i) { - // The threads will execute the private member `do_work`. Note that we - // need to pass a reference to the function (namespaced with the class - // name) as the first argument, and the current object as second - // argument - threads.emplace_back(&ThreadPool::do_work, this); + try { + for (unsigned i = 0; i < number_of_threads; ++i) { + // The threads will execute the private member `do_work`. Note that we + // need to pass a reference to the function (namespaced with the class + // name) as the first argument, and the current object as second + // argument + threads.emplace_back(&ThreadPool::do_work, this); + worker_ids.push_back(threads.back().get_id()); + } + } catch (...) { + // The destructor does not run when a constructor throws, and destroying a + // joinable std::thread calls std::terminate. Stop and join the threads + // that did start before letting the exception out. + stop_accepting_work(); + join_threads(); + throw; } } -// Set on a worker whose own pool was destroyed by the task it just ran (the -// task held the last shared_ptr to the pool, e.g. a promise task). do_work() -// must then return without touching the freed pool. -static thread_local bool pool_destroyed_on_worker = false; - -// The destructor joins all the threads so the process (or in our RN case, this -// main-thread/runtime generation) can exit gracefully. This will be executed if -// there is any exception (e.g. creating the threads) +// Joins the threads so the process (or in our RN case, this +// main-thread/runtime generation) can exit gracefully. A no-op when shutdown() +// already ran. Never runs on a worker as long as no task owns the pool (see the +// rule in the header). ThreadPool::~ThreadPool() { shutdown(); } -void ThreadPool::shutdown() { - std::vector to_join; +bool ThreadPool::is_worker_thread() const { + return std::find(worker_ids.begin(), worker_ids.end(), + std::this_thread::get_id()) != worker_ids.end(); +} + +void ThreadPool::stop_accepting_work() { { - std::lock_guard g(work_queue_mutex); - if (shut_down) { - return; - } - shut_down = true; // Set under the mutex so a worker between its predicate check and its // wait cannot miss the wake-up below. + std::lock_guard g(work_queue_mutex); done = true; - to_join.swap(threads); } - // Wake up all the threads, so they can finish and be joined + // Wake up all the threads, so they can drain the queue and finish work_pending.notify_all(); +} - for (auto &thread : to_join) { - if (!thread.joinable()) { - continue; - } - if (thread.get_id() == std::this_thread::get_id()) { - // The last reference was dropped by a task on this very worker: joining - // ourselves throws std::system_error (terminate). Detach; do_work() - // returns as soon as it sees the flag. - thread.detach(); - pool_destroyed_on_worker = true; - } else { +void ThreadPool::join_threads() { + // A second caller blocks here until the first caller's join has completed, + // so it can never free this object while the worker is still running. + std::lock_guard g(join_mutex); + for (auto &thread : threads) { + if (thread.joinable()) { thread.join(); } } + threads.clear(); +} + +void ThreadPool::shutdown() { + stop_accepting_work(); + + if (is_worker_thread()) { + // Called from a task (e.g. a database invalidated on the worker). The + // worker cannot join itself, and it will not pick up another task until + // this one returns, so run what is left here: when shutdown() returns, + // nothing else will run, as on every other thread. `busy` still counts the + // calling task, which do_work() releases as usual. + while (true) { + std::function task; + { + std::lock_guard g(work_queue_mutex); + if (work_queue.empty()) { + break; + } + task = std::move(work_queue.front()); + work_queue.pop(); + } + task(); + } + work_pending.notify_all(); + return; + } + + join_threads(); } // This function will be called by the server every time there is a request @@ -78,11 +108,10 @@ void ThreadPool::queue_work(const std::function &task) { // Grab the mutex std::lock_guard g(work_queue_mutex); - // A shut down pool has no worker: a task queued now would never run and its - // promise would never settle. Callers queue from a Promise executor, so the - // throw rejects the promise. + // A stopped pool has no worker left to run the task, and its promise would + // never settle. Callers map this to their own "database is closed" error. if (done) { - throw std::runtime_error("[op-sqlite] database is closed"); + throw ThreadPoolStoppedError(); } // Push the request to the queue @@ -95,8 +124,7 @@ void ThreadPool::queue_work(const std::function &task) { // Function used by the threads to grab work from the queue void ThreadPool::do_work() { - // Loop while the queue is not destructing - while (!done) { + while (true) { std::function task; // Create a scope, so we don't lock the queue for longer than necessary @@ -108,8 +136,9 @@ void ThreadPool::do_work() { return done || !work_queue.empty(); }); - // If we are shutting down exit without trying to process more work - if (done) { + // Shutting down: finish only once every queued task has run, so no + // promise is left unsettled and wait_finished() cannot block forever. + if (work_queue.empty()) { break; } @@ -125,13 +154,6 @@ void ThreadPool::do_work() { // while task-owned resources are still pending destruction. task = nullptr; - // Releasing the task may have destroyed this pool (it held the last - // reference). If so, `this` is gone: touch nothing. - if (pool_destroyed_on_worker) { - pool_destroyed_on_worker = false; - return; - } - { std::lock_guard g(work_queue_mutex); --busy; diff --git a/cpp/OPThreadPool.hpp b/cpp/OPThreadPool.hpp index 6912790f..4ee4054e 100644 --- a/cpp/OPThreadPool.hpp +++ b/cpp/OPThreadPool.hpp @@ -6,24 +6,46 @@ #include #include #include +#include #include #include #include namespace opsqlite { +// Thrown by queue_work() once the pool has been shut down. The pool knows +// nothing about databases; callers map this to their own "database is closed" +// error. +class ThreadPoolStoppedError : public std::runtime_error { +public: + ThreadPoolStoppedError() + : std::runtime_error("[op-sqlite] thread pool is stopped") {} +}; + +// Rule: a task must never own the pool it runs on (capture a shared_ptr to +// it). If a task released the last reference, ~ThreadPool would run on the +// worker while do_work() still uses `this`. No task does today: the tasks +// queued by promisify and the reactive flush capture the database or the +// statement by raw pointer, never the pool. class ThreadPool { public: ThreadPool(); ~ThreadPool(); + // Throws ThreadPoolStoppedError after shutdown(). void queue_work(const std::function &task); void wait_finished(); - // Stops and joins the worker now. Called by close()/delete()/invalidate(): - // the pool is shared with prepared statements and pending promises, so the - // destructor may run much later (only when the JS object is garbage - // collected), and until then every closed database kept a parked thread. - // Idempotent and safe to call concurrently. Work queued afterwards is - // rejected. + // Stops the pool: no new work is accepted, every task already queued still + // runs (so no promise is left unsettled), then the worker is joined. When it + // returns, no other task will run. Called by close()/delete()/invalidate() + // rather than leaving it to the destructor, because the pool is shared with + // prepared statements and pending promises and may outlive the database + // until the JS object is garbage collected. + // + // Idempotent and safe to call concurrently: a later caller returns only + // after the first caller's join has completed. Called from a task on the + // worker itself, it runs the remaining queued tasks inline and returns + // without joining (a thread cannot join itself). The worker then exits after + // the current task, and a later shutdown() or the destructor joins it. void shutdown(); private: @@ -32,25 +54,34 @@ class ThreadPool { // work to do std::condition_variable_any work_pending; - // We store the threads in a vector, so we can later stop them gracefully + // We store the threads in a vector, so we can later stop them gracefully. + // Only touched by the constructor and, under join_mutex, by shutdown(). std::vector threads; + // Ids of the worker threads. Written only by the constructor, so shutdown() + // can read it from any thread without a lock. + std::vector worker_ids; + // Mutex to protect work_queue std::mutex work_queue_mutex; + // Held by shutdown() while it joins, so a second caller waits for that join + // to finish instead of returning while the worker still uses this object. + std::mutex join_mutex; + // Queue of requests waiting to be processed std::queue> work_queue; - // This will be set to true when the thread pool is shutting down. This - // tells the threads to stop looping and finish. - // Atomic because do_work() reads it in `while (!done)` outside the mutex. - std::atomic done; + // Set (under work_queue_mutex) by shutdown(). queue_work() then refuses new + // work, and the threads stop once the queue is empty. + bool done{false}; - // Set (under work_queue_mutex) by the first shutdown(); later calls return. - bool shut_down{false}; + bool is_worker_thread() const; + void stop_accepting_work(); + void join_threads(); // Function used by the threads to grab work from the queue void do_work(); }; -} // namespace opsqlite \ No newline at end of file +} // namespace opsqlite diff --git a/cpp/OPUtils.cpp b/cpp/OPUtils.cpp index 7f3ccb2d..7311c635 100644 --- a/cpp/OPUtils.cpp +++ b/cpp/OPUtils.cpp @@ -403,16 +403,21 @@ static void reject_with(const std::shared_ptr &invoker, }); } +std::string database_closed_message(const char *function_name) { + return std::string("[op-sqlite][") + function_name + "] database is closed"; +} + jsi::Value -promisify(jsi::Runtime &rt, std::shared_ptr thread_pool, +promisify(jsi::Runtime &rt, const char *function_name, + std::shared_ptr thread_pool, std::function lambda, std::function resolve_callback) { auto promise_constructor = rt.global().getPropertyAsFunction(rt, "Promise"); - auto executor = - HFN3(lambda = std::move(lambda), - resolve_callback = std::move(resolve_callback), thread_pool) { + auto executor = HFN4(lambda = std::move(lambda), + resolve_callback = std::move(resolve_callback), + thread_pool, function_name) { auto resolve = std::make_shared(rt, args[0]); auto reject = std::make_shared(rt, args[1]); @@ -465,7 +470,13 @@ promisify(jsi::Runtime &rt, std::shared_ptr thread_pool, } }; - thread_pool->queue_work(task); + try { + thread_pool->queue_work(task); + } catch (const ThreadPoolStoppedError &) { + // Thrown from the executor, so the promise rejects with the same error + // as every other call on a closed database. + throw std::runtime_error(database_closed_message(function_name)); + } return jsi::Value(nullptr); }); diff --git a/cpp/OPUtils.hpp b/cpp/OPUtils.hpp index 46c2e9a8..0e2a5ff1 100644 --- a/cpp/OPUtils.hpp +++ b/cpp/OPUtils.hpp @@ -107,8 +107,16 @@ jsi::Value create_js_error(jsi::Runtime &rt, const std::string &message, /// properties. A jsi::JSError carries our own Error object through untouched. [[noreturn]] void throw_js_error(jsi::Runtime &rt, const SQLiteError &error); +/// The message every call on a closed database fails with: +/// "[op-sqlite][] database is closed". +std::string database_closed_message(const char *function_name); + +/// `function_name` names the call in the "database is closed" rejection when +/// the pool has already been shut down. It must be a string literal. jsi::Value -promisify(jsi::Runtime &rt, std::shared_ptr thread_pool, std::function lambda, +promisify(jsi::Runtime &rt, const char *function_name, + std::shared_ptr thread_pool, + std::function lambda, std::function resolve_callback); diff --git a/scripts/test-thread-pool.sh b/scripts/test-thread-pool.sh new file mode 100755 index 00000000..38691073 --- /dev/null +++ b/scripts/test-thread-pool.sh @@ -0,0 +1,25 @@ +#!/bin/bash +# Builds scripts/thread_pool_check.cpp against cpp/OPThreadPool.cpp and runs it +# under ThreadSanitizer and AddressSanitizer. No React Native toolchain needed. +# +# scripts/test-thread-pool.sh # both sanitizers +# scripts/test-thread-pool.sh thread # one of them +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +OUT="${TMPDIR:-/tmp}/op-sqlite-thread-pool-check" +mkdir -p "$OUT" + +sanitizers=("$@") +if [ ${#sanitizers[@]} -eq 0 ]; then + sanitizers=(thread address) +fi + +for sanitizer in "${sanitizers[@]}"; do + echo "== -fsanitize=$sanitizer" + "${CXX:-clang++}" -std=c++17 -O1 -g -fno-omit-frame-pointer \ + -fsanitize="$sanitizer" -I "$ROOT/cpp" \ + "$ROOT/cpp/OPThreadPool.cpp" "$ROOT/scripts/thread_pool_check.cpp" \ + -o "$OUT/check-$sanitizer" + "$OUT/check-$sanitizer" +done diff --git a/scripts/thread_pool_check.cpp b/scripts/thread_pool_check.cpp new file mode 100644 index 00000000..c40ee201 --- /dev/null +++ b/scripts/thread_pool_check.cpp @@ -0,0 +1,374 @@ +// Standalone lifecycle checks for cpp/OPThreadPool.cpp. No React Native, no +// JSI: it compiles the pool on its own and drives it the way OPDatabase does. +// Run it under ThreadSanitizer and AddressSanitizer with +// scripts/test-thread-pool.sh. +// +// Every check runs under a watchdog: a hang (a wait_finished() that never +// returns, a join that never completes) is reported as a failure instead of +// stalling the run. +#include "OPThreadPool.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#ifdef __APPLE__ +#include +#else +#include +#endif + +using opsqlite::ThreadPool; +using opsqlite::ThreadPoolStoppedError; +using namespace std::chrono_literals; + +static int thread_count() { +#ifdef __APPLE__ + thread_act_array_t list; + mach_msg_type_number_t n = 0; + if (task_threads(mach_task_self(), &list, &n) != KERN_SUCCESS) { + return -1; + } + for (mach_msg_type_number_t i = 0; i < n; i++) { + mach_port_deallocate(mach_task_self(), list[i]); + } + vm_deallocate(mach_task_self(), (vm_address_t)list, n * sizeof(thread_act_t)); + return (int)n; +#else + int n = 0; + if (DIR *dir = opendir("/proc/self/task")) { + while (dirent *entry = readdir(dir)) { + if (entry->d_name[0] != '.') { + n++; + } + } + closedir(dir); + } + return n; +#endif +} + +static int failures = 0; + +static void check(bool condition, const std::string &message) { + std::printf("%s %s\n", condition ? "ok: " : "FAIL:", message.c_str()); + std::fflush(stdout); + if (!condition) { + failures++; + } +} + +// Runs `body` on its own thread and gives up on the whole process if it does +// not finish in time: a hung thread cannot be recovered. +template +static void with_watchdog(const char *name, std::chrono::milliseconds limit, + F body) { + std::mutex m; + std::condition_variable cv; + bool finished = false; + std::thread runner([&] { + body(); + std::lock_guard g(m); + finished = true; + cv.notify_all(); + }); + std::unique_lock lock(m); + if (!cv.wait_for(lock, limit, [&] { return finished; })) { + std::printf("FAIL: %s did not finish within %lld ms (hang)\n", name, + (long long)limit.count()); + std::printf("\nFAILED (hang)\n"); + std::fflush(stdout); + std::_Exit(2); + } + lock.unlock(); + runner.join(); +} + +// A one-shot gate a task can block on, so a test controls exactly when the +// worker is busy. +struct Gate { + std::mutex m; + std::condition_variable cv; + bool open = false; + void release() { + std::lock_guard g(m); + open = true; + cv.notify_all(); + } + void wait() { + std::unique_lock g(m); + cv.wait(g, [&] { return open; }); + } +}; + +// (a) close() frees the worker now, while the pool is still referenced (by a +// prepared statement, or by the JS object awaiting GC). +static void closed_pools_release_their_threads() { + const int base = thread_count(); + std::vector> held; + for (int i = 0; i < 300; i++) { + auto pool = std::make_shared(); + std::atomic ran{false}; + pool->queue_work([&] { ran = true; }); + pool->shutdown(); + if (!ran) { + check(false, "work queued before shutdown ran"); + } + held.push_back(pool); + } + const int extra = thread_count() - base; + check(extra <= 1, "300 shut down pools, still referenced, leave <= 1 extra " + "thread (extra=" + + std::to_string(extra) + ")"); +} + +// (b) Work queued on a stopped pool is refused with the pool's own error, so a +// promise rejects instead of waiting on a queue nobody drains. +static void queue_after_shutdown_throws() { + auto pool = std::make_shared(); + pool->shutdown(); + bool threw = false; + std::string what; + try { + pool->queue_work([] {}); + } catch (const ThreadPoolStoppedError &e) { + threw = true; + what = e.what(); + } + check(threw, "queue_work after shutdown throws ThreadPoolStoppedError"); + check(what == "[op-sqlite] thread pool is stopped", + "the error is the pool's generic one (\"" + what + "\")"); + pool->wait_finished(); + check(true, "wait_finished after shutdown returns"); +} + +// (c) Tasks queued before shutdown() all run before it returns, with or +// without a wait_finished() first, and on the destructor path too. +static void queued_tasks_drain_on_shutdown() { + { + auto pool = std::make_shared(); + Gate gate; + std::atomic ran{0}; + pool->queue_work([&] { + gate.wait(); + ran++; + }); + for (int i = 0; i < 50; i++) { + pool->queue_work([&] { ran++; }); + } + // The worker is parked in the first task, so all 50 are still queued + // when shutdown() starts. + std::thread opener([&] { + std::this_thread::sleep_for(20ms); + gate.release(); + }); + pool->shutdown(); + check(ran == 51, "shutdown() drains the queue before returning (ran=" + + std::to_string(ran.load()) + "/51)"); + pool->wait_finished(); + check(true, "wait_finished after a draining shutdown returns"); + opener.join(); + } + { + std::atomic ran{0}; + Gate gate; + std::thread opener; + { + auto pool = std::make_shared(); + pool->queue_work([&] { + gate.wait(); + ran++; + }); + for (int i = 0; i < 50; i++) { + pool->queue_work([&] { ran++; }); + } + opener = std::thread([&] { + std::this_thread::sleep_for(20ms); + gate.release(); + }); + } // ~ThreadPool, no shutdown() and no wait_finished() before it + check(ran == 51, "the destructor drains the queue too (ran=" + + std::to_string(ran.load()) + "/51)"); + opener.join(); + } +} + +// (d) Two concurrent shutdown() calls, then the destructor. Neither caller may +// return while the worker is still inside a task: the destructor that follows +// would free the mutex, condition variable and queue under it. +static void concurrent_shutdowns_then_destructor() { + for (int round = 0; round < 20; round++) { + auto *pool = new ThreadPool(); + Gate started; + std::atomic task_finished{false}; + pool->queue_work([&] { + started.release(); + std::this_thread::sleep_for(30ms); + task_finished = true; + }); + started.wait(); + + std::atomic first_saw_finished{false}; + std::atomic second_saw_finished{false}; + std::thread first([&] { + pool->shutdown(); + first_saw_finished = task_finished.load(); + }); + std::thread second([&] { + // Start only once `first` has stopped the pool (queue_work refuses + // work from then on) and is on its way into the join. + while (true) { + try { + pool->queue_work([] {}); + } catch (const ThreadPoolStoppedError &) { + break; + } + std::this_thread::sleep_for(1ms); + } + std::this_thread::sleep_for(5ms); + pool->shutdown(); + second_saw_finished = task_finished.load(); + if (!second_saw_finished) { + // Report before the delete below, which then frees the pool under + // the running worker. + check(false, "the second shutdown() returned before the join " + "completed"); + } + delete pool; // ~ThreadPool right after a shutdown() returned + }); + first.join(); + second.join(); + if (!first_saw_finished || !second_saw_finished) { + check(false, "round " + std::to_string(round) + + ": a shutdown() returned while the worker was still " + "running a task"); + return; + } + } + check(true, "concurrent shutdown() x2 + destructor: every caller waits for " + "the join (20 rounds)"); +} + +// (e) shutdown() from a task on the pool's own worker, as OPDatabase's +// invalidate()/destructor would if it ran there. It must not self-join, it +// must not hang, the tasks behind it must still run, and `busy` must be +// released so wait_finished() returns. +static void shutdown_from_the_worker() { + auto pool = std::make_shared(); + Gate queued; + std::atomic after{0}; + std::atomic after_seen_by_shutdown{-1}; + std::atomic threw_on_worker{false}; + pool->queue_work([&] { + queued.wait(); + pool->shutdown(); + // Runs the rest inline: nothing is left to run once shutdown() returns. + after_seen_by_shutdown = after.load(); + try { + pool->queue_work([] {}); + } catch (const ThreadPoolStoppedError &) { + threw_on_worker = true; + } + }); + for (int i = 0; i < 10; i++) { + pool->queue_work([&] { after++; }); + } + queued.release(); + + pool->wait_finished(); // hangs if do_work never decremented busy + check(true, "wait_finished returns after shutdown() ran on the worker"); + check(after_seen_by_shutdown == 10, + "shutdown() on the worker ran the queued tasks before returning " + "(saw " + + std::to_string(after_seen_by_shutdown.load()) + "/10)"); + check(threw_on_worker, "queue_work from the worker after its shutdown " + "throws"); + pool->wait_finished(); + check(true, "a second wait_finished also returns"); + pool->shutdown(); // joins the worker, which exited on its own + check(true, "shutdown() from another thread then joins the worker"); + pool.reset(); + check(true, "destructor after a worker-side shutdown"); +} + +// (f) A constructor that cannot start its thread throws without terminating +// the process. The pool starts one thread, so this exercises the failure of +// the first (and only) one; the catch block's join of already-started +// threads matters only if number_of_threads is raised. +static void constructor_throw_is_clean() { + std::mutex m; + std::condition_variable cv; + bool release = false; + std::vector hogs; + bool exhausted = false; + for (int i = 0; i < 10000; i++) { + try { + hogs.emplace_back([&] { + std::unique_lock g(m); + cv.wait(g, [&] { return release; }); + }); + } catch (const std::system_error &) { + exhausted = true; + break; + } + } + bool threw = false; + if (exhausted) { + try { + ThreadPool pool; + } catch (const std::system_error &) { + threw = true; + } + } + { + std::lock_guard g(m); + release = true; + } + cv.notify_all(); + for (auto &t : hogs) { + t.join(); + } + if (!exhausted) { + check(true, "constructor throw: could not exhaust threads (" + + std::to_string(hogs.size()) + " started), skipped"); + return; + } + check(threw, "constructor throws std::system_error when its thread cannot " + "start, without std::terminate (after " + + std::to_string(hogs.size()) + " threads)"); + // The pool still works once threads are available again. + ThreadPool pool; + std::atomic ran{false}; + pool.queue_work([&] { ran = true; }); + pool.shutdown(); + check(ran, "a pool constructed afterwards works"); +} + +int main() { + with_watchdog("(a) closed pools release threads", 30s, + closed_pools_release_their_threads); + with_watchdog("(b) queue after shutdown", 10s, queue_after_shutdown_throws); + with_watchdog("(c) drain on shutdown", 10s, queued_tasks_drain_on_shutdown); + with_watchdog("(d) concurrent shutdowns + destructor", 30s, + concurrent_shutdowns_then_destructor); + with_watchdog("(e) shutdown from the worker", 10s, shutdown_from_the_worker); + if (std::getenv("SKIP_CONSTRUCTOR_THROW") == nullptr) { + with_watchdog("(f) constructor throw", 60s, constructor_throw_is_clean); + } + + if (failures != 0) { + std::printf("\n%d FAILED\n", failures); + return 1; + } + std::printf("\nall passed\n"); + return 0; +} From baa94ba406d03c3b0a1b6faca78760fc65fb8b71 Mon Sep 17 00:00:00 2001 From: Glenn444 Date: Sat, 24 Oct 2026 21:11:14 +0300 Subject: [PATCH 3/5] Prepared statements: fail with "database is closed" after close() Addresses point 5 of the review of #470 (and the test asked for in 10). A statement keeps the raw connection handle it was prepared on. After close() the async path rejected only because the pool was stopped, while executeSync() and bindSync() still ran against the closed handle, which for libsql is already freed. PreparedStatementHostObject now holds a weak_ptr to its OPDatabase and checks it at the top of bind, bindSync, execute and executeSync, before anything touches the handle. A closed (or already destroyed) database throws the same "[op-sqlite][] database is closed" error as OPDatabase::throw_if_closed, with no `code`, whatever the pool's state. The JS wrapper for stmt.execute is now async, as bind already is, so the native throw reaches the caller as a rejection, the same way db.execute reports a closed database. executeSync/bindSync throw synchronously. example/src/tests/preparedStatements.ts covers both paths. Co-Authored-By: Claude Fable 5.1 --- cpp/OPDatabase.cpp | 4 +-- cpp/OPDatabase.hpp | 3 ++ cpp/OPPreparedStatementHostObject.cpp | 17 +++++++++ cpp/OPPreparedStatementHostObject.hpp | 19 +++++++--- example/src/tests/preparedStatements.ts | 47 +++++++++++++++++++++++++ src/functions.ts | 6 +++- 6 files changed, 89 insertions(+), 7 deletions(-) diff --git a/cpp/OPDatabase.cpp b/cpp/OPDatabase.cpp index 2bfba5eb..0b20b115 100644 --- a/cpp/OPDatabase.cpp +++ b/cpp/OPDatabase.cpp @@ -824,8 +824,8 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, } #endif auto preparedStatementHostObject = - std::make_shared(db, statement, - thread_pool); + std::make_shared(weak_from_this(), db, + statement, thread_pool); return jsi::Object::createFromHostObject(rt, preparedStatementHostObject); })); diff --git a/cpp/OPDatabase.hpp b/cpp/OPDatabase.hpp index 9e387a6b..a1c5cbc6 100644 --- a/cpp/OPDatabase.hpp +++ b/cpp/OPDatabase.hpp @@ -77,6 +77,9 @@ class JSI_EXPORT OPDatabase void on_commit(); void on_rollback(); void invalidate(); + // True once close(), delete() or invalidate() ran. Prepared statements check + // it before touching the connection handle they were created from. + bool is_closed() const { return invalidated; } ~OPDatabase() override; private: diff --git a/cpp/OPPreparedStatementHostObject.cpp b/cpp/OPPreparedStatementHostObject.cpp index 06b7a692..7c2b5921 100644 --- a/cpp/OPPreparedStatementHostObject.cpp +++ b/cpp/OPPreparedStatementHostObject.cpp @@ -1,4 +1,5 @@ #include "OPPreparedStatementHostObject.hpp" +#include "OPDatabase.hpp" #if OP_SQLITE_USE_LIBSQL #include "libsql/OPLibsqlBridge.hpp" #else @@ -18,12 +19,22 @@ PreparedStatementHostObject::getPropertyNames(jsi::Runtime &rt) { return keys; } +void PreparedStatementHostObject::throw_if_closed( + const char *function_name) const { + auto database = _database.lock(); + if (database == nullptr || database->is_closed()) { + throw std::runtime_error(database_closed_message(function_name)); + } +} + jsi::Value PreparedStatementHostObject::get(jsi::Runtime &rt, const jsi::PropNameID &propNameID) { auto name = propNameID.utf8(rt); if (name == "bind") { return HFN(this) { + throw_if_closed("bind"); + if (_stmt == nullptr) { throw std::runtime_error("statement has been freed"); } @@ -49,6 +60,8 @@ jsi::Value PreparedStatementHostObject::get(jsi::Runtime &rt, if (name == "bindSync") { return HFN(this) { + throw_if_closed("bindSync"); + if (_stmt == nullptr) { throw std::runtime_error("statement has been freed"); } @@ -72,6 +85,8 @@ jsi::Value PreparedStatementHostObject::get(jsi::Runtime &rt, if (name == "execute") { return HFN(this) { + throw_if_closed("execute"); + if (_stmt == nullptr) { throw std::runtime_error("statement has been freed"); } @@ -107,6 +122,8 @@ jsi::Value PreparedStatementHostObject::get(jsi::Runtime &rt, } if (name == "executeSync") { return HFN(this) { + throw_if_closed("executeSync"); + if (_stmt == nullptr) { throw std::runtime_error("statement has been freed"); } diff --git a/cpp/OPPreparedStatementHostObject.hpp b/cpp/OPPreparedStatementHostObject.hpp index 567364a4..82376fca 100644 --- a/cpp/OPPreparedStatementHostObject.hpp +++ b/cpp/OPPreparedStatementHostObject.hpp @@ -21,16 +21,22 @@ namespace opsqlite { namespace jsi = facebook::jsi; namespace react = facebook::react; +class OPDatabase; + class PreparedStatementHostObject : public jsi::HostObject { public: #ifdef OP_SQLITE_USE_LIBSQL - PreparedStatementHostObject(DB const &db, libsql_stmt_t stmt, + PreparedStatementHostObject(std::weak_ptr database, DB const &db, + libsql_stmt_t stmt, std::shared_ptr thread_pool) - : _db(db), _stmt(stmt), _thread_pool(thread_pool) {}; + : _database(std::move(database)), _db(db), _stmt(stmt), + _thread_pool(thread_pool) {}; #else - PreparedStatementHostObject(sqlite3 *db, sqlite3_stmt *stmt, + PreparedStatementHostObject(std::weak_ptr database, sqlite3 *db, + sqlite3_stmt *stmt, std::shared_ptr thread_pool) - : _db(db), _stmt(stmt), _thread_pool(thread_pool) {}; + : _database(std::move(database)), _db(db), _stmt(stmt), + _thread_pool(thread_pool) {}; #endif ~PreparedStatementHostObject() override; @@ -40,6 +46,11 @@ class PreparedStatementHostObject : public jsi::HostObject { jsi::Value get(jsi::Runtime &rt, const jsi::PropNameID &propNameID) override; private: + // Throws the same error as OPDatabase::throw_if_closed once the database + // this statement came from is closed (or gone): `_db` is no longer valid. + void throw_if_closed(const char *function_name) const; + + std::weak_ptr _database; #ifdef OP_SQLITE_USE_LIBSQL DB _db; libsql_stmt_t _stmt; diff --git a/example/src/tests/preparedStatements.ts b/example/src/tests/preparedStatements.ts index cfb128ee..bebf698a 100644 --- a/example/src/tests/preparedStatements.ts +++ b/example/src/tests/preparedStatements.ts @@ -125,4 +125,51 @@ describe("PreparedStatements", () => { const results = selectStatement.executeSync(); expect(results.rows.length).toEqual(5); }); + + it("prepared statement, execute after close rejects", async () => { + const statement = db.prepareStatement("SELECT * FROM User;"); + db.close(); + + // Rejects (does not throw synchronously), like db.execute after close + const promise = statement.execute(); + let error: any; + try { + await promise; + } catch (e) { + error = e; + } + + expect(error?.message).toContain( + "[op-sqlite][execute] database is closed", + ); + expect(error.code).toEqual(undefined); + }); + + it("prepared statement, sync calls after close throw", () => { + const statement = db.prepareStatement( + 'INSERT INTO "User" (id, name) VALUES(?,?);', + ); + db.close(); + + let executeError: any; + try { + statement.executeSync(); + } catch (e) { + executeError = e; + } + expect(executeError?.message).toContain( + "[op-sqlite][executeSync] database is closed", + ); + expect(executeError.code).toEqual(undefined); + + let bindError: any; + try { + statement.bindSync([4, "Juan"]); + } catch (e) { + bindError = e; + } + expect(bindError?.message).toContain( + "[op-sqlite][bindSync] database is closed", + ); + }); }); diff --git a/src/functions.ts b/src/functions.ts index fdf1185e..9fa528b4 100644 --- a/src/functions.ts +++ b/src/functions.ts @@ -178,7 +178,11 @@ function enhanceDB(db: _InternalDB, options: DBParams): DB { bind: async (params: Scalar[]) => { await stmt.bind(params); }, - execute: stmt.execute, + // async, like bind: a native throw (e.g. database is closed) becomes + // a rejection, as it does for db.execute + execute: async () => { + return await stmt.execute(); + }, executeSync: stmt.executeSync, }; }, From 08d4998a2127ecd50e7ba1dc8d6f30b73166a6b2 Mon Sep 17 00:00:00 2001 From: Oscar Franco Date: Mon, 26 Oct 2026 09:27:42 -0600 Subject: [PATCH 4/5] Simplify ThreadPool into a single WorkerThread The pool only ever runs one thread per connection, and after #470 nothing calls wait_finished() any more: shutdown() drains the queue and joins. That makes most of the pool's machinery unnecessary. - One std::thread, declared last, so a failed start needs no cleanup. This replaces the thread vector and the constructor try/catch. - shutdown() runs under std::call_once: idempotent, and a concurrent caller blocks until the first caller's join has finished. This replaces join_mutex. - shutdown() from the worker's own thread throws std::system_error before entering call_once, instead of running the rest of the queue inline. No task does this; the header documents the rule. This replaces worker_ids and the inline-drain path. - busy and wait_finished() are removed. Renamed ThreadPool -> WorkerThread (OPWorkerThread.*), ThreadPoolStoppedError -> WorkerThreadStoppedError, the thread_pool members -> worker_thread, and the harness/script to scripts/worker_thread_check.cpp / scripts/test-worker-thread.sh. Check (e) now expects shutdown() from the worker to throw while another thread is already shutting down. Co-Authored-By: Claude Opus 5.5 --- android/CMakeLists.txt | 2 +- cpp/OPDatabase.cpp | 48 ++--- cpp/OPDatabase.hpp | 4 +- cpp/OPPreparedStatementHostObject.cpp | 4 +- cpp/OPPreparedStatementHostObject.hpp | 12 +- cpp/OPSqlite.cpp | 2 +- cpp/OPThreadPool.cpp | 170 ----------------- cpp/OPThreadPool.hpp | 87 --------- cpp/OPUtils.cpp | 12 +- cpp/OPUtils.hpp | 6 +- cpp/OPWorkerThread.cpp | 79 ++++++++ cpp/OPWorkerThread.hpp | 75 ++++++++ example/src/tests/hooks.ts | 2 +- ...t-thread-pool.sh => test-worker-thread.sh} | 10 +- ...pool_check.cpp => worker_thread_check.cpp} | 175 +++++++++--------- 15 files changed, 288 insertions(+), 400 deletions(-) delete mode 100644 cpp/OPThreadPool.cpp delete mode 100644 cpp/OPThreadPool.hpp create mode 100644 cpp/OPWorkerThread.cpp create mode 100644 cpp/OPWorkerThread.hpp rename scripts/{test-thread-pool.sh => test-worker-thread.sh} (60%) rename scripts/{thread_pool_check.cpp => worker_thread_check.cpp} (62%) diff --git a/android/CMakeLists.txt b/android/CMakeLists.txt index 3b52778e..a132c506 100644 --- a/android/CMakeLists.txt +++ b/android/CMakeLists.txt @@ -43,7 +43,7 @@ add_library( SHARED ../cpp/OPSqlite.cpp ../cpp/OPUtils.cpp - ../cpp/OPThreadPool.cpp + ../cpp/OPWorkerThread.cpp ../cpp/OPSmartHostObject.cpp ../cpp/OPPreparedStatementHostObject.cpp ../cpp/OPDumbHostObject.cpp diff --git a/cpp/OPDatabase.cpp b/cpp/OPDatabase.cpp index 0b20b115..213faa6c 100644 --- a/cpp/OPDatabase.cpp +++ b/cpp/OPDatabase.cpp @@ -205,7 +205,7 @@ void OPDatabase::release_hooks() { OPDatabase::OPDatabase(jsi::Runtime &rt, jsi::Object &js_object, std::string &url, std::string &auth_token) : db_name(url) { - thread_pool = std::make_shared(); + worker_thread = std::make_shared(); db = opsqlite_libsql_open_remote(url, auth_token); create_jsi_functions(rt, js_object); @@ -220,7 +220,7 @@ OPDatabase::OPDatabase(jsi::Runtime &rt, jsi::Object &js_object, std::string &remote_encryption_key) : base_path(path), db_name(db_name), delete_db_name(db_name) { - thread_pool = std::make_shared(); + worker_thread = std::make_shared(); db = opsqlite_libsql_open_sync(db_name, path, url, auth_token, sync_interval, @@ -236,7 +236,7 @@ OPDatabase::OPDatabase(jsi::Runtime &rt, jsi::Object &js_object, std::string &base_path) : base_path(base_path), db_name(url), delete_db_name(turso_remote_db_name(url)) { - thread_pool = std::make_shared(); + worker_thread = std::make_shared(); db = opsqlite_open_remote(url, auth_token, base_path); create_jsi_functions(rt, js_object); @@ -249,7 +249,7 @@ OPDatabase::OPDatabase(jsi::Runtime &rt, jsi::Object &js_object, std::string &remote_encryption_key) : base_path(path), db_name(db_name), delete_db_name(db_name) { - thread_pool = std::make_shared(); + worker_thread = std::make_shared(); db = opsqlite_open_sync(db_name, path, url, auth_token, remote_encryption_key); @@ -264,7 +264,7 @@ OPDatabase::OPDatabase(jsi::Runtime &rt, jsi::Object &js_object, std::string &path, bool readOnly, bool failOnCreate, std::string &encryption_key) : base_path(base_path), db_name(db_name), delete_db_name(db_name) { - thread_pool = std::make_shared(); + worker_thread = std::make_shared(); #ifdef OP_SQLITE_USE_SQLCIPHER db = opsqlite_open(db_name, path, readOnly, failOnCreate, encryption_key); @@ -352,18 +352,18 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, js_object.setProperty(rt, "close", HFN(this) { invalidated = true; - // Abort pending native SQLite work before waiting on the thread pool. + // Abort pending native SQLite work before waiting on the worker thread. #if !defined(OP_SQLITE_USE_LIBSQL) && !defined(OP_SQLITE_USE_TURSO) if (db != nullptr) { sqlite3_interrupt(db); } #endif // Drain any in-flight async queries before closing the db handle. - // Without this, a queued/running execute() on the thread pool may + // Without this, a queued/running execute() on the worker thread may // dereference the freed sqlite3* pointer → heap corruption / SIGABRT. // shutdown() runs everything already queued, then joins the worker now // rather than when the JS object is collected. - thread_pool->shutdown(); + worker_thread->shutdown(); release_hooks(); #ifdef OP_SQLITE_USE_LIBSQL opsqlite_libsql_close(db); @@ -419,7 +419,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, } invalidated = true; - // Abort pending native SQLite work before waiting on the thread pool. + // Abort pending native SQLite work before waiting on the worker thread. #if !defined(OP_SQLITE_USE_LIBSQL) && !defined(OP_SQLITE_USE_TURSO) if (db != nullptr) { sqlite3_interrupt(db); @@ -427,7 +427,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, #endif // Drain any in-flight async queries before closing/removing the db handle. // Without this, queued/running work may dereference a freed sqlite handle. - thread_pool->shutdown(); + worker_thread->shutdown(); release_hooks(); #ifdef OP_SQLITE_USE_LIBSQL @@ -450,7 +450,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, : std::vector(); return promisify( - rt, "executeRaw", thread_pool, + rt, "executeRaw", worker_thread, [this, query, params]() { std::vector> results; #ifdef OP_SQLITE_USE_LIBSQL @@ -525,7 +525,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, : std::vector(); return promisify( - rt, "execute", thread_pool, + rt, "execute", worker_thread, [this, query, params]() { #ifdef OP_SQLITE_USE_LIBSQL auto status = opsqlite_libsql_execute(db, query, ¶ms); @@ -549,7 +549,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, : std::vector(); return promisify( - rt, "executeWithHostObjects", thread_pool, + rt, "executeWithHostObjects", worker_thread, [this, query, params]() { std::vector results; std::shared_ptr> metadata = @@ -597,7 +597,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, to_batch_arguments(rt, batchParams, &commands); return promisify( - rt, "executeBatch", thread_pool, + rt, "executeBatch", worker_thread, [this, commands]() { #ifdef OP_SQLITE_USE_LIBSQL auto batchResult = opsqlite_libsql_execute_batch(db, &commands); @@ -658,7 +658,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, const std::string sqlFileName = args[0].asString(rt).utf8(rt); return promisify( - rt, "loadFile", thread_pool, + rt, "loadFile", worker_thread, [this, sqlFileName]() { return import_sql_file(db, sqlFileName); }, [](jsi::Runtime &rt, std::any prev) { auto result = std::any_cast(std::move(prev)); @@ -825,7 +825,7 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, #endif auto preparedStatementHostObject = std::make_shared(weak_from_this(), db, - statement, thread_pool); + statement, worker_thread); return jsi::Object::createFromHostObject(rt, preparedStatementHostObject); })); @@ -866,8 +866,8 @@ void OPDatabase::create_jsi_functions(jsi::Runtime &rt, }; try { - thread_pool->queue_work(task); - } catch (const ThreadPoolStoppedError &) { + worker_thread->queue_work(task); + } catch (const WorkerThreadStoppedError &) { // Thrown from the executor, so the promise rejects with the same error // as every other call on a closed database. throw std::runtime_error( @@ -890,18 +890,18 @@ void OPDatabase::invalidate() { // Abort whatever is currently inside sqlite3_step so the drain below can // actually finish. Parity with the close and delete host functions, which - // already do this. Without it a long running query holds the pool past React - // Native's module invalidation budget, after which the runtime is destroyed - // anyway and the drain has bought nothing. + // already do this. Without it a long running query holds the worker thread + // past React Native's module invalidation budget, after which the runtime is + // destroyed anyway and the drain has bought nothing. #if !defined(OP_SQLITE_USE_LIBSQL) && !defined(OP_SQLITE_USE_TURSO) if (db != nullptr) { sqlite3_interrupt(db); } #endif - // Drain in-flight thread pool work and join the worker before closing the - // db handle. - thread_pool->shutdown(); + // Drain in-flight work and join the worker thread before closing the db + // handle. + worker_thread->shutdown(); release_hooks(); #ifdef OP_SQLITE_USE_LIBSQL diff --git a/cpp/OPDatabase.hpp b/cpp/OPDatabase.hpp index a1c5cbc6..ba6948c6 100644 --- a/cpp/OPDatabase.hpp +++ b/cpp/OPDatabase.hpp @@ -1,7 +1,7 @@ #pragma once -#include "OPThreadPool.hpp" #include "OPTypes.hpp" +#include "OPWorkerThread.hpp" #include #include #include @@ -103,7 +103,7 @@ class JSI_EXPORT OPDatabase // by the dead one. std::shared_ptr invoker = opsqlite::invoker; std::shared_ptr> alive = opsqlite::generation_alive; - std::shared_ptr thread_pool; + std::shared_ptr worker_thread; std::string db_name; std::string delete_db_name; std::shared_ptr update_hook_callback; diff --git a/cpp/OPPreparedStatementHostObject.cpp b/cpp/OPPreparedStatementHostObject.cpp index 7c2b5921..ab39ee4e 100644 --- a/cpp/OPPreparedStatementHostObject.cpp +++ b/cpp/OPPreparedStatementHostObject.cpp @@ -43,7 +43,7 @@ jsi::Value PreparedStatementHostObject::get(jsi::Runtime &rt, std::vector params = to_variant_vec(rt, js_params); return promisify( - rt, "bind", _thread_pool, + rt, "bind", _worker_thread, [this, params]() { #ifdef OP_SQLITE_USE_LIBSQL opsqlite_libsql_bind_statement(_stmt, ¶ms); @@ -92,7 +92,7 @@ jsi::Value PreparedStatementHostObject::get(jsi::Runtime &rt, } return promisify( - rt, "execute", _thread_pool, + rt, "execute", _worker_thread, [this]() { std::vector results; auto metadata = std::make_shared>(); diff --git a/cpp/OPPreparedStatementHostObject.hpp b/cpp/OPPreparedStatementHostObject.hpp index 82376fca..695a89fb 100644 --- a/cpp/OPPreparedStatementHostObject.hpp +++ b/cpp/OPPreparedStatementHostObject.hpp @@ -13,7 +13,7 @@ #include #endif #endif -#include "OPThreadPool.hpp" +#include "OPWorkerThread.hpp" #include #include @@ -28,15 +28,15 @@ class PreparedStatementHostObject : public jsi::HostObject { #ifdef OP_SQLITE_USE_LIBSQL PreparedStatementHostObject(std::weak_ptr database, DB const &db, libsql_stmt_t stmt, - std::shared_ptr thread_pool) + std::shared_ptr worker_thread) : _database(std::move(database)), _db(db), _stmt(stmt), - _thread_pool(thread_pool) {}; + _worker_thread(worker_thread) {}; #else PreparedStatementHostObject(std::weak_ptr database, sqlite3 *db, sqlite3_stmt *stmt, - std::shared_ptr thread_pool) + std::shared_ptr worker_thread) : _database(std::move(database)), _db(db), _stmt(stmt), - _thread_pool(thread_pool) {}; + _worker_thread(worker_thread) {}; #endif ~PreparedStatementHostObject() override; @@ -59,7 +59,7 @@ class PreparedStatementHostObject : public jsi::HostObject { // This shouldn't be de-allocated until sqlite3_finalize is called on it sqlite3_stmt *_stmt; #endif - std::shared_ptr _thread_pool; + std::shared_ptr _worker_thread; }; } // namespace opsqlite diff --git a/cpp/OPSqlite.cpp b/cpp/OPSqlite.cpp index e97158f9..3ee40eaa 100644 --- a/cpp/OPSqlite.cpp +++ b/cpp/OPSqlite.cpp @@ -1,7 +1,7 @@ #include "OPSqlite.hpp" #include "OPDatabase.hpp" #include "OPDumbHostObject.hpp" -#include "OPThreadPool.hpp" +#include "OPWorkerThread.hpp" #ifdef OP_SQLITE_USE_LIBSQL #include "libsql/OPLibsqlBridge.hpp" #else diff --git a/cpp/OPThreadPool.cpp b/cpp/OPThreadPool.cpp deleted file mode 100644 index 7bfd4e13..00000000 --- a/cpp/OPThreadPool.cpp +++ /dev/null @@ -1,170 +0,0 @@ -#include "OPThreadPool.hpp" - -#include - -namespace opsqlite { - -ThreadPool::ThreadPool() { - // This returns the number of threads supported by the system. If the - // function can't figure out this information, it returns 0. 0 is not good, - // so we create at least 1 - // auto number_of_threads = std::thread::hardware_concurrency(); - // if (number_of_threads == 0) { - // number_of_threads = 1; - // } - - // To keep sqlite threading model working, we cannot access via multiple - // threads in the same process therefore we cap the number of off-threads - // to one per connection - // - // You can achieve more performance when using more threads but you run - // into race conditions. This request was brought forth by PowerSync. - auto number_of_threads = 1; - try { - for (unsigned i = 0; i < number_of_threads; ++i) { - // The threads will execute the private member `do_work`. Note that we - // need to pass a reference to the function (namespaced with the class - // name) as the first argument, and the current object as second - // argument - threads.emplace_back(&ThreadPool::do_work, this); - worker_ids.push_back(threads.back().get_id()); - } - } catch (...) { - // The destructor does not run when a constructor throws, and destroying a - // joinable std::thread calls std::terminate. Stop and join the threads - // that did start before letting the exception out. - stop_accepting_work(); - join_threads(); - throw; - } -} - -// Joins the threads so the process (or in our RN case, this -// main-thread/runtime generation) can exit gracefully. A no-op when shutdown() -// already ran. Never runs on a worker as long as no task owns the pool (see the -// rule in the header). -ThreadPool::~ThreadPool() { shutdown(); } - -bool ThreadPool::is_worker_thread() const { - return std::find(worker_ids.begin(), worker_ids.end(), - std::this_thread::get_id()) != worker_ids.end(); -} - -void ThreadPool::stop_accepting_work() { - { - // Set under the mutex so a worker between its predicate check and its - // wait cannot miss the wake-up below. - std::lock_guard g(work_queue_mutex); - done = true; - } - - // Wake up all the threads, so they can drain the queue and finish - work_pending.notify_all(); -} - -void ThreadPool::join_threads() { - // A second caller blocks here until the first caller's join has completed, - // so it can never free this object while the worker is still running. - std::lock_guard g(join_mutex); - for (auto &thread : threads) { - if (thread.joinable()) { - thread.join(); - } - } - threads.clear(); -} - -void ThreadPool::shutdown() { - stop_accepting_work(); - - if (is_worker_thread()) { - // Called from a task (e.g. a database invalidated on the worker). The - // worker cannot join itself, and it will not pick up another task until - // this one returns, so run what is left here: when shutdown() returns, - // nothing else will run, as on every other thread. `busy` still counts the - // calling task, which do_work() releases as usual. - while (true) { - std::function task; - { - std::lock_guard g(work_queue_mutex); - if (work_queue.empty()) { - break; - } - task = std::move(work_queue.front()); - work_queue.pop(); - } - task(); - } - work_pending.notify_all(); - return; - } - - join_threads(); -} - -// This function will be called by the server every time there is a request -// that needs to be processed by the thread pool -void ThreadPool::queue_work(const std::function &task) { - // Grab the mutex - std::lock_guard g(work_queue_mutex); - - // A stopped pool has no worker left to run the task, and its promise would - // never settle. Callers map this to their own "database is closed" error. - if (done) { - throw ThreadPoolStoppedError(); - } - - // Push the request to the queue - work_queue.push(task); - - // Wake every waiter. wait_finished() and do_work() share this condition - // so we force all conditions to check - work_pending.notify_all(); -} - -// Function used by the threads to grab work from the queue -void ThreadPool::do_work() { - while (true) { - std::function task; - - // Create a scope, so we don't lock the queue for longer than necessary - { - std::unique_lock g(work_queue_mutex); - work_pending.wait(g, [&] { - // Only wake up if there are elements in the queue or the - // program is shutting down - return done || !work_queue.empty(); - }); - - // Shutting down: finish only once every queued task has run, so no - // promise is left unsettled and wait_finished() cannot block forever. - if (work_queue.empty()) { - break; - } - - task = work_queue.front(); - work_queue.pop(); - ++busy; - } - - task(); - - // Release the task (and everything it captured, e.g. JSI values) before - // signalling idle, so wait_finished()/close() can't observe busy == 0 - // while task-owned resources are still pending destruction. - task = nullptr; - - { - std::lock_guard g(work_queue_mutex); - --busy; - } - work_pending.notify_all(); - } -} - -void ThreadPool::wait_finished() { - std::unique_lock g(work_queue_mutex); - work_pending.wait(g, [&] { return work_queue.empty() && (busy == 0); }); -} - -} // namespace opsqlite diff --git a/cpp/OPThreadPool.hpp b/cpp/OPThreadPool.hpp deleted file mode 100644 index 4ee4054e..00000000 --- a/cpp/OPThreadPool.hpp +++ /dev/null @@ -1,87 +0,0 @@ -#pragma once - -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -namespace opsqlite { - -// Thrown by queue_work() once the pool has been shut down. The pool knows -// nothing about databases; callers map this to their own "database is closed" -// error. -class ThreadPoolStoppedError : public std::runtime_error { -public: - ThreadPoolStoppedError() - : std::runtime_error("[op-sqlite] thread pool is stopped") {} -}; - -// Rule: a task must never own the pool it runs on (capture a shared_ptr to -// it). If a task released the last reference, ~ThreadPool would run on the -// worker while do_work() still uses `this`. No task does today: the tasks -// queued by promisify and the reactive flush capture the database or the -// statement by raw pointer, never the pool. -class ThreadPool { -public: - ThreadPool(); - ~ThreadPool(); - // Throws ThreadPoolStoppedError after shutdown(). - void queue_work(const std::function &task); - void wait_finished(); - // Stops the pool: no new work is accepted, every task already queued still - // runs (so no promise is left unsettled), then the worker is joined. When it - // returns, no other task will run. Called by close()/delete()/invalidate() - // rather than leaving it to the destructor, because the pool is shared with - // prepared statements and pending promises and may outlive the database - // until the JS object is garbage collected. - // - // Idempotent and safe to call concurrently: a later caller returns only - // after the first caller's join has completed. Called from a task on the - // worker itself, it runs the remaining queued tasks inline and returns - // without joining (a thread cannot join itself). The worker then exits after - // the current task, and a later shutdown() or the destructor joins it. - void shutdown(); - -private: - unsigned int busy{}; - // This condition variable is used for the threads to wait until there is - // work to do - std::condition_variable_any work_pending; - - // We store the threads in a vector, so we can later stop them gracefully. - // Only touched by the constructor and, under join_mutex, by shutdown(). - std::vector threads; - - // Ids of the worker threads. Written only by the constructor, so shutdown() - // can read it from any thread without a lock. - std::vector worker_ids; - - // Mutex to protect work_queue - std::mutex work_queue_mutex; - - // Held by shutdown() while it joins, so a second caller waits for that join - // to finish instead of returning while the worker still uses this object. - std::mutex join_mutex; - - // Queue of requests waiting to be processed - std::queue> work_queue; - - // Set (under work_queue_mutex) by shutdown(). queue_work() then refuses new - // work, and the threads stop once the queue is empty. - bool done{false}; - - bool is_worker_thread() const; - void stop_accepting_work(); - void join_threads(); - - // Function used by the threads to grab work from the queue - void do_work(); -}; - -} // namespace opsqlite diff --git a/cpp/OPUtils.cpp b/cpp/OPUtils.cpp index 7311c635..401b262a 100644 --- a/cpp/OPUtils.cpp +++ b/cpp/OPUtils.cpp @@ -5,8 +5,8 @@ #ifndef OP_SQLITE_USE_LIBSQL #include "OPBridge.hpp" #endif -#include "OPThreadPool.hpp" #include "OPMacros.hpp" +#include "OPWorkerThread.hpp" #include #include #include @@ -382,7 +382,7 @@ void log_to_console(jsi::Runtime &runtime, const std::string &message) { log.call(runtime, jsi::String::createFromUtf8(runtime, message)); } -/// Rejects a promisified call from the thread pool. +/// Rejects a promisified call from the worker thread. /// /// `resolve` is captured in the invokeAsync lambda alongside `reject` so it is /// disposed on the JS thread. A negative `code` means the failure did not come @@ -409,7 +409,7 @@ std::string database_closed_message(const char *function_name) { jsi::Value promisify(jsi::Runtime &rt, const char *function_name, - std::shared_ptr thread_pool, + std::shared_ptr worker_thread, std::function lambda, std::function resolve_callback) { @@ -417,7 +417,7 @@ promisify(jsi::Runtime &rt, const char *function_name, auto executor = HFN4(lambda = std::move(lambda), resolve_callback = std::move(resolve_callback), - thread_pool, function_name) { + worker_thread, function_name) { auto resolve = std::make_shared(rt, args[0]); auto reject = std::make_shared(rt, args[1]); @@ -471,8 +471,8 @@ promisify(jsi::Runtime &rt, const char *function_name, }; try { - thread_pool->queue_work(task); - } catch (const ThreadPoolStoppedError &) { + worker_thread->queue_work(task); + } catch (const WorkerThreadStoppedError &) { // Thrown from the executor, so the promise rejects with the same error // as every other call on a closed database. throw std::runtime_error(database_closed_message(function_name)); diff --git a/cpp/OPUtils.hpp b/cpp/OPUtils.hpp index 0e2a5ff1..01eafbd8 100644 --- a/cpp/OPUtils.hpp +++ b/cpp/OPUtils.hpp @@ -9,12 +9,12 @@ #else #include #endif +#include "OPWorkerThread.hpp" #include #include #include #include #include -#include "OPThreadPool.hpp" namespace opsqlite { @@ -112,10 +112,10 @@ jsi::Value create_js_error(jsi::Runtime &rt, const std::string &message, std::string database_closed_message(const char *function_name); /// `function_name` names the call in the "database is closed" rejection when -/// the pool has already been shut down. It must be a string literal. +/// the worker thread has already been shut down. It must be a string literal. jsi::Value promisify(jsi::Runtime &rt, const char *function_name, - std::shared_ptr thread_pool, + std::shared_ptr worker_thread, std::function lambda, std::function resolve_callback); diff --git a/cpp/OPWorkerThread.cpp b/cpp/OPWorkerThread.cpp new file mode 100644 index 00000000..62ae4764 --- /dev/null +++ b/cpp/OPWorkerThread.cpp @@ -0,0 +1,79 @@ +#include "OPWorkerThread.hpp" + +namespace opsqlite { + +WorkerThread::WorkerThread() : thread(&WorkerThread::do_work, this) { + thread_id = thread.get_id(); +} + +// Joins the thread so the process (or in our RN case, this +// main-thread/runtime generation) can exit gracefully. A no-op when shutdown() +// already ran. +WorkerThread::~WorkerThread() { shutdown(); } + +void WorkerThread::shutdown() { + // Checked before call_once: on the worker thread it could otherwise block on + // another caller's join of this very thread. + if (std::this_thread::get_id() == thread_id) { + throw std::system_error( + std::make_error_code(std::errc::resource_deadlock_would_occur), + "[op-sqlite] WorkerThread::shutdown() called from its own thread"); + } + + std::call_once(shutdown_once, [this] { + { + // Set under the mutex so the thread, between its predicate check and + // its wait, cannot miss the wake-up below. + std::lock_guard g(mutex); + done = true; + } + work_pending.notify_one(); + thread.join(); + }); +} + +// Called by the database and prepared statement host objects (through +// promisify and the reactive flush) for every async call +void WorkerThread::queue_work(const std::function &task) { + { + std::lock_guard g(mutex); + + // A stopped worker has no thread left to run the task, and its promise + // would never settle. Callers map this to their own "database is closed" + // error. + if (done) { + throw WorkerThreadStoppedError(); + } + + work_queue.push(task); + } + + work_pending.notify_one(); +} + +void WorkerThread::do_work() { + while (true) { + std::function task; + + // Create a scope, so we don't lock the queue for longer than necessary + { + std::unique_lock g(mutex); + work_pending.wait(g, [&] { return done || !work_queue.empty(); }); + + // Shutting down: finish only once every queued task has run, so no + // promise is left unsettled. + if (work_queue.empty()) { + return; + } + + task = std::move(work_queue.front()); + work_queue.pop(); + } + + // The task (and everything it captured, e.g. JSI values) is released at + // the end of this iteration, before the thread can exit and be joined. + task(); + } +} + +} // namespace opsqlite diff --git a/cpp/OPWorkerThread.hpp b/cpp/OPWorkerThread.hpp new file mode 100644 index 00000000..4321b7c3 --- /dev/null +++ b/cpp/OPWorkerThread.hpp @@ -0,0 +1,75 @@ +#pragma once + +#include +#include +#include +#include +#include +#include +#include + +namespace opsqlite { + +// Thrown by queue_work() once the worker has been shut down. WorkerThread knows +// nothing about databases; callers map this to their own "database is closed" +// error. +class WorkerThreadStoppedError : public std::runtime_error { +public: + WorkerThreadStoppedError() + : std::runtime_error("[op-sqlite] worker thread is stopped") {} +}; + +// Runs a connection's async work, one task at a time, on a single background +// thread. To keep sqlite's threading model working a connection must not be +// used from several threads at once, so each connection gets exactly one +// (more threads were faster but raced; requested by PowerSync). +// +// Rule: a task must never own the WorkerThread it runs on, nor call +// shutdown(). The thread cannot join itself (shutdown() throws +// std::system_error). No task does today: the tasks queued by promisify and +// the reactive flush capture the database or the statement by raw pointer. +class WorkerThread { +public: + WorkerThread(); + ~WorkerThread(); + // Throws WorkerThreadStoppedError after shutdown(). + void queue_work(const std::function &task); + // Stops the worker: no new work is accepted, every task already queued still + // runs (so no promise is left unsettled), then the thread is joined. Called + // by close()/delete()/invalidate() rather than leaving it to the destructor, + // because the WorkerThread is shared with prepared statements and pending + // promises and may outlive the database until the JS object is garbage + // collected. + // + // Idempotent and safe to call concurrently: a later caller blocks until the + // first caller's join has completed. + void shutdown(); + +private: + // Protects work_queue and done + std::mutex mutex; + + // Signalled when work is queued or the worker is shutting down + std::condition_variable work_pending; + + // Tasks waiting to run, in order + std::queue> work_queue; + + // Set by shutdown(). queue_work() then refuses new work, and the thread + // exits once the queue is empty. + bool done = false; + + std::once_flag shutdown_once; + + // Declared last so it starts only once everything above is constructed. If + // it fails to start, nothing else needs cleaning up. + std::thread thread; + + // Written only by the constructor, so shutdown() can read it without a lock + std::thread::id thread_id; + + // The thread's loop: runs queued tasks until shut down and drained + void do_work(); +}; + +} // namespace opsqlite diff --git a/example/src/tests/hooks.ts b/example/src/tests/hooks.ts index 1b623dc2..798c85ea 100644 --- a/example/src/tests/hooks.ts +++ b/example/src/tests/hooks.ts @@ -251,7 +251,7 @@ describe("Hooks", () => { // capture raw `this` in the invoker->invokeAsync lambda and read // commit_hook_callback/rollback_hook_callback (members of OPDatabase) when // the lambda finally ran on the JS thread. close()/delete() only drain the - // native thread pool, not the invoker queue, so a db freed right after the + // native worker thread, not the invoker queue, so a db freed right after the // hook fires but before the queued callback runs would leave that lambda // dereferencing a dangling OPDatabase. Closing/deleting immediately after // triggering the hook - without waiting for its callback to run - recreates diff --git a/scripts/test-thread-pool.sh b/scripts/test-worker-thread.sh similarity index 60% rename from scripts/test-thread-pool.sh rename to scripts/test-worker-thread.sh index 38691073..ac0cd058 100755 --- a/scripts/test-thread-pool.sh +++ b/scripts/test-worker-thread.sh @@ -1,13 +1,13 @@ #!/bin/bash -# Builds scripts/thread_pool_check.cpp against cpp/OPThreadPool.cpp and runs it +# Builds scripts/worker_thread_check.cpp against cpp/OPWorkerThread.cpp and runs it # under ThreadSanitizer and AddressSanitizer. No React Native toolchain needed. # -# scripts/test-thread-pool.sh # both sanitizers -# scripts/test-thread-pool.sh thread # one of them +# scripts/test-worker-thread.sh # both sanitizers +# scripts/test-worker-thread.sh thread # one of them set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" -OUT="${TMPDIR:-/tmp}/op-sqlite-thread-pool-check" +OUT="${TMPDIR:-/tmp}/op-sqlite-worker-thread-check" mkdir -p "$OUT" sanitizers=("$@") @@ -19,7 +19,7 @@ for sanitizer in "${sanitizers[@]}"; do echo "== -fsanitize=$sanitizer" "${CXX:-clang++}" -std=c++17 -O1 -g -fno-omit-frame-pointer \ -fsanitize="$sanitizer" -I "$ROOT/cpp" \ - "$ROOT/cpp/OPThreadPool.cpp" "$ROOT/scripts/thread_pool_check.cpp" \ + "$ROOT/cpp/OPWorkerThread.cpp" "$ROOT/scripts/worker_thread_check.cpp" \ -o "$OUT/check-$sanitizer" "$OUT/check-$sanitizer" done diff --git a/scripts/thread_pool_check.cpp b/scripts/worker_thread_check.cpp similarity index 62% rename from scripts/thread_pool_check.cpp rename to scripts/worker_thread_check.cpp index c40ee201..3b7c09de 100644 --- a/scripts/thread_pool_check.cpp +++ b/scripts/worker_thread_check.cpp @@ -1,12 +1,12 @@ -// Standalone lifecycle checks for cpp/OPThreadPool.cpp. No React Native, no -// JSI: it compiles the pool on its own and drives it the way OPDatabase does. +// Standalone lifecycle checks for cpp/OPWorkerThread.cpp. No React Native, no +// JSI: it compiles WorkerThread on its own and drives it the way OPDatabase +// does. // Run it under ThreadSanitizer and AddressSanitizer with -// scripts/test-thread-pool.sh. +// scripts/test-worker-thread.sh. // -// Every check runs under a watchdog: a hang (a wait_finished() that never -// returns, a join that never completes) is reported as a failure instead of -// stalling the run. -#include "OPThreadPool.hpp" +// Every check runs under a watchdog: a hang (a join that never completes) is +// reported as a failure instead of stalling the run. +#include "OPWorkerThread.hpp" #include #include @@ -27,8 +27,8 @@ #include #endif -using opsqlite::ThreadPool; -using opsqlite::ThreadPoolStoppedError; +using opsqlite::WorkerThread; +using opsqlite::WorkerThreadStoppedError; using namespace std::chrono_literals; static int thread_count() { @@ -110,60 +110,60 @@ struct Gate { } }; -// (a) close() frees the worker now, while the pool is still referenced (by a -// prepared statement, or by the JS object awaiting GC). -static void closed_pools_release_their_threads() { +// (a) close() frees the thread now, while the WorkerThread is still referenced +// (by a prepared statement, or by the JS object awaiting GC). +static void closed_workers_release_their_threads() { const int base = thread_count(); - std::vector> held; + std::vector> held; for (int i = 0; i < 300; i++) { - auto pool = std::make_shared(); + auto worker = std::make_shared(); std::atomic ran{false}; - pool->queue_work([&] { ran = true; }); - pool->shutdown(); + worker->queue_work([&] { ran = true; }); + worker->shutdown(); if (!ran) { check(false, "work queued before shutdown ran"); } - held.push_back(pool); + held.push_back(worker); } const int extra = thread_count() - base; - check(extra <= 1, "300 shut down pools, still referenced, leave <= 1 extra " - "thread (extra=" + + check(extra <= 1, "300 shut down workers, still referenced, leave <= 1 " + "extra thread (extra=" + std::to_string(extra) + ")"); } -// (b) Work queued on a stopped pool is refused with the pool's own error, so a -// promise rejects instead of waiting on a queue nobody drains. +// (b) Work queued on a stopped worker is refused with the worker's own error, +// so a promise rejects instead of waiting on a queue nobody drains. static void queue_after_shutdown_throws() { - auto pool = std::make_shared(); - pool->shutdown(); + auto worker = std::make_shared(); + worker->shutdown(); bool threw = false; std::string what; try { - pool->queue_work([] {}); - } catch (const ThreadPoolStoppedError &e) { + worker->queue_work([] {}); + } catch (const WorkerThreadStoppedError &e) { threw = true; what = e.what(); } - check(threw, "queue_work after shutdown throws ThreadPoolStoppedError"); - check(what == "[op-sqlite] thread pool is stopped", - "the error is the pool's generic one (\"" + what + "\")"); - pool->wait_finished(); - check(true, "wait_finished after shutdown returns"); + check(threw, "queue_work after shutdown throws WorkerThreadStoppedError"); + check(what == "[op-sqlite] worker thread is stopped", + "the error is the worker's generic one (\"" + what + "\")"); + worker->shutdown(); + check(true, "a second shutdown returns"); } -// (c) Tasks queued before shutdown() all run before it returns, with or -// without a wait_finished() first, and on the destructor path too. +// (c) Tasks queued before shutdown() all run before it returns, and on the +// destructor path too. static void queued_tasks_drain_on_shutdown() { { - auto pool = std::make_shared(); + auto worker = std::make_shared(); Gate gate; std::atomic ran{0}; - pool->queue_work([&] { + worker->queue_work([&] { gate.wait(); ran++; }); for (int i = 0; i < 50; i++) { - pool->queue_work([&] { ran++; }); + worker->queue_work([&] { ran++; }); } // The worker is parked in the first task, so all 50 are still queued // when shutdown() starts. @@ -171,11 +171,9 @@ static void queued_tasks_drain_on_shutdown() { std::this_thread::sleep_for(20ms); gate.release(); }); - pool->shutdown(); + worker->shutdown(); check(ran == 51, "shutdown() drains the queue before returning (ran=" + std::to_string(ran.load()) + "/51)"); - pool->wait_finished(); - check(true, "wait_finished after a draining shutdown returns"); opener.join(); } { @@ -183,19 +181,19 @@ static void queued_tasks_drain_on_shutdown() { Gate gate; std::thread opener; { - auto pool = std::make_shared(); - pool->queue_work([&] { + auto worker = std::make_shared(); + worker->queue_work([&] { gate.wait(); ran++; }); for (int i = 0; i < 50; i++) { - pool->queue_work([&] { ran++; }); + worker->queue_work([&] { ran++; }); } opener = std::thread([&] { std::this_thread::sleep_for(20ms); gate.release(); }); - } // ~ThreadPool, no shutdown() and no wait_finished() before it + } // ~WorkerThread, no shutdown() before it check(ran == 51, "the destructor drains the queue too (ran=" + std::to_string(ran.load()) + "/51)"); opener.join(); @@ -207,10 +205,10 @@ static void queued_tasks_drain_on_shutdown() { // would free the mutex, condition variable and queue under it. static void concurrent_shutdowns_then_destructor() { for (int round = 0; round < 20; round++) { - auto *pool = new ThreadPool(); + auto *worker = new WorkerThread(); Gate started; std::atomic task_finished{false}; - pool->queue_work([&] { + worker->queue_work([&] { started.release(); std::this_thread::sleep_for(30ms); task_finished = true; @@ -220,30 +218,30 @@ static void concurrent_shutdowns_then_destructor() { std::atomic first_saw_finished{false}; std::atomic second_saw_finished{false}; std::thread first([&] { - pool->shutdown(); + worker->shutdown(); first_saw_finished = task_finished.load(); }); std::thread second([&] { - // Start only once `first` has stopped the pool (queue_work refuses + // Start only once `first` has stopped the worker (queue_work refuses // work from then on) and is on its way into the join. while (true) { try { - pool->queue_work([] {}); - } catch (const ThreadPoolStoppedError &) { + worker->queue_work([] {}); + } catch (const WorkerThreadStoppedError &) { break; } std::this_thread::sleep_for(1ms); } std::this_thread::sleep_for(5ms); - pool->shutdown(); + worker->shutdown(); second_saw_finished = task_finished.load(); if (!second_saw_finished) { - // Report before the delete below, which then frees the pool under + // Report before the delete below, which then frees the worker under // the running worker. check(false, "the second shutdown() returned before the join " "completed"); } - delete pool; // ~ThreadPool right after a shutdown() returned + delete worker; // ~WorkerThread right after a shutdown() returned }); first.join(); second.join(); @@ -258,52 +256,44 @@ static void concurrent_shutdowns_then_destructor() { "the join (20 rounds)"); } -// (e) shutdown() from a task on the pool's own worker, as OPDatabase's -// invalidate()/destructor would if it ran there. It must not self-join, it -// must not hang, the tasks behind it must still run, and `busy` must be -// released so wait_finished() returns. -static void shutdown_from_the_worker() { - auto pool = std::make_shared(); +// (e) shutdown() from a task running on the worker breaks the rule in the +// header. It must fail loudly (std::system_error from the self-join) rather +// than hang or terminate, the tasks behind it must still run, and a later +// shutdown() from another thread must still join the worker cleanly. +static void shutdown_from_the_worker_throws() { + auto worker = std::make_shared(); Gate queued; std::atomic after{0}; - std::atomic after_seen_by_shutdown{-1}; std::atomic threw_on_worker{false}; - pool->queue_work([&] { + worker->queue_work([&] { queued.wait(); - pool->shutdown(); - // Runs the rest inline: nothing is left to run once shutdown() returns. - after_seen_by_shutdown = after.load(); try { - pool->queue_work([] {}); - } catch (const ThreadPoolStoppedError &) { + worker->shutdown(); + } catch (const std::system_error &) { threw_on_worker = true; } }); for (int i = 0; i < 10; i++) { - pool->queue_work([&] { after++; }); + worker->queue_work([&] { after++; }); } - queued.release(); - pool->wait_finished(); // hangs if do_work never decremented busy - check(true, "wait_finished returns after shutdown() ran on the worker"); - check(after_seen_by_shutdown == 10, - "shutdown() on the worker ran the queued tasks before returning " - "(saw " + - std::to_string(after_seen_by_shutdown.load()) + "/10)"); - check(threw_on_worker, "queue_work from the worker after its shutdown " - "throws"); - pool->wait_finished(); - check(true, "a second wait_finished also returns"); - pool->shutdown(); // joins the worker, which exited on its own - check(true, "shutdown() from another thread then joins the worker"); - pool.reset(); - check(true, "destructor after a worker-side shutdown"); + // Release the worker while this thread is already in its own shutdown(): + // the worker's call must throw rather than wait on a join of itself. + std::thread opener([&] { + std::this_thread::sleep_for(20ms); + queued.release(); + }); + worker->shutdown(); + opener.join(); + check(threw_on_worker, "shutdown() on the worker throws std::system_error"); + check(after == 10, "the tasks queued behind it still ran (" + + std::to_string(after.load()) + "/10)"); + worker.reset(); + check(true, "destructor after a worker-side shutdown attempt"); } // (f) A constructor that cannot start its thread throws without terminating -// the process. The pool starts one thread, so this exercises the failure of -// the first (and only) one; the catch block's join of already-started -// threads matters only if number_of_threads is raised. +// the process. static void constructor_throw_is_clean() { std::mutex m; std::condition_variable cv; @@ -324,7 +314,7 @@ static void constructor_throw_is_clean() { bool threw = false; if (exhausted) { try { - ThreadPool pool; + WorkerThread worker; } catch (const std::system_error &) { threw = true; } @@ -345,22 +335,23 @@ static void constructor_throw_is_clean() { check(threw, "constructor throws std::system_error when its thread cannot " "start, without std::terminate (after " + std::to_string(hogs.size()) + " threads)"); - // The pool still works once threads are available again. - ThreadPool pool; + // The worker still works once threads are available again. + WorkerThread worker; std::atomic ran{false}; - pool.queue_work([&] { ran = true; }); - pool.shutdown(); - check(ran, "a pool constructed afterwards works"); + worker.queue_work([&] { ran = true; }); + worker.shutdown(); + check(ran, "a worker constructed afterwards works"); } int main() { - with_watchdog("(a) closed pools release threads", 30s, - closed_pools_release_their_threads); + with_watchdog("(a) closed workers release threads", 30s, + closed_workers_release_their_threads); with_watchdog("(b) queue after shutdown", 10s, queue_after_shutdown_throws); with_watchdog("(c) drain on shutdown", 10s, queued_tasks_drain_on_shutdown); with_watchdog("(d) concurrent shutdowns + destructor", 30s, concurrent_shutdowns_then_destructor); - with_watchdog("(e) shutdown from the worker", 10s, shutdown_from_the_worker); + with_watchdog("(e) shutdown from the worker", 10s, + shutdown_from_the_worker_throws); if (std::getenv("SKIP_CONSTRUCTOR_THROW") == nullptr) { with_watchdog("(f) constructor throw", 60s, constructor_throw_is_clean); } From b14e5b72db41c25615b878fa40cd055ed589bdeb Mon Sep 17 00:00:00 2001 From: Oscar Franco Date: Mon, 26 Oct 2026 11:30:24 -0600 Subject: [PATCH 5/5] Small simplification --- src/functions.ts | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/functions.ts b/src/functions.ts index 9fa528b4..d26722ef 100644 --- a/src/functions.ts +++ b/src/functions.ts @@ -175,14 +175,10 @@ function enhanceDB(db: _InternalDB, options: DBParams): DB { bindSync: (params: Scalar[]) => { stmt.bindSync(params); }, - bind: async (params: Scalar[]) => { - await stmt.bind(params); - }, + bind: async (params: Scalar[]) => stmt.bind(params), // async, like bind: a native throw (e.g. database is closed) becomes // a rejection, as it does for db.execute - execute: async () => { - return await stmt.execute(); - }, + execute: async () => stmt.execute(), executeSync: stmt.executeSync, }; },