 |
KiCad PCB EDA Suite
|
|
KiCad PCB EDA Suite
|
An exclusive advisory lock on a file, held for the lifetime of this object. More...
#include <io.h>
Public Types | |
| enum class | STATE { NONE , HELD , BUSY , UNSUPPORTED } |
Public Member Functions | |
| FILE_LOCK ()=default | |
| ~FILE_LOCK () | |
| FILE_LOCK (FILE_LOCK &&aOther) noexcept | |
| FILE_LOCK & | operator= (FILE_LOCK &&aOther) noexcept |
| FILE_LOCK (const FILE_LOCK &)=delete | |
| FILE_LOCK & | operator= (const FILE_LOCK &)=delete |
| STATE | Acquire (const wxString &aPath, bool &aCreated) |
Open aPath, creating it if it does not exist, and try to take the lock without ever blocking on it. | |
| bool | OpenForInspect (const wxString &aPath, bool &aHeldByAnother) |
| Open an existing file and report whether another process holds its lock, creating nothing and keeping no lock of our own, so that a caller which only wants to know who holds a lock cannot disturb it. | |
| bool | IsOpen () const |
| bool | ReadAll (std::string &aContents) const |
| Read the whole file through the descriptor we hold. | |
| bool | Rewrite (const std::string &aContents) |
| Replace the file contents through the descriptor we hold, keeping the same inode. | |
| void | Release () |
| Release the lock and close the file. | |
Private Attributes | |
| int | m_fd = -1 |
| STATE | m_state = STATE::NONE |
An exclusive advisory lock on a file, held for the lifetime of this object.
The operating system releases the lock when the holding process dies, however it dies, so a lock that can be taken proves that whoever wrote the file is gone. That answer costs nothing to obtain and needs no cooperation from the other process, unlike a recorded process id, which is meaningless outside the pid namespace that recorded it.
POSIX uses flock(2), which is held by the open file description; Windows locks a byte far past the end of the file so that readers can still see the contents. The descriptor is opened close-on-exec: a child that inherited it would keep the lock alive past the death of its owner.
Windows releases the locks of a process that died in its own time rather than at once, so shortly after a crash a lock can still read as held. That errs towards leaving a lock alone, which is the safe direction to err in.
Content is read and written through the locked descriptor rather than by path, so that a file replaced underneath us cannot be mistaken for the one we hold.
|
strong |
|
default |
References FILE_LOCK().
Referenced by FILE_LOCK(), FILE_LOCK(), FILE_LOCK(), operator=(), and operator=().
| KIPLATFORM::IO::FILE_LOCK::~FILE_LOCK | ( | ) |
Definition at line 481 of file common/io.cpp.
References Release().
|
noexcept |
Definition at line 487 of file common/io.cpp.
References FILE_LOCK().
|
delete |
References FILE_LOCK().
| KIPLATFORM::IO::FILE_LOCK::STATE KIPLATFORM::IO::FILE_LOCK::Acquire | ( | const wxString & | aPath, |
| bool & | aCreated ) |
Open aPath, creating it if it does not exist, and try to take the lock without ever blocking on it.
The file stays open whatever the outcome, so the caller can read the contents of a lock another process holds.
| aPath | file to open and lock. |
| aCreated | set true if this call created the file, false if it existed. |
Definition at line 364 of file common/io.cpp.
References BUSY, HELD, m_fd, m_state, Release(), and UNSUPPORTED.
Referenced by BOOST_AUTO_TEST_CASE().
| bool KIPLATFORM::IO::FILE_LOCK::IsOpen | ( | ) | const |
| bool KIPLATFORM::IO::FILE_LOCK::OpenForInspect | ( | const wxString & | aPath, |
| bool & | aHeldByAnother ) |
Open an existing file and report whether another process holds its lock, creating nothing and keeping no lock of our own, so that a caller which only wants to know who holds a lock cannot disturb it.
| aPath | file to look at. |
| aHeldByAnother | set true only when another process provably holds the lock, so that an answer we cannot obtain never reads as in use. |
Definition at line 400 of file common/io.cpp.
References m_fd, and Release().
Referenced by LOCKFILE::Inspect().
References FILE_LOCK().
|
noexcept |
Definition at line 493 of file common/io.cpp.
References FILE_LOCK(), m_fd, m_state, NONE, and Release().
| bool KIPLATFORM::IO::FILE_LOCK::ReadAll | ( | std::string & | aContents | ) | const |
Read the whole file through the descriptor we hold.
Definition at line 427 of file common/io.cpp.
| void KIPLATFORM::IO::FILE_LOCK::Release | ( | ) |
Release the lock and close the file.
Definition at line 465 of file common/io.cpp.
References IsOpen(), m_fd, m_state, and NONE.
Referenced by Acquire(), OpenForInspect(), operator=(), and ~FILE_LOCK().
| bool KIPLATFORM::IO::FILE_LOCK::Rewrite | ( | const std::string & | aContents | ) |
Replace the file contents through the descriptor we hold, keeping the same inode.
Definition at line 444 of file common/io.cpp.
|
private |
Definition at line 156 of file io.h.
Referenced by Acquire(), IsOpen(), OpenForInspect(), operator=(), ReadAll(), Release(), and Rewrite().
|
private |
Definition at line 158 of file io.h.
Referenced by Acquire(), operator=(), and Release().
1.13.2