Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## [1.4.3] - 2026-11-16

This release adds one C function, `sqlitejs_cancel_all()`, for a host that has no other way to stop
JavaScript that does not come back. Nothing changes for an application that never calls it: SQL and
JavaScript behave exactly as on 1.4.2 until a cancel arrives.

### Added

- **`sqlitejs_cancel_all()` stops all JavaScript running now, in every connection.** Each call into JavaScript fails with an "interrupted" error, even code that catches every exception, and JavaScript that begins afterwards runs normally. It is safe to call from any thread, and it works on every SQLite version, including those before 3.41.0 where `sqlite3_interrupt()` cannot reach JavaScript at all. It exists for hosts whose own cancelling cannot: Android cancels a query with a progress handler, which SQLite never calls while a function is running, and Room 2.7 and later pass no cancellation signal at all, so a runaway function could previously only be stopped by killing the process. **The connection whose JavaScript is stopped is interrupted as well**, as `sqlite3_interrupt()` does it, because a collation cannot report an error and its sort would otherwise go on calling JavaScript, each call beginning after the cancel; so any other statement that connection has in progress fails with SQLITE_INTERRUPT too, and `sqlite3_is_interrupted()` stays true for it until the connection next prepares or steps a statement with none of its own still running. The function is declared in `sqlitejs.h` and exported from the Windows DLL.
- **A result set the cancelled call left open reads on as "interrupted"**, where 1.4.2 says it was closed when the call that created it returned. Ending such a result set runs the `final` of the window or aggregate function its statement was computing, and those finals belong to the call that is being cancelled: one that never ends is stopped, and its statement fails with an interrupt, rather than hanging the statement for good on SQLite before 3.41.0. A short `final` can still run to its end before the engine's next interrupt check.
- **A cancel never stops the JavaScript the extension itself runs to set a connection up**, so a connection opening while cancels are in flight still comes up complete: neither the code run while the extension loads nor the functions `js_init_table(1)` restores from the `js_functions` table are cancelled. Only that work is exempt — JavaScript it reaches through SQL is a call of its own and is cancelled — and on SQLite 3.41.0 and later `sqlite3_interrupt()` still stops setup JavaScript that never ends.

## [1.4.2] - 2026-11-13

One change in this release can alter the behavior of JavaScript that works on 1.4.1: a `db.exec()`
Expand Down
1 change: 1 addition & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ ifeq ($(PLATFORM),windows)
@echo " sqlite3_js_init" >> $@
@echo " sqlitejs_version" >> $@
@echo " quickjs_version" >> $@
@echo " sqlitejs_cancel_all" >> $@
endif

# Clean up
Expand Down
78 changes: 75 additions & 3 deletions src/sqlitejs.c
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,13 @@ typedef struct {
size_t mem_peak; // the most in use since the last result or error
size_t stack_size; // in bytes, 0 for no check: see js_set_max_stack_size()
int depth; // calls into JavaScript in progress: see js_enter()
unsigned cancel_epoch; // js_cancel_epoch when the outermost call began
int setup_depth; // depth of a call that sets the connection up, 0 for none: see js_interrupt_handler()
bool check_interrupted; // sqlite3_is_interrupted() is available
struct rowset *rowsets; // result sets not yet freed: see js_end_rowsets()
int orphans; // of those, the ones whose JavaScript object is gone
bool ending_rowsets; // js_end_rowsets() is running
unsigned end_pass; // js_end_rowsets() passes that ended every result set
} globaljs_context;

typedef struct {
Expand Down Expand Up @@ -115,6 +119,7 @@ typedef struct rowset {
bool ended; // ended by js_end_rowsets(): reading on throws
bool interrupted; // and an interrupt is why: reading on throws "interrupted"
bool orphaned; // its JavaScript object is gone: see js_rowset_finalizer()
unsigned end_pass; // the js_end_rowsets() pass that ended it
struct rowset *prev, *next; // in the connection's list: see js_end_rowsets()
} rowset;

Expand Down Expand Up @@ -270,9 +275,12 @@ static void js_rowset_finalizer(JSRuntime *rt, JSValue val) {
// computing, whose js_leave() comes back here and whose garbage collection can free result sets
// of the list. So each statement is taken from its result set before it is finalized, the list
// is walked again from its head after each one, and a nested call does nothing.
static unsigned js_cancel_epoch_load (void);

static void js_end_rowsets (globaljs_context *js, bool all, bool interrupted) {
if (js->ending_rowsets) return;
js->ending_rowsets = true;
unsigned pass = all ? ++js->end_pass : 0;
for (;;) {
rowset *rs = js->rowsets;
while (rs && !(rs->orphaned || (all && rs->vm))) rs = rs->next;
Expand All @@ -289,10 +297,17 @@ static void js_end_rowsets (globaljs_context *js, bool all, bool interrupted) {
} else {
rs->vm = NULL;
rs->ended = true;
rs->end_pass = pass;
if (interrupted) rs->interrupted = true;
}
if (vm) sqlite3_finalize(vm);
}
// A cancel that landed while the finals ran stopped them, as one before the call returned
// would have: the result sets this pass ended read on as interrupted too. Nothing runs
// JavaScript here, so the list holds only result sets that are still allocated.
if (all && !interrupted && (js->cancel_epoch != js_cancel_epoch_load())) {
for (rowset *r = js->rowsets; r; r = r->next) if (r->ended && (r->end_pass == pass)) r->interrupted = true;
}
js->ending_rowsets = false;
}

Expand Down Expand Up @@ -325,14 +340,55 @@ static void js_collect_below_limit (globaljs_context *js) {
js_keep_gc_below_limit(js);
}

// Bumped by sqlitejs_cancel_all(): JavaScript that began before stops, as if interrupted.
static unsigned js_cancel_epoch;

static unsigned js_cancel_epoch_load (void) {
#if defined(__clang__) || defined(__GNUC__)
return __atomic_load_n(&js_cancel_epoch, __ATOMIC_ACQUIRE);
#else
return *(volatile unsigned *)&js_cancel_epoch;
#endif
}

// Stops all JavaScript that is running now, in every connection: each call fails with an
// "interrupted" error, and the connection it was running on is interrupted, so every statement
// that connection has in progress fails with SQLITE_INTERRUPT too (see js_interrupt_handler).
// JavaScript that begins afterwards runs normally, and the JavaScript the extension itself runs
// to set a connection up is never stopped. Safe from any thread.
// For hosts whose own cancelling cannot reach JavaScript: Android cancels a query with a
// progress handler, which SQLite never calls while a JavaScript function runs.
void sqlitejs_cancel_all (void) {
#if defined(__clang__) || defined(__GNUC__)
__atomic_add_fetch(&js_cancel_epoch, 1, __ATOMIC_RELEASE);
#else
(*(volatile unsigned *)&js_cancel_epoch)++;
#endif
}

// QuickJS calls this from time to time while it runs code. A non-zero result stops the code
// with an uncatchable "interrupted" error, so sqlite3_interrupt() (Ctrl-C in the sqlite3 shell,
// a cancelled query in an app) also stops JavaScript that never returns to SQLite.
static int js_interrupt_handler (JSRuntime *rt, void *opaque) {
UNUSED(rt);
globaljs_context *js = (globaljs_context *)opaque;
js_keep_gc_below_limit(js);
return (js->db != NULL) && sqlite3_is_interrupted(js->db);
// Only a call (see js_enter) is cancelled, and never the JavaScript the extension itself runs
// to set a connection up: while it loads the extension (globaljs_init, depth 0), and while
// js_init_table(1) restores the functions of the js_functions table (js_create_common, which
// records its depth in setup_depth). Stopping either leaves the connection short of what an
// app expects of it: a cancel during the first made it fail to load, and one during the second
// left it without its stored functions, each reported only by a statement an app need not look
// at. Like the depth 0 exemption, this one covers that call alone: JavaScript the loading code
// runs through SQL is a call of its own, at a greater depth, and is cancelled. And on SQLite
// 3.41 and later sqlite3_interrupt() still stops setup JavaScript that never ends, as always.
if ((js->depth > 0) && (js->depth != js->setup_depth) && (js->cancel_epoch != js_cancel_epoch_load())) {
// The statement is interrupted too: a collation cannot report an error, so the
// statement would go on calling JavaScript, each call beginning after the cancel.
if (js->db) sqlite3_interrupt(js->db);
return 1;
}
return js->check_interrupted && (js->db != NULL) && sqlite3_is_interrupted(js->db);
}

// The most memory, in bytes, the JavaScript runtime of a connection may allocate until
Expand Down Expand Up @@ -542,6 +598,10 @@ static bool js_stack_room (size_t *room) {
// runs JavaScript) is on the same thread and keeps the outer call's limit.
static void js_enter (globaljs_context *js) {
if (js->depth++ > 0) return;
// The finals that ending a call's result sets runs (see js_leave) belong to that call: they keep
// its epoch, so a cancel during the call or during the ending stops them, as it would have
// stopped the call. Before SQLite 3.41 nothing else would stop one that never ends.
if (!js->ending_rowsets) js->cancel_epoch = js_cancel_epoch_load();
JS_UpdateStackTop(js->runtime);
// A thread with less room than SQLITE_JS_STACK_MIN keeps it too: JavaScript there then fails
// with "Maximum call stack size exceeded" rather than running past the end of the stack. A
Expand All @@ -556,6 +616,8 @@ static void js_enter (globaljs_context *js) {
static void js_leave (globaljs_context *js) {
if (--js->depth > 0) return;
if (!js->rowsets) return;
// A cancel (sqlitejs_cancel_all) is not seen here: js_end_rowsets() marks its result sets
// interrupted itself, which is the only way they read so before SQLite 3.41.
bool interrupted = (sqlite3_libversion_number() >= 3041000) && js->db && sqlite3_is_interrupted(js->db);
js_end_rowsets(js, true, interrupted);
}
Expand All @@ -577,8 +639,9 @@ static globaljs_context *globaljs_init (sqlite3 *db) {
//JS_SetMaxStackSize(rt, 10 * 1024);

// sqlite3_is_interrupted() is new in SQLite 3.41.0: an older library has no such entry
// in its sqlite3_api_routines, so JavaScript cannot be interrupted there
if (sqlite3_libversion_number() >= 3041000) JS_SetInterruptHandler(rt, js_interrupt_handler, js);
// in its sqlite3_api_routines, so JavaScript cannot be interrupted there, only cancelled
js->check_interrupted = (sqlite3_libversion_number() >= 3041000);
JS_SetInterruptHandler(rt, js_interrupt_handler, js);

// the default stack size must fit in the stack of the thread that loads the extension: Windows
// gives a main thread 1 MB, and apps often give their threads no more
Expand Down Expand Up @@ -900,6 +963,7 @@ static JSValue js_sqlite_exec (JSContext *ctx, sqlite3 *db, const char *sql, int
rs->vm = vm;
rs->ncols = sqlite3_column_count(vm);
rs->ended = false;
rs->end_pass = 0;
rs->interrupted = false;
rs->orphaned = false;
rs->prev = rs->next = NULL;
Expand Down Expand Up @@ -1612,7 +1676,15 @@ static bool js_create_function (sqlite3_context *context, const char *type, cons
bool js_create_common (sqlite3_context *context, const char *type, const char *name, const char *init_code, const char *step_code, const char *final_code, const char *value_code, const char *inverse_code, bool is_load) {
globaljs_context *js = (globaljs_context *)sqlite3_user_data(context);
js_enter(js);
// Restoring a function of the js_functions table (is_load) sets the connection up, as loading
// the extension does, so sqlitejs_cancel_all() does not stop it: see js_interrupt_handler().
// Only this call is exempt, not JavaScript it runs through SQL, which is a call of its own at
// a greater depth. The previous value is kept for an is_load that a stored function's own code
// reaches through js_init_table().
int setup_depth = js->setup_depth;
if (is_load) js->setup_depth = js->depth;
bool ok = js_create_function(context, type, name, init_code, step_code, final_code, value_code, inverse_code, is_load);
js->setup_depth = setup_depth;
js_leave(js);
return ok;
}
Expand Down
14 changes: 13 additions & 1 deletion src/sqlitejs.h
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,22 @@
#include "sqlite3.h"
#endif

#define SQLITE_JS_VERSION "1.4.2"
#define SQLITE_JS_VERSION "1.4.3"

int sqlite3_js_init (sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi);
const char *sqlitejs_version (void);
const char *quickjs_version (void);
// Stops all JavaScript now running, in every connection: each call into JavaScript fails with an
// "interrupted" error, and a result set it leaves open reads on as interrupted. Safe to call from
// any thread.
// It stops only JavaScript already running: calls that begin afterwards are not affected, and
// neither is the JavaScript the extension itself runs to set a connection up, while it loads the
// extension and while js_init_table(1) restores the functions of the js_functions table.
// A connection whose JavaScript is stopped is also interrupted, as sqlite3_interrupt() does it:
// a collation cannot report an error, so without that its sort would go on calling JavaScript.
// So any other statement that connection has in progress fails with SQLITE_INTERRUPT as well,
// and sqlite3_is_interrupted() stays true for it until the connection next prepares or steps a
// statement with none of its own still running, as after any sqlite3_interrupt().
void sqlitejs_cancel_all (void);

#endif
Loading
Loading