src/app/qtlocalpeer/qtlockedfile.cpp

   1 /*
   2  * Bittorrent Client using Qt and libtorrent.
   3  * Copyright (C) 2019  Mike Tzou (Chocobo1)
   4  *
   5  * This program is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU General Public License
   7  * as published by the Free Software Foundation; either version 2
   8  * of the License, or (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18  *
  19  * In addition, as a special exception, the copyright holders give permission to
  20  * link this program with the OpenSSL project's "OpenSSL" library (or with
  21  * modified versions of it that use the same license as the "OpenSSL" library),
  22  * and distribute the linked executables. You must obey the GNU General Public
  23  * License in all respects for all of the code used other than "OpenSSL".  If you
  24  * modify file(s), you may extend this exception to your version of the file(s),
  25  * but you are not obligated to do so. If you do not wish to do so, delete this
  26  * exception statement from your version.
  27  *
  28 ****************************************************************************
  29 **
  30 ** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
  31 ** Contact: http://www.qt-project.org/legal
  32 **
  33 ** This file is part of the Qt Solutions component.
  34 **
  35 ** $QT_BEGIN_LICENSE:BSD$
  36 ** You may use this file under the terms of the BSD license as follows:
  37 **
  38 ** "Redistribution and use in source and binary forms, with or without
  39 ** modification, are permitted provided that the following conditions are
  40 ** met:
  41 **   * Redistributions of source code must retain the above copyright
  42 **     notice, this list of conditions and the following disclaimer.
  43 **   * Redistributions in binary form must reproduce the above copyright
  44 **     notice, this list of conditions and the following disclaimer in
  45 **     the documentation and/or other materials provided with the
  46 **     distribution.
  47 **   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
  48 **     of its contributors may be used to endorse or promote products derived
  49 **     from this software without specific prior written permission.
  50 **
  51 **
  52 ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  53 ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  54 ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  55 ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  56 ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  57 ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  58 ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  59 ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  60 ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  61 ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  62 ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
  63 **
  64 ** $QT_END_LICENSE$
  65 **
  66 ****************************************************************************
  67 */
  68
  69 #include "qtlockedfile.h"
  70
  71 /*!
  72     \class QtLockedFile
  73
  74     \brief The QtLockedFile class extends QFile with advisory locking
  75     functions.
  76
  77     A file may be locked in read or write mode. Multiple instances of
  78     \e QtLockedFile, created in multiple processes running on the same
  79     machine, may have a file locked in read mode. Exactly one instance
  80     may have it locked in write mode. A read and a write lock cannot
  81     exist simultaneously on the same file.
  82
  83     The file locks are advisory. This means that nothing prevents
  84     another process from manipulating a locked file using QFile or
  85     file system functions offered by the OS. Serialization is only
  86     guaranteed if all processes that access the file use
  87     QLockedFile. Also, while holding a lock on a file, a process
  88     must not open the same file again (through any API), or locks
  89     can be unexpectedly lost.
  90
  91     The lock provided by an instance of \e QtLockedFile is released
  92     whenever the program terminates. This is true even when the
  93     program crashes and no destructors are called.
  94 */
  95
  96 /*! \enum QtLockedFile::LockMode
  97
  98     This enum describes the available lock modes.
  99
 100     \value ReadLock A read lock.
 101     \value WriteLock A write lock.
 102     \value NoLock Neither a read lock nor a write lock.
 103 */
 104
 105 /*!
 106     Constructs an unlocked \e QtLockedFile object. This constructor
 107     behaves in the same way as \e QFile::QFile().
 108
 109     \sa QFile::QFile()
 110 */
 111 QtLockedFile::QtLockedFile() = default;
 112
 113 /*!
 114     Constructs an unlocked QtLockedFile object with file \a name. This
 115     constructor behaves in the same way as \e QFile::QFile(const
 116     QString&).
 117
 118     \sa QFile::QFile()
 119 */
 120 QtLockedFile::QtLockedFile(const QString &name)
 121     : QFile(name)
 122 {
 123 }
 124
 125 /*!
 126   Opens the file in OpenMode \a mode.
 127
 128   This is identical to QFile::open(), with the one exception that the
 129   Truncate mode flag is disallowed. Truncation would conflict with the
 130   advisory file locking, since the file would be modified before the
 131   write lock is obtained. If truncation is required, use resize(0)
 132   after obtaining the write lock.
 133
 134   Returns true if successful; otherwise false.
 135
 136   \sa QFile::open(), QFile::resize()
 137 */
 138 bool QtLockedFile::open(const OpenMode mode)
 139 {
 140     if (mode & QIODevice::Truncate)
 141     {
 142         qWarning("QtLockedFile::open(): Truncate mode not allowed.");
 143         return false;
 144     }
 145     return QFile::open(mode);
 146 }
 147
 148 /*!
 149     Returns \e true if this object has a in read or write lock;
 150     otherwise returns \e false.
 151
 152     \sa lockMode()
 153 */
 154 bool QtLockedFile::isLocked() const
 155 {
 156     return m_lockMode != NoLock;
 157 }
 158
 159 /*!
 160     Returns the type of lock currently held by this object, or \e
 161     QtLockedFile::NoLock.
 162
 163     \sa isLocked()
 164 */
 165 QtLockedFile::LockMode QtLockedFile::lockMode() const
 166 {
 167     return m_lockMode;
 168 }
 169
 170 /*!
 171     \fn bool QtLockedFile::lock(LockMode mode, bool block = true)
 172
 173     Obtains a lock of type \a mode. The file must be opened before it
 174     can be locked.
 175
 176     If \a block is true, this function will block until the lock is
 177     acquired. If \a block is false, this function returns \e false
 178     immediately if the lock cannot be acquired.
 179
 180     If this object already has a lock of type \a mode, this function
 181     returns \e true immediately. If this object has a lock of a
 182     different type than \a mode, the lock is first released and then a
 183     new lock is obtained.
 184
 185     This function returns \e true if, after it executes, the file is
 186     locked by this object, and \e false otherwise.
 187
 188     \sa unlock(), isLocked(), lockMode()
 189 */
 190
 191 /*!
 192     \fn bool QtLockedFile::unlock()
 193
 194     Releases a lock.
 195
 196     If the object has no lock, this function returns immediately.
 197
 198     This function returns \e true if, after it executes, the file is
 199     not locked by this object, and \e false otherwise.
 200
 201     \sa lock(), isLocked(), lockMode()
 202 */
 203
 204 /*!
 205     \fn QtLockedFile::~QtLockedFile()
 206
 207     Destroys the \e QtLockedFile object. If any locks were held, they
 208     are released.
 209 */