File indexing completed on 2024-05-19 04:38:45
0001 /**************************************************************************** 0002 ** 0003 ** Copyright (C) 2016 The Qt Company Ltd. 0004 ** Contact: https://www.qt.io/licensing/ 0005 ** 0006 ** This file is part of Qt Creator. 0007 ** 0008 ** Commercial License Usage 0009 ** Licensees holding valid commercial Qt licenses may use this file in 0010 ** accordance with the commercial license agreement provided with the 0011 ** Software or, alternatively, in accordance with the terms contained in 0012 ** a written agreement between you and The Qt Company. For licensing terms 0013 ** and conditions see https://www.qt.io/terms-conditions. For further 0014 ** information use the contact form at https://www.qt.io/contact-us. 0015 ** 0016 ** GNU General Public License Usage 0017 ** Alternatively, this file may be used under the terms of the GNU 0018 ** General Public License version 3 as published by the Free Software 0019 ** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT 0020 ** included in the packaging of this file. Please review the following 0021 ** information to ensure the GNU General Public License requirements will 0022 ** be met: https://www.gnu.org/licenses/gpl-3.0.html. 0023 ** 0024 ****************************************************************************/ 0025 0026 #include "qtlockedfile.h" 0027 0028 namespace SharedTools { 0029 0030 /*! 0031 \class QtLockedFile 0032 0033 \brief The QtLockedFile class extends QFile with advisory locking functions. 0034 0035 A file may be locked in read or write mode. Multiple instances of 0036 \e QtLockedFile, created in multiple processes running on the same 0037 machine, may have a file locked in read mode. Exactly one instance 0038 may have it locked in write mode. A read and a write lock cannot 0039 exist simultaneously on the same file. 0040 0041 The file locks are advisory. This means that nothing prevents 0042 another process from manipulating a locked file using QFile or 0043 file system functions offered by the OS. Serialization is only 0044 guaranteed if all processes that access the file use 0045 QtLockedFile. Also, while holding a lock on a file, a process 0046 must not open the same file again (through any API), or locks 0047 can be unexpectedly lost. 0048 0049 The lock provided by an instance of \e QtLockedFile is released 0050 whenever the program terminates. This is true even when the 0051 program crashes and no destructors are called. 0052 */ 0053 0054 /*! \enum QtLockedFile::LockMode 0055 0056 This enum describes the available lock modes. 0057 0058 \value ReadLock A read lock. 0059 \value WriteLock A write lock. 0060 \value NoLock Neither a read lock nor a write lock. 0061 */ 0062 0063 /*! 0064 Constructs an unlocked \e QtLockedFile object. This constructor behaves in the same way 0065 as \e QFile::QFile(). 0066 0067 \sa QFile::QFile() 0068 */ 0069 QtLockedFile::QtLockedFile() 0070 : QFile() 0071 , m_lock_mode(NoLock) 0072 { 0073 #ifdef Q_OS_WIN 0074 m_semaphore_hnd = 0; 0075 m_mutex_hnd = 0; 0076 #endif 0077 } 0078 0079 /*! 0080 Constructs an unlocked QtLockedFile object with file \a name. This constructor behaves in 0081 the same way as \e QFile::QFile(const QString&). 0082 0083 \sa QFile::QFile() 0084 */ 0085 QtLockedFile::QtLockedFile(const QString &name) 0086 : QFile(name) 0087 , m_lock_mode(NoLock) 0088 { 0089 #ifdef Q_OS_WIN 0090 m_semaphore_hnd = 0; 0091 m_mutex_hnd = 0; 0092 #endif 0093 } 0094 0095 /*! 0096 Returns \e true if this object has a in read or write lock; 0097 otherwise returns \e false. 0098 0099 \sa lockMode() 0100 */ 0101 bool QtLockedFile::isLocked() const 0102 { 0103 return m_lock_mode != NoLock; 0104 } 0105 0106 /*! 0107 Returns the type of lock currently held by this object, or \e QtLockedFile::NoLock. 0108 0109 \sa isLocked() 0110 */ 0111 QtLockedFile::LockMode QtLockedFile::lockMode() const 0112 { 0113 return m_lock_mode; 0114 } 0115 0116 /*! 0117 \fn bool QtLockedFile::lock(LockMode mode, bool block = true) 0118 0119 Obtains a lock of type \a mode. 0120 0121 If \a block is true, this 0122 function will block until the lock is acquired. If \a block is 0123 false, this function returns \e false immediately if the lock cannot 0124 be acquired. 0125 0126 If this object already has a lock of type \a mode, this function returns \e true immediately. If this object has a lock of a different type than \a mode, the lock 0127 is first released and then a new lock is obtained. 0128 0129 This function returns \e true if, after it executes, the file is locked by this object, 0130 and \e false otherwise. 0131 0132 \sa unlock(), isLocked(), lockMode() 0133 */ 0134 0135 /*! 0136 \fn bool QtLockedFile::unlock() 0137 0138 Releases a lock. 0139 0140 If the object has no lock, this function returns immediately. 0141 0142 This function returns \e true if, after it executes, the file is not locked by 0143 this object, and \e false otherwise. 0144 0145 \sa lock(), isLocked(), lockMode() 0146 */ 0147 0148 /*! 0149 \fn QtLockedFile::~QtLockedFile() 0150 0151 Destroys the \e QtLockedFile object. If any locks were held, they are released. 0152 */ 0153 0154 } // namespace SharedTools