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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 11:04:21 +00:00
1 parent f14994a2f7
commit 304ddf643d
6 files changed
+98 -7

No files matched your search

+1
View File
@@ -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. |
+25 -2
View File
@@ -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<string, LinkedListNode<SqliteStatement>> _cache = new(StringComparer.Ordinal);
private readonly LinkedList<SqliteStatement> _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);
/// <summary>Stops the running statement, or the next one if none has started yet, until <see cref="ClearInterrupt"/>.</summary>
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));
+1
View File
@@ -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<nint, int> 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);
+28 -5
View File
@@ -7,7 +7,7 @@ namespace Titano.Data.Sqlite;
/// <summary>
/// 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 <see cref="StepAsync"/>). Cancellation
/// interrupts the running statement with <c>sqlite3_interrupt</c>.
/// interrupts the running statement with <c>sqlite3_interrupt</c>. Blocking SQLite calls always run on the thread pool.
/// </summary>
internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection connection) : IDbSession
{
@@ -21,6 +21,7 @@ internal sealed class SqliteSession(SqliteDatabase database, SqliteConnection co
public async Task<int> 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<DbRow> 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<string> 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);
/// <summary>Interrupts the connection when the token is cancelled; the interrupt never outlives the scope.</summary>
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();
}
}
}
/// <summary>A <c>BEGIN IMMEDIATE</c> transaction holding the database write lock until it ends.</summary>
+23
View File
@@ -0,0 +1,23 @@
using System.Runtime.CompilerServices;
namespace Titano.Data.Sqlite;
/// <summary>
/// <c>await default(ThreadPoolHop)</c> 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.
/// </summary>
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);
}
@@ -27,6 +27,26 @@ public sealed class SqliteBindingTests(TestContext context) : DatabaseTest(conte
Assert.Equal(268435456L, await session.ScalarAsync<long>("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<OperationCanceledException>(() => query);
}
[Test]
public async Task RejectsScriptsAndWrongParameterCounts()
{