Advisory lock over a file, taken by writing a sibling lock file and holding an exclusive lock on it for as long as this object lives. More...

#include <lockfile.h>

Public Member Functions
	LOCKFILE (const wxString &filename, bool aRemoveOnRelease=true)

	LOCKFILE (LOCKFILE &&other) noexcept

	~LOCKFILE ()

void	UnlockFile ()
	Unlock and remove the file from the filesystem as long as we still own it.

bool	OverrideLock (bool aRemoveOnRelease=true)
	Force the lock, overwriting the data that existed already.

bool	IsLockedByMe ()

wxString	GetUsername ()

wxString	GetHostname ()

bool	Locked () const

bool	Valid () const

Static Public Member Functions
static LOCKFILE	Inspect (const wxString &aFilename)
	Look at a lock without taking it: nothing is created, nothing is claimed and nothing is removed on release, so a caller that only wants to know who holds a lock cannot disturb it.

static wxString	LockPathFor (const wxString &aFilename)

Private Member Functions
	LOCKFILE ()=default

void	claim ()

bool	readRecord (nlohmann::json &aRecord) const

void	readOwner ()

bool	stillOwnLock ()

Static Private Member Functions
static wxString	newToken ()

Private Attributes
wxString	m_lockFilename

wxString	m_username

wxString	m_hostname

wxString	m_token

KIPLATFORM::IO::FILE_LOCK	m_lock

bool	m_owned = false

bool	m_status = false

bool	m_removeOnRelease = false

Detailed Description

Advisory lock over a file, taken by writing a sibling lock file and holding an exclusive lock on it for as long as this object lives.

The operating system drops that lock when the owning process dies, so a lock file we can lock is one whose writer is gone and whose contents we may take over. That keeps a session killed by a crash from pinning its project read-only forever, without ever guessing at the liveness of a process we cannot see.

Definition at line 59 of file lockfile.h.

Constructor & Destructor Documentation

◆ LOCKFILE() [1/3]

LOCKFILE::LOCKFILE	(	const wxString &	filename,
		bool	aRemoveOnRelease = true )

inline

Definition at line 62 of file lockfile.h.

References KIPLATFORM::IO::FILE_LOCK::BUSY, claim(), KIPLATFORM::IO::FILE_LOCK::HELD, IsLockedByMe(), KIPLATFORM::ENV::IsRemovablePath(), LockPathFor(), m_lock, m_lockFilename, m_removeOnRelease, m_status, readOwner(), and traceLockFile.

Referenced by Inspect(), and LOCKFILE().

◆ LOCKFILE() [2/3]

LOCKFILE::LOCKFILE ( LOCKFILE && other )

inlinenoexcept

Definition at line 149 of file lockfile.h.

References LOCKFILE().

◆ ~LOCKFILE()

LOCKFILE::~LOCKFILE ( )

inline

Definition at line 163 of file lockfile.h.

References UnlockFile().

◆ LOCKFILE() [3/3]

LOCKFILE::LOCKFILE ( )

privatedefault

Member Function Documentation

◆ claim()

void LOCKFILE::claim ( )

inlineprivate

Definition at line 267 of file lockfile.h.

References m_hostname, m_lock, m_lockFilename, m_owned, m_status, m_token, m_username, newToken(), and traceLockFile.

Referenced by LOCKFILE(), and OverrideLock().

◆ GetHostname()

wxString LOCKFILE::GetHostname ( )

inline

Returns: Current hostname. If we own the lock this is our computer. Otherwise, this is the computer that does.

Definition at line 226 of file lockfile.h.

References m_hostname.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), KICAD_MANAGER_FRAME::LoadProject(), and KICAD_MANAGER_FRAME::ProjectChanged().

◆ GetUsername()

wxString LOCKFILE::GetUsername ( )

inline

Returns: Current username. If we own the lock, this is us. Otherwise, this is the user that does own it.

Definition at line 220 of file lockfile.h.

References m_username.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), KICAD_MANAGER_FRAME::LoadProject(), and KICAD_MANAGER_FRAME::ProjectChanged().

◆ Inspect()

static LOCKFILE LOCKFILE::Inspect ( const wxString & aFilename )

inlinestatic

Look at a lock without taking it: nothing is created, nothing is claimed and nothing is removed on release, so a caller that only wants to know who holds a lock cannot disturb it.

Valid() then answers whether the lock is free rather than whether we hold it, and Locked() is always false.

Definition at line 119 of file lockfile.h.

References LOCKFILE(), LockPathFor(), m_lock, m_lockFilename, m_status, KIPLATFORM::IO::FILE_LOCK::OpenForInspect(), and readOwner().

Referenced by HISTORY_LOCK_MANAGER::acquireFileLock(), HISTORY_LOCK_MANAGER::IsLockStale(), KICAD_MANAGER_FRAME::LoadProject(), and SETTINGS_MANAGER::LoadProject().

◆ IsLockedByMe()

bool LOCKFILE::IsLockedByMe ( )

inline

Definition at line 206 of file lockfile.h.

References m_hostname, and m_username.

Referenced by BOOST_AUTO_TEST_CASE(), and LOCKFILE().

◆ Locked()

bool LOCKFILE::Locked ( ) const

inline

Definition at line 228 of file lockfile.h.

References m_owned.

Referenced by BOOST_AUTO_TEST_CASE(), and HISTORY_LOCK_MANAGER::BreakStaleLock().

◆ LockPathFor()

static wxString LOCKFILE::LockPathFor ( const wxString & aFilename )

inlinestatic

Returns: the path of the lock file that guards aFilename.

Definition at line 140 of file lockfile.h.

References FILEEXT::LockFileExtension, and FILEEXT::LockFilePrefix.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), Inspect(), HISTORY_LOCK_MANAGER::IsLockStale(), LOCKFILE(), and seedLockedProject().

◆ newToken()

static wxString LOCKFILE::newToken ( )

inlinestaticprivate

Returns: a value no other lock will carry. Process ids cannot serve here: sandboxed KiCads each number their processes from one, so two of them collide routinely.

Definition at line 255 of file lockfile.h.

Referenced by claim().

◆ OverrideLock()

bool LOCKFILE::OverrideLock ( bool aRemoveOnRelease = true )

inline

Force the lock, overwriting the data that existed already.

Returns: True if we successfully overrode the lock

Definition at line 194 of file lockfile.h.

References claim(), m_lock, m_lockFilename, m_owned, m_removeOnRelease, m_status, and traceLockFile.

Referenced by KICAD_MANAGER_FRAME::LoadProject(), and KICAD_MANAGER_FRAME::ProjectChanged().

◆ readOwner()

void LOCKFILE::readOwner ( )

inlineprivate

Definition at line 312 of file lockfile.h.

References m_hostname, m_token, m_username, and readRecord().

Referenced by Inspect(), and LOCKFILE().

◆ readRecord()

bool LOCKFILE::readRecord ( nlohmann::json & aRecord ) const

inlineprivate

Returns: true if the lock file holds a record we could parse. Cloud-synced drives can present a lock file before its contents finish syncing, so an empty or corrupt one counts as an unknown owner rather than a hard error.

Definition at line 294 of file lockfile.h.

References m_lock, m_lockFilename, and traceLockFile.

Referenced by readOwner(), and stillOwnLock().

◆ stillOwnLock()

bool LOCKFILE::stillOwnLock ( )

inlineprivate

Returns: true if the lock file still carries the record we wrote, so that a lock another process has since taken over is left alone.

Definition at line 334 of file lockfile.h.

References m_lockFilename, m_token, readRecord(), and traceLockFile.

Referenced by UnlockFile().

◆ UnlockFile()

void LOCKFILE::UnlockFile ( )

inline

Unlock and remove the file from the filesystem as long as we still own it.

Definition at line 171 of file lockfile.h.

References m_lock, m_lockFilename, m_owned, m_removeOnRelease, m_status, stillOwnLock(), and traceLockFile.

Referenced by ~LOCKFILE().

◆ Valid()

bool LOCKFILE::Valid ( ) const

inline

Definition at line 233 of file lockfile.h.

References m_status.

Referenced by HISTORY_LOCK_MANAGER::acquireFileLock(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), HISTORY_LOCK_MANAGER::IsLockStale(), KICAD_MANAGER_FRAME::LoadProject(), SETTINGS_MANAGER::LoadProject(), and KICAD_MANAGER_FRAME::ProjectChanged().

Member Data Documentation

◆ m_hostname

wxString LOCKFILE::m_hostname

private

Definition at line 244 of file lockfile.h.

Referenced by claim(), GetHostname(), IsLockedByMe(), and readOwner().

◆ m_lock

KIPLATFORM::IO::FILE_LOCK LOCKFILE::m_lock

private

Definition at line 246 of file lockfile.h.

Referenced by claim(), Inspect(), LOCKFILE(), OverrideLock(), readRecord(), and UnlockFile().

◆ m_lockFilename

wxString LOCKFILE::m_lockFilename

private

Definition at line 242 of file lockfile.h.

Referenced by claim(), Inspect(), LOCKFILE(), OverrideLock(), readRecord(), stillOwnLock(), and UnlockFile().

◆ m_owned

bool LOCKFILE::m_owned = false

private

Definition at line 247 of file lockfile.h.

Referenced by claim(), Locked(), OverrideLock(), and UnlockFile().

◆ m_removeOnRelease

bool LOCKFILE::m_removeOnRelease = false

private

Definition at line 249 of file lockfile.h.

Referenced by LOCKFILE(), OverrideLock(), and UnlockFile().

◆ m_status

bool LOCKFILE::m_status = false

private

Definition at line 248 of file lockfile.h.

Referenced by claim(), Inspect(), LOCKFILE(), OverrideLock(), UnlockFile(), and Valid().

◆ m_token

wxString LOCKFILE::m_token

private

Definition at line 245 of file lockfile.h.

Referenced by claim(), readOwner(), and stillOwnLock().

◆ m_username

wxString LOCKFILE::m_username

private

Definition at line 243 of file lockfile.h.

Referenced by claim(), GetUsername(), IsLockedByMe(), and readOwner().

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

lockfile.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ LOCKFILE() [1/3]

◆ LOCKFILE() [2/3]

◆ ~LOCKFILE()

◆ LOCKFILE() [3/3]

Member Function Documentation

◆ claim()

◆ GetHostname()

◆ GetUsername()

◆ Inspect()

◆ IsLockedByMe()

◆ Locked()

◆ LockPathFor()

◆ newToken()

◆ OverrideLock()

◆ readOwner()

◆ readRecord()

◆ stillOwnLock()

◆ UnlockFile()

◆ Valid()

Member Data Documentation

◆ m_hostname

◆ m_lock

◆ m_lockFilename

◆ m_owned

◆ m_removeOnRelease

◆ m_status

◆ m_token

◆ m_username