Lightweight::SqlAdvisoryLockHandler Class Reference

#include <SqlAdvisoryLock.hpp>

Public Member Functions
virtual	~SqlAdvisoryLockHandler ()=default
	Polymorphic destructor.
	SqlAdvisoryLockHandler (SqlAdvisoryLockHandler const &)=delete
SqlAdvisoryLockHandler &	operator= (SqlAdvisoryLockHandler const &)=delete
	SqlAdvisoryLockHandler (SqlAdvisoryLockHandler &&)=delete
SqlAdvisoryLockHandler &	operator= (SqlAdvisoryLockHandler &&)=delete
virtual std::expected< void, SqlLockError >	TryAcquire (SqlConnection &connection, std::string_view lockName, std::chrono::milliseconds timeout) const =0
virtual std::expected< void, SqlLockError >	Release (SqlConnection &connection, std::string_view lockName) const =0
virtual std::vector< std::string_view >	BookkeepingTableNames () const noexcept

Detailed Description

Dialect-specific implementation of advisory-lock acquire/release.

Each SqlQueryFormatter returns a process-singleton instance of the appropriate concrete handler via SqlQueryFormatter::AdvisoryLockOps(). Concrete implementations live next to the formatter that owns them (e.g. the SQL Server handler is defined alongside SqlServerQueryFormatter), keeping every dialect quirk in one source file and out of the SqlScopedLock business logic.

Callers that need a lock should use the SqlScopedLock RAII wrapper — this type is the extension point for adding new dialects.

Naming: these are advisory locks (also called application or named locks): they don't lock any particular row or table; they're purely cooperative tokens identified by a string name. Two processes that agree to acquire the same name serialise on it.

Definition at line 79 of file SqlAdvisoryLock.hpp.

Member Function Documentation

TryAcquire()

virtual std::expected< void, SqlLockError > Lightweight::SqlAdvisoryLockHandler::TryAcquire ( SqlConnection &  connection, std::string_view  lockName, std::chrono::milliseconds  timeout  ) const

pure virtual

Attempts to acquire the named lock on connection, blocking up to timeout ms.

Returns an empty expected on success; otherwise a fully-populated SqlLockError so the caller can distinguish timeout from deadlock from driver error and propagate accordingly.

Implementations MUST NOT throw on a recoverable timeout — that's a SqlLockFailureReason::Timeout. They MAY throw only on truly catastrophic conditions (out-of-memory, ABI mismatch); routine driver failures should populate SqlLockFailureReason::DriverError with info set.

Parameters

connection	The SQL connection to acquire the lock on.
lockName	The name of the lock (advisory; backends hash or quote as needed).
timeout	Maximum time to wait for lock acquisition.

Returns

Empty expected on success, populated SqlLockError on failure.

Release()

virtual std::expected< void, SqlLockError > Lightweight::SqlAdvisoryLockHandler::Release ( SqlConnection &  connection, std::string_view  lockName  ) const

pure virtual

Releases the named lock previously acquired with TryAcquire.

Implementations MUST tolerate "release of a lock that's already gone" (connection teardown, server-side session expiry, etc.) as success — Release is idempotent by contract.

Returns an error only if the release round-trip itself failed. The caller (typically SqlScopedLock's destructor) should log such an error rather than swallow it silently.

Parameters

connection	The SQL connection that holds the lock.
lockName	The name of the lock to release.

Returns

Empty expected on success, populated SqlLockError on failure.

BookkeepingTableNames()

virtual std::vector< std::string_view > Lightweight::SqlAdvisoryLockHandler::BookkeepingTableNames ( ) const

inlinevirtualnoexcept

Names of any backend-internal bookkeeping tables this handler maintains — empty for backends with server-native advisory locks (SQL Server's sp_getapplock, PostgreSQL's pg_advisory_lock), non-empty for backends that implement locking via a regular table (SQLite returns its lock-table name here).

Tooling that walks the live schema (dbtool hard-reset, schema diffs, backups that try to skip internal tables) consults this so the lock table is recognised as infrastructure rather than mistaken for user data.

Definition at line 137 of file SqlAdvisoryLock.hpp.

---

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

• Lightweight/SqlAdvisoryLock.hpp