#include <AsyncSqlTransaction.hpp>

Public Member Functions
	AsyncSqlTransaction (SqlConnection &connection) noexcept

	AsyncSqlTransaction (AsyncSqlTransaction const &)=delete

AsyncSqlTransaction &	operator= (AsyncSqlTransaction const &)=delete

	AsyncSqlTransaction (AsyncSqlTransaction &&)=delete

AsyncSqlTransaction &	operator= (AsyncSqlTransaction &&)=delete

	~AsyncSqlTransaction ()
	Best-effort synchronous finalization if still open (see class note).

Task< void >	BeginAsync (SqlTransactionMode defaultMode=SqlTransactionMode::COMMIT, SqlIsolationMode isolationMode=SqlIsolationMode::DriverDefault, std::stop_token token={})

Task< void >	CommitAsync ()

Task< void >	RollbackAsync ()

Detailed Description

A distinct coroutine-based SQL transaction.

Unlike the high- and low-level async methods (which are added directly to the existing classes), a transaction is a scoped object, so it reads best as its own type. Each operation is offloaded to the connection's async backend (a worker thread, serialized per connection) and the awaiting coroutine resumes on the app's resume scheduler.

The underlying connection must have async enabled (SqlConnection::EnableAsync) before use and must stay async-enabled and alive for the whole lifetime of the transaction: do not destroy the connection (or return the owning pooled DataMapper, which disables async) between BeginAsync and the matching CommitAsync / RollbackAsync — the offloaded steps capture the connection by pointer and would otherwise fail (a clear std::logic_error from SqlConnection::AsyncBackend) or dangle.

Always co_await CommitAsync() or co_await RollbackAsync() explicitly. If the transaction is still open when destroyed, the destructor performs a best-effort finalization (per the configured mode) and emits a warning via SqlLogger. That finalization is itself routed through the connection's strand (and blocks the destroying thread until it completes) so it never touches the ODBC handle concurrently with another in-flight async operation on the same connection.

Warning: The destructor's strand-serialized finalization blocks the destroying thread until the strand has run it, so do not destroy an open transaction from any thread that the strand needs in order to make progress. That includes (a) destroying it from within a strand operation on its own connection, and (b) — in the multi-threaded model where the resume scheduler is the worker pool that backs the connection's strand — letting it be destroyed while the coroutine is resuming on one of those worker threads (with a single-worker pool this self-waits and deadlocks). The connection and its injected executors must also outlive the transaction; tearing the worker pool down first leaves the finalization undrained and the destructor blocked. Prefer explicit CommitAsync / RollbackAsync so the destructor never has to finalize.

auto tx = Async::AsyncSqlTransaction { dm.Connection() };
co_await tx.BeginAsync();
co_await dm.UpdateAsync(record);
co_await tx.CommitAsync();

Definition at line 55 of file AsyncSqlTransaction.hpp.

Constructor & Destructor Documentation

◆ AsyncSqlTransaction()

Lightweight::Async::AsyncSqlTransaction::AsyncSqlTransaction ( SqlConnection & connection )

explicitnoexcept

Constructs an (not-yet-begun) async transaction over connection.

Parameters

connection The async-enabled connection to run the transaction on.

Member Function Documentation

◆ BeginAsync()

Task< void > Lightweight::Async::AsyncSqlTransaction::BeginAsync	(	SqlTransactionMode	defaultMode = `SqlTransactionMode::COMMIT`,
		SqlIsolationMode	isolationMode = `SqlIsolationMode::DriverDefault`,
		std::stop_token	token = `{}`
	)

Asynchronously begins the transaction (disables auto-commit).

Parameters

defaultMode	How an un-finalized transaction is closed on destruction. Defaults to `COMMIT` to match the synchronous SqlTransaction, so porting sync code that relies on commit-on-scope-exit does not silently switch to rollback.
isolationMode	The transaction isolation level.
token	Optional cancellation token (a default-constructed `std::stop_token` is non-cancellable; cancellation is checked before the step is dispatched).

Returns: A Task that completes once the transaction has begun.

Exceptions

std::logic_error if a transaction is already open on this object (programmer error).

◆ CommitAsync()

Task< void > Lightweight::Async::AsyncSqlTransaction::CommitAsync ( )

Asynchronously commits the transaction.

Note: Finalization is a point of no return and is intentionally not cancellable: it always runs to completion. (Abandoning it would leave the transaction open, and the destructor would then finalize it with the configured default mode.)

◆ RollbackAsync()

Task< void > Lightweight::Async::AsyncSqlTransaction::RollbackAsync ( )

Asynchronously rolls back the transaction.

Note: Finalization is a point of no return and is intentionally not cancellable: it always runs to completion (so a rollback never silently degrades into a commit-on-destruction).

The documentation for this class was generated from the following file:

Lightweight/Async/AsyncSqlTransaction.hpp