#include <SqlScopedLock.hpp>

Public Member Functions
LIGHTWEIGHT_API	SqlScopedLock (SqlConnection &connection, std::string_view lockName, std::chrono::milliseconds timeout=std::chrono::seconds(30))

LIGHTWEIGHT_API	~SqlScopedLock ()

	SqlScopedLock (SqlScopedLock const &)=delete

SqlScopedLock &	operator= (SqlScopedLock const &)=delete

LIGHTWEIGHT_API	SqlScopedLock (SqlScopedLock &&other) noexcept
	Move constructor.

LIGHTWEIGHT_API SqlScopedLock &	operator= (SqlScopedLock &&other) noexcept
	Move assignment operator.

bool	IsLocked () const noexcept
	Check if the lock is currently held by this instance.

std::string_view	Name () const noexcept
	Returns the lock name passed at construction.

LIGHTWEIGHT_API std::expected< void, SqlLockError >	Release ()

Static Public Member Functions
static LIGHTWEIGHT_API std::expected< SqlScopedLock, SqlLockError >	TryConstruct (SqlConnection &connection, std::string_view lockName, std::chrono::milliseconds timeout=std::chrono::seconds(30))

Detailed Description

RAII-style cross-process advisory lock.

Provides a distributed locking mechanism so that only one process at a time can hold a named token. The dialect-specific primitive is selected by the active SqlQueryFormatter's AdvisoryLockOps() handler:

SQL Server: sp_getapplock / sp_releaseapplock
PostgreSQL: pg_advisory_lock / pg_advisory_unlock
SQLite: _lightweight_locks table guarded by a unique constraint

SqlScopedLock itself contains zero per-DBMS branching — adding a new dialect only requires implementing a SqlAdvisoryLockHandler and wiring it to the new formatter's AdvisoryLockOps().

// Throws on failure (timeout, deadlock, or driver error):
auto lock = SqlScopedLock { connection, "my-resource" };
 
// Or, with structured error handling:
auto maybeLock = SqlScopedLock::TryConstruct(connection, "my-resource");
if (!maybeLock)
    std::println(stderr, "{}", maybeLock.error().message);

Definition at line 39 of file SqlScopedLock.hpp.

Constructor & Destructor Documentation

◆ SqlScopedLock()

LIGHTWEIGHT_API Lightweight::SqlScopedLock::SqlScopedLock	(	SqlConnection &	connection,
		std::string_view	lockName,
		std::chrono::milliseconds	timeout = `std::chrono::seconds(30)`
	)

explicit

Acquire a named advisory lock.

Parameters

connection	Database connection to use for locking.
lockName	Name of the lock (cooperative; any string).
timeout	Maximum time to wait for lock acquisition.

Exceptions

std::runtime_error if the lock cannot be acquired (timeout, deadlock, or driver error). The thrown exception's what() contains a human-readable explanation. For programmatic access to the failure reason, use the non-throwing TryConstruct factory.

◆ ~SqlScopedLock()

LIGHTWEIGHT_API Lightweight::SqlScopedLock::~SqlScopedLock ( )

Releases the lock on destruction. Release-time errors are routed to SqlLogger::OnWarning rather than being silently swallowed.

Member Function Documentation

◆ TryConstruct()

static LIGHTWEIGHT_API std::expected< SqlScopedLock, SqlLockError > Lightweight::SqlScopedLock::TryConstruct	(	SqlConnection &	connection,
		std::string_view	lockName,
		std::chrono::milliseconds	timeout = `std::chrono::seconds(30)`
	)

static

Non-throwing factory that returns either a held lock or a structured SqlLockError describing why the acquire failed. Prefer this when the caller wants to react programmatically to the failure reason (timeout vs deadlock vs driver error) — for example, to retry with backoff or to show a tailored UI message.

◆ IsLocked()

bool Lightweight::SqlScopedLock::IsLocked ( ) const

inlinenoexcept

Check if the lock is currently held by this instance.

Definition at line 77 of file SqlScopedLock.hpp.

◆ Name()

std::string_view Lightweight::SqlScopedLock::Name ( ) const

inlinenoexcept

Returns the lock name passed at construction.

Definition at line 83 of file SqlScopedLock.hpp.

◆ Release()

LIGHTWEIGHT_API std::expected< void, SqlLockError > Lightweight::SqlScopedLock::Release ( )

Release the lock early.

Automatically called in the destructor; can be invoked manually for finer scope control. Returns the underlying SqlLockError if the release round-trip fails so callers can log or surface it.

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

Lightweight/SqlScopedLock.hpp

Public Member Functions

Static Public Member Functions