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 53 of file lockfile.h.

Constructor & Destructor Documentation

◆ LOCKFILE() [1/3]

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

inline

Definition at line 56 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 143 of file lockfile.h.

References LOCKFILE().

◆ ~LOCKFILE()

LOCKFILE::~LOCKFILE ( )

inline

Definition at line 157 of file lockfile.h.

References UnlockFile().

◆ LOCKFILE() [3/3]

LOCKFILE::LOCKFILE ( )

privatedefault

Member Function Documentation

◆ claim()

void LOCKFILE::claim ( )

inlineprivate

Definition at line 255 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 220 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 214 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 113 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 200 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 222 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 134 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 243 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 188 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 300 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 282 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 327 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 165 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 224 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 232 of file lockfile.h.

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

◆ m_lock

KIPLATFORM::IO::FILE_LOCK LOCKFILE::m_lock

private

Definition at line 234 of file lockfile.h.

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

◆ m_lockFilename

wxString LOCKFILE::m_lockFilename

private

Definition at line 230 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 235 of file lockfile.h.

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

◆ m_removeOnRelease

bool LOCKFILE::m_removeOnRelease = false

private

Definition at line 237 of file lockfile.h.

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

◆ m_status

bool LOCKFILE::m_status = false

private

Definition at line 236 of file lockfile.h.

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

◆ m_token

wxString LOCKFILE::m_token

private

Definition at line 233 of file lockfile.h.

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

◆ m_username

wxString LOCKFILE::m_username

private

Definition at line 231 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