Hybrid locking mechanism for local history git repositories. More...

#include <history_lock.h>

Public Member Functions
	HISTORY_LOCK_MANAGER (const wxString &aProjectPath, int aStaleTimeoutSec=0)
	Construct a lock manager and attempt to acquire locks.

	~HISTORY_LOCK_MANAGER ()
	Destructor releases all locks and closes git repository.

	HISTORY_LOCK_MANAGER (const HISTORY_LOCK_MANAGER &)=delete

HISTORY_LOCK_MANAGER &	operator= (const HISTORY_LOCK_MANAGER &)=delete

bool	IsLocked () const
	Check if locks were successfully acquired.

git_repository *	GetRepository ()
	Get the git repository handle (only valid if IsLocked() returns true).

git_index *	GetIndex ()
	Get the git index handle (only valid if IsLocked() returns true).

wxString	GetLockError () const
	Get error message describing why lock could not be acquired.

wxString	GetLockHolder () const
	Get information about who currently holds the lock.

Static Public Member Functions
static bool	IsLockStale (const wxString &aProjectPath, int aStaleTimeoutSec=0)
	Check if a lock file exists and is stale (older than timeout).

static bool	BreakStaleLock (const wxString &aProjectPath)
	Forcibly remove a stale lock file.

Private Member Functions
bool	acquireFileLock ()

bool	openRepository ()

bool	acquireIndexLock ()

Private Attributes
wxString	m_projectPath

wxString	m_historyPath

std::unique_ptr< LOCKFILE >	m_fileLock

git_repository *	m_repo

git_index *	m_index

bool	m_repoOwned

bool	m_indexOwned

wxString	m_lockError

int	m_staleTimeoutSec

Detailed Description

Hybrid locking mechanism for local history git repositories.

Implements a two-layer locking strategy:

Layer 1: File-based lock (prevents cross-instance conflicts)
Layer 2: Git index lock (prevents concurrent git operations)

This provides defense-in-depth protection against:

Multiple KiCad instances accessing same project
Multi-threaded operations within same instance
Repository corruption from concurrent writes

Usage:

HISTORY_LOCK_MANAGER lock( projectPath );
if( !lock.IsLocked() )
{
    wxLogError( "Cannot acquire lock: %s", lock.GetLockError() );
    return false;
}
git_repository* repo = lock.GetRepository();
git_index* index = lock.GetIndex();
// ... perform git operations ...
// Lock automatically released when object goes out of scope

Definition at line 60 of file history_lock.h.

Constructor & Destructor Documentation

◆ HISTORY_LOCK_MANAGER() [1/2]

HISTORY_LOCK_MANAGER::HISTORY_LOCK_MANAGER	(	const wxString &	aProjectPath,
		int	aStaleTimeoutSec = 0 )

Construct a lock manager and attempt to acquire locks.

Parameters

aProjectPath	Path to the KiCad project directory
aStaleTimeoutSec	Timeout in seconds after which a lock is considered stale and can be forcibly removed. If <= 0, uses the value from ADVANCED_CFG::m_HistoryLockStaleTimeout (default: 0 = use config)

Definition at line 45 of file history_lock.cpp.

References acquireFileLock(), acquireIndexLock(), HISTORY_LOCK_TRACE, historyPath(), m_historyPath, m_index, m_indexOwned, m_lockError, m_projectPath, m_repo, m_repoOwned, m_staleTimeoutSec, and openRepository().

Referenced by HISTORY_LOCK_MANAGER(), and operator=().

◆ ~HISTORY_LOCK_MANAGER()

HISTORY_LOCK_MANAGER::~HISTORY_LOCK_MANAGER ( )

Destructor releases all locks and closes git repository.

Definition at line 84 of file history_lock.cpp.

References HISTORY_LOCK_TRACE, m_index, m_indexOwned, m_projectPath, m_repo, and m_repoOwned.

◆ HISTORY_LOCK_MANAGER() [2/2]

HISTORY_LOCK_MANAGER::HISTORY_LOCK_MANAGER ( const HISTORY_LOCK_MANAGER & )

delete

References HISTORY_LOCK_MANAGER().

Member Function Documentation

◆ acquireFileLock()

bool HISTORY_LOCK_MANAGER::acquireFileLock ( )

private

Definition at line 129 of file history_lock.cpp.

References _, BreakStaleLock(), IsLockStale(), m_fileLock, m_historyPath, m_lockError, m_projectPath, and m_staleTimeoutSec.

Referenced by HISTORY_LOCK_MANAGER().

◆ acquireIndexLock()

bool HISTORY_LOCK_MANAGER::acquireIndexLock ( )

private

Definition at line 194 of file history_lock.cpp.

References _, m_index, m_indexOwned, m_lockError, and m_repo.

Referenced by HISTORY_LOCK_MANAGER().

◆ BreakStaleLock()

bool HISTORY_LOCK_MANAGER::BreakStaleLock ( const wxString & aProjectPath )

static

Forcibly remove a stale lock file.

Should only be called after confirming with user or if IsLockStale() returns true.

Parameters

aProjectPath Path to project directory

Returns: true if lock was removed successfully

Definition at line 245 of file history_lock.cpp.

References HISTORY_LOCK_TRACE, historyPath(), FILEEXT::LockFileExtension, FILEEXT::LockFilePrefix, and result.

Referenced by acquireFileLock().

◆ GetIndex()

git_index * HISTORY_LOCK_MANAGER::GetIndex ( )

inline

Get the git index handle (only valid if IsLocked() returns true).

Returns: Pointer to git_index, or nullptr if not locked

Definition at line 101 of file history_lock.h.

References m_index.

Referenced by LOCAL_HISTORY::CommitSnapshot().

◆ GetLockError()

wxString HISTORY_LOCK_MANAGER::GetLockError ( ) const

Get error message describing why lock could not be acquired.

Returns: Human-readable error message with details about lock holder

Definition at line 111 of file history_lock.cpp.

References m_lockError.

Referenced by LOCAL_HISTORY::CommitSnapshot().

◆ GetLockHolder()

wxString HISTORY_LOCK_MANAGER::GetLockHolder ( ) const

Get information about who currently holds the lock.

Returns: String in format "username@hostname" or empty if lock is held by current process

Definition at line 117 of file history_lock.cpp.

References m_fileLock.

◆ GetRepository()

git_repository * HISTORY_LOCK_MANAGER::GetRepository ( )

inline

Get the git repository handle (only valid if IsLocked() returns true).

Returns: Pointer to git_repository, or nullptr if not locked

Definition at line 94 of file history_lock.h.

References m_repo.

Referenced by LOCAL_HISTORY::CommitDuplicateOfLastSave(), LOCAL_HISTORY::CommitSnapshot(), LOCAL_HISTORY::EnforceSizeLimit(), LOCAL_HISTORY::RestoreCommit(), and LOCAL_HISTORY::TagSave().

◆ IsLocked()

bool HISTORY_LOCK_MANAGER::IsLocked ( ) const

Check if locks were successfully acquired.

Returns: true if both file lock and git repository are accessible

Definition at line 105 of file history_lock.cpp.

References m_fileLock, m_index, and m_repo.

Referenced by LOCAL_HISTORY::CommitDuplicateOfLastSave(), LOCAL_HISTORY::CommitSnapshot(), LOCAL_HISTORY::EnforceSizeLimit(), LOCAL_HISTORY::RestoreCommit(), and LOCAL_HISTORY::TagSave().

◆ IsLockStale()

bool HISTORY_LOCK_MANAGER::IsLockStale	(	const wxString &	aProjectPath,
		int	aStaleTimeoutSec = 0 )

static

Check if a lock file exists and is stale (older than timeout).

This does not acquire the lock, just checks its status.

Parameters

aProjectPath	Path to project directory
aStaleTimeoutSec	Timeout in seconds. If <= 0, uses the value from ADVANCED_CFG::m_HistoryLockStaleTimeout (default: 0 = use config)