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