ground/gcs/src/shared/qtlockedfile/qtlockedfile.cpp

   1 /**
   2  ******************************************************************************
   3  *
   4  * @file       qtlockedfile.cpp
   5  * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
   6  *             Parts by Nokia Corporation (qt-info@nokia.com) Copyright (C) 2009.
   7  * @brief
   8  * @see        The GNU Public License (GPL) Version 3
   9  * @defgroup
  10  * @{
  11  *
  12  *****************************************************************************/
  13 /*
  14  * This program is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 3 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * This program is distributed in the hope that it will be useful, but
  20  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  21  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  22  * for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License along
  25  * with this program; if not, write to the Free Software Foundation, Inc.,
  26  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  27  */
  28
  29 #include "qtlockedfile.h"
  30
  31 namespace SharedTools {
  32 /*!
  33     \class QtLockedFile
  34
  35     \brief The QtLockedFile class extends QFile with advisory locking functions.
  36
  37     A file may be locked in read or write mode. Multiple instances of
  38     \e QtLockedFile, created in multiple processes running on the same
  39     machine, may have a file locked in read mode. Exactly one instance
  40     may have it locked in write mode. A read and a write lock cannot
  41     exist simultaneously on the same file.
  42
  43     The file locks are advisory. This means that nothing prevents
  44     another process from manipulating a locked file using QFile or
  45     file system functions offered by the OS. Serialization is only
  46     guaranteed if all processes that access the file use
  47     QtLockedFile. Also, while holding a lock on a file, a process
  48     must not open the same file again (through any API), or locks
  49     can be unexpectedly lost.
  50
  51     The lock provided by an instance of \e QtLockedFile is released
  52     whenever the program terminates. This is true even when the
  53     program crashes and no destructors are called.
  54  */
  55
  56 /*! \enum QtLockedFile::LockMode
  57
  58     This enum describes the available lock modes.
  59
  60     \value ReadLock A read lock.
  61     \value WriteLock A write lock.
  62     \value NoLock Neither a read lock nor a write lock.
  63  */
  64
  65 /*!
  66     Constructs an unlocked \e QtLockedFile object. This constructor behaves in the same way
  67     as \e QFile::QFile().
  68
  69     \sa QFile::QFile()
  70  */
  71 QtLockedFile::QtLockedFile()
  72     : QFile()
  73 {
  74 #ifdef Q_OS_WIN
  75     m_semaphore_hnd = 0;
  76     m_mutex_hnd     = 0;
  77 #endif
  78     m_lock_mode     = NoLock;
  79 }
  80
  81 /*!
  82     Constructs an unlocked QtLockedFile object with file \a name. This constructor behaves in
  83     the same way as \e QFile::QFile(const QString&).
  84
  85     \sa QFile::QFile()
  86  */
  87 QtLockedFile::QtLockedFile(const QString &name)
  88     : QFile(name)
  89 {
  90 #ifdef Q_OS_WIN
  91     m_semaphore_hnd = 0;
  92     m_mutex_hnd     = 0;
  93 #endif
  94     m_lock_mode     = NoLock;
  95 }
  96
  97 /*!
  98     Returns \e true if this object has a in read or write lock;
  99     otherwise returns \e false.
 100
 101     \sa lockMode()
 102  */
 103 bool QtLockedFile::isLocked() const
 104 {
 105     return m_lock_mode != NoLock;
 106 }
 107
 108 /*!
 109     Returns the type of lock currently held by this object, or \e QtLockedFile::NoLock.
 110
 111     \sa isLocked()
 112  */
 113 QtLockedFile::LockMode QtLockedFile::lockMode() const
 114 {
 115     return m_lock_mode;
 116 }
 117
 118 /*!
 119     \fn bool QtLockedFile::lock(LockMode mode, bool block = true)
 120
 121     Obtains a lock of type \a mode.
 122
 123     If \a block is true, this
 124     function will block until the lock is aquired. If \a block is
 125     false, this function returns \e false immediately if the lock cannot
 126     be aquired.
 127
 128     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
 129     is first released and then a new lock is obtained.
 130
 131     This function returns \e true if, after it executes, the file is locked by this object,
 132     and \e false otherwise.
 133
 134     \sa unlock(), isLocked(), lockMode()
 135  */
 136
 137 /*!
 138     \fn bool QtLockedFile::unlock()
 139
 140     Releases a lock.
 141
 142     If the object has no lock, this function returns immediately.
 143
 144     This function returns \e true if, after it executes, the file is not locked by
 145     this object, and \e false otherwise.
 146
 147     \sa lock(), isLocked(), lockMode()
 148  */
 149
 150 /*!
 151     \fn QtLockedFile::~QtLockedFile()
 152
 153     Destroys the \e QtLockedFile object. If any locks were held, they are released.
 154  */
 155 } // namespace SharedTools