From 304ddf643db4f6ae8cbfe805939194c80df6a1a3 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 11:04:21 +0000 Subject: [PATCH] fix(data): never block the caller's thread and never lose a SQLite cancel SQLite steps ran synchronously on the calling thread, so a repository awaited on the WPF UI thread would freeze the window for the length of the query. Blocking calls now continue on the thread pool. A cancel that landed before sqlite3_step started the statement was lost (SQLite clears the interrupt when no statement is running) and the query ran to completion. Each connection now has a cancel flag polled by a progress handler; it is cleared outside every interruptible operation so a stale cancel cannot stop a later statement. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- docs/DECISIONS.md | 1 + src/Titano.Data/Sqlite/SqliteConnection.cs | 27 +++++++++++++-- src/Titano.Data/Sqlite/SqliteNative.cs | 1 + src/Titano.Data/Sqlite/SqliteSession.cs | 33 ++++++++++++++++--- src/Titano.Data/Sqlite/ThreadPoolHop.cs | 23 +++++++++++++ .../Sqlite/SqliteBindingTests.cs | 20 +++++++++++ 6 files changed, 98 insertions(+), 7 deletions(-) create mode 100644 src/Titano.Data/Sqlite/ThreadPoolHop.cs diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index df6a5afa..69f01b5c 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -80,3 +80,4 @@ One line per decision: date · decision · alternative · reason. | 2026-10-02 | Uploader settings are an in-window panel; single instance via a per-session mutex and a current-user named pipe; native tray menu (`TrackPopupMenuEx`). | Dialog / WM_COPYDATA / WPF ContextMenu | §12.1 allows modals only for login and destructive confirmations; works while hidden in the tray; dismisses reliably. | | 2026-10-02 | Network watch folders are polled (default 5 min); local folders every 60 s plus `FileSystemWatcher` hints. | Watcher everywhere | SMB change notifications are unreliable. | | 2026-10-02 | The Dockerfile uses BuildKit's built-in frontend (no `# syntax=docker/dockerfile:1`). | Pinned external frontend | Every feature used is built in; the build no longer depends on Docker Hub (a 502 there failed CI). Base images come from mcr.microsoft.com. | +| 2026-10-02 | SQLite sessions run every blocking call on the thread pool (`ThreadPoolHop`) and cancel through a per-connection flag polled by `sqlite3_progress_handler` (every 1000 VM instructions) in addition to `sqlite3_interrupt`. | Callers offload themselves / interrupt only | A repository awaited on the UI thread never freezes it; an interrupt that lands before `sqlite3_step` starts was silently lost and the query ran to the end. | diff --git a/src/Titano.Data/Sqlite/SqliteConnection.cs b/src/Titano.Data/Sqlite/SqliteConnection.cs index b81c7f10..6d5d5761 100644 --- a/src/Titano.Data/Sqlite/SqliteConnection.cs +++ b/src/Titano.Data/Sqlite/SqliteConnection.cs @@ -1,3 +1,4 @@ +using System.Runtime.InteropServices; using System.Text; using static Titano.Data.Sqlite.SqliteNative; @@ -11,10 +12,20 @@ internal sealed unsafe class SqliteConnection : IDisposable "PRAGMA synchronous=NORMAL; PRAGMA foreign_keys=ON; PRAGMA temp_store=MEMORY; " + "PRAGMA cache_size=-65536; PRAGMA mmap_size=268435456;"; + // SQLite polls the cancel flag every ProgressInterval VM instructions. sqlite3_interrupt alone is lost when it + // lands before sqlite3_step starts the statement (SQLite clears it when no statement is running). + private const int ProgressInterval = 1000; + private readonly Dictionary> _cache = new(StringComparer.Ordinal); private readonly LinkedList _lru = new(); + private int* _cancel; - private SqliteConnection(nint handle) => Handle = handle; + private SqliteConnection(nint handle) + { + Handle = handle; + _cancel = (int*)NativeMemory.AllocZeroed(sizeof(int)); + sqlite3_progress_handler(handle, ProgressInterval, &OnProgress, (nint)_cancel); + } public nint Handle { get; private set; } @@ -111,7 +122,14 @@ internal sealed unsafe class SqliteConnection : IDisposable else statement.Dispose(); } - public void Interrupt() => sqlite3_interrupt(Handle); + /// Stops the running statement, or the next one if none has started yet, until . + public void Interrupt() + { + Volatile.Write(ref *_cancel, 1); + sqlite3_interrupt(Handle); + } + + public void ClearInterrupt() => Volatile.Write(ref *_cancel, 0); public SqliteException Error(int rc) => new(Utf8(sqlite3_errmsg(Handle)) ?? $"SQLite error {rc}", rc); @@ -123,8 +141,13 @@ internal sealed unsafe class SqliteConnection : IDisposable _cache.Clear(); sqlite3_close_v2(Handle); Handle = 0; + NativeMemory.Free(_cancel); + _cancel = null; } + [UnmanagedCallersOnly] + private static int OnProgress(nint cancel) => Volatile.Read(ref *(int*)cancel); + private SqliteStatement Prepare(string sql) { var bytes = Encoding.UTF8.GetBytes(SqliteSqlText.TranslatePlaceholders(sql)); diff --git a/src/Titano.Data/Sqlite/SqliteNative.cs b/src/Titano.Data/Sqlite/SqliteNative.cs index b86a4c77..f485ce37 100644 --- a/src/Titano.Data/Sqlite/SqliteNative.cs +++ b/src/Titano.Data/Sqlite/SqliteNative.cs @@ -77,6 +77,7 @@ internal static unsafe class SqliteNative [DllImport(Library, ExactSpelling = true)] public static extern void sqlite3_free(void* p); [DllImport(Library, ExactSpelling = true)] public static extern byte* sqlite3_errmsg(nint db); [DllImport(Library, ExactSpelling = true)] public static extern void sqlite3_interrupt(nint db); + [DllImport(Library, ExactSpelling = true)] public static extern void sqlite3_progress_handler(nint db, int instructions, delegate* unmanaged callback, nint arg); [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_changes(nint db); [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_total_changes(nint db); [DllImport(Library, ExactSpelling = true)] public static extern int sqlite3_get_autocommit(nint db); diff --git a/src/Titano.Data/Sqlite/SqliteSession.cs b/src/Titano.Data/Sqlite/SqliteSession.cs index 4954f572..9045a39b 100644 --- a/src/Titano.Data/Sqlite/SqliteSession.cs +++ b/src/Titano.Data/Sqlite/SqliteSession.cs @@ -7,7 +7,7 @@ namespace Titano.Data.Sqlite; /// /// A pooled SQLite connection. Statements that write take the database write lock for their duration when no /// transaction holds it already; lock conflicts are retried (see ). Cancellation -/// interrupts the running statement with sqlite3_interrupt. +/// interrupts the running statement with sqlite3_interrupt. Blocking SQLite calls always run on the thread pool. /// internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection connection) : IDbSession { @@ -21,6 +21,7 @@ internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection co public async Task ExecuteAsync(string sql, DbParam[] parameters, CancellationToken cancellationToken) { + await default(ThreadPoolHop); ObjectDisposedException.ThrowIf(_disposed, this); cancellationToken.ThrowIfCancellationRequested(); var statement = connection.Rent(sql); @@ -50,6 +51,7 @@ internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection co public async IAsyncEnumerable QueryAsync(string sql, DbParam[] parameters, [EnumeratorCancellation] CancellationToken cancellationToken) { + await default(ThreadPoolHop); ObjectDisposedException.ThrowIf(_disposed, this); cancellationToken.ThrowIfCancellationRequested(); var statement = connection.Rent(sql); @@ -82,6 +84,7 @@ internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection co public async Task ExecuteScriptAsync(string script, CancellationToken cancellationToken) { + await default(ThreadPoolHop); ObjectDisposedException.ThrowIf(_disposed, this); cancellationToken.ThrowIfCancellationRequested(); var locked = _transaction is null; @@ -221,6 +224,7 @@ internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection co private async Task InsertBufferedAsync(string table, IReadOnlyList columns, object?[] buffer, int rowCount, CancellationToken cancellationToken) { + await default(ThreadPoolHop); var statement = connection.Rent(InsertSql(table, columns, rowCount)); try { @@ -250,6 +254,7 @@ internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection co private async Task RunAsync(string sql, CancellationToken cancellationToken) { + await default(ThreadPoolHop); var statement = connection.Rent(sql); try { @@ -272,6 +277,7 @@ internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection co var busyRetries = 0; while (true) { + await default(ThreadPoolHop); // each row may be pulled from a UI thread var rc = statement.Step(); if (rc is SQLITE_ROW or SQLITE_DONE) return rc; var primary = rc & 0xFF; @@ -290,10 +296,27 @@ internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection co } } - private CancellationTokenRegistration RegisterInterrupt(CancellationToken cancellationToken) => - cancellationToken.CanBeCanceled - ? cancellationToken.UnsafeRegister(static state => ((SqliteConnection)state!).Interrupt(), connection) - : default; + private InterruptScope RegisterInterrupt(CancellationToken cancellationToken) => new(connection, cancellationToken); + + /// Interrupts the connection when the token is cancelled; the interrupt never outlives the scope. + private readonly struct InterruptScope : IDisposable + { + private readonly SqliteConnection _connection; + private readonly CancellationTokenRegistration _registration; + + public InterruptScope(SqliteConnection connection, CancellationToken cancellationToken) + { + _connection = connection; + connection.ClearInterrupt(); + _registration = cancellationToken.UnsafeRegister(static state => ((SqliteConnection)state!).Interrupt(), connection); + } + + public void Dispose() + { + _registration.Dispose(); // waits for a callback already running + _connection.ClearInterrupt(); + } + } } /// A BEGIN IMMEDIATE transaction holding the database write lock until it ends. diff --git a/src/Titano.Data/Sqlite/ThreadPoolHop.cs b/src/Titano.Data/Sqlite/ThreadPoolHop.cs new file mode 100644 index 00000000..23c47cb0 --- /dev/null +++ b/src/Titano.Data/Sqlite/ThreadPoolHop.cs @@ -0,0 +1,23 @@ +using System.Runtime.CompilerServices; + +namespace Titano.Data.Sqlite; + +/// +/// await default(ThreadPoolHop) continues on a thread-pool thread unless the caller already runs on one +/// without a synchronization context. SQLite calls block for as long as a statement runs, so they must never run on +/// a UI thread. +/// +internal readonly struct ThreadPoolHop : ICriticalNotifyCompletion +{ + public bool IsCompleted => SynchronizationContext.Current is null && Thread.CurrentThread.IsThreadPoolThread; + + public ThreadPoolHop GetAwaiter() => this; + + public void GetResult() + { + } + + public void OnCompleted(Action continuation) => ThreadPool.QueueUserWorkItem(static c => c(), continuation, preferLocal: false); + + public void UnsafeOnCompleted(Action continuation) => ThreadPool.UnsafeQueueUserWorkItem(static c => c(), continuation, preferLocal: false); +} diff --git a/tests/Titano.Data.Tests/Sqlite/SqliteBindingTests.cs b/tests/Titano.Data.Tests/Sqlite/SqliteBindingTests.cs index f0ddbc6b..f2d2b576 100644 --- a/tests/Titano.Data.Tests/Sqlite/SqliteBindingTests.cs +++ b/tests/Titano.Data.Tests/Sqlite/SqliteBindingTests.cs @@ -27,6 +27,26 @@ public sealed class SqliteBindingTests(TestContext context) : DatabaseTest(conte Assert.Equal(268435456L, await session.ScalarAsync("PRAGMA mmap_size", [], Ct)); } + [Test] + public async Task CallsFromAUiThreadReturnBeforeTheStatementRuns() + { + await using var session = await (await OpenDatabaseAsync()).OpenAsync(Ct); + using var cts = CancellationTokenSource.CreateLinkedTokenSource(Ct); + Task? query = null; + var ui = new Thread(() => + { + // A UI thread: has a synchronization context and is not a pool thread. + SynchronizationContext.SetSynchronizationContext(new SynchronizationContext()); + query = session.ExecuteAsync( + "WITH RECURSIVE r(n) AS (SELECT 1 UNION ALL SELECT n + 1 FROM r WHERE n < 2000000000) SELECT count(*) FROM r", [], cts.Token); + }); + ui.Start(); + Assert.True(ui.Join(TimeSpan.FromSeconds(5)), "the calling thread was blocked by the statement"); + Assert.False(query!.IsCompleted); + await cts.CancelAsync(); + await Assert.ThrowsAsync(() => query); + } + [Test] public async Task RejectsScriptsAndWrongParameterCounts() {