<class name="QReadWriteLock" doc="/** <p>The <a href="QReadWriteLock.html#QReadWriteLock()"><tt>QReadWriteLock</tt></a> class provides read-write locking.</p> <p>A read-write lock is a synchronization tool for protecting resources that can be accessed for reading and writing. This type of lock is useful if you want to allow multiple threads to have simultaneous read-only access, but as soon as one thread wants to write to the resource, all other threads must be blocked until the writing is complete.</p> <p>In many cases, <a href="QReadWriteLock.html#QReadWriteLock()"><tt>QReadWriteLock</tt></a> is a direct competitor to <a href="%2E%2E/core/QMutex.html"><tt>QMutex</tt></a>. <a href="QReadWriteLock.html#QReadWriteLock()"><tt>QReadWriteLock</tt></a> is a good choice if there are many concurrent reads and writing occurs infrequently.</p> <p>Example:</p> <pre> QReadWriteLock lock; void ReaderThread::run() { ... lock.lockForRead(); read_file(); lock.unlock(); ... } void WriterThread::run() { ... lock.lockForWrite(); write_file(); lock.unlock(); ... }</pre> <p>To ensure that writers aren't blocked forever by readers, readers attempting to obtain a lock will not succeed if there is a blocked writer waiting for access, even if the lock is currently only accessed by other readers. Also, if the lock is accessed by a writer and another writer comes in, that writer will have priority over any readers that might also be waiting.</p> <p>Like <a href="%2E%2E/core/QMutex.html"><tt>QMutex</tt></a>, a <a href="QReadWriteLock.html#QReadWriteLock()"><tt>QReadWriteLock</tt></a> can be recursively locked by the same thread. In such cases, <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> must be called the same number of times <a href="QReadWriteLock.html#lockForWrite()"><tt>lockForWrite</tt></a> or <a href="QReadWriteLock.html#lockForRead()"><tt>lockForRead</tt></a> was called. Note that the lock type cannot be changed when trying to lock recursively, i.e&#x2e; it is not possible to lock for reading in a thread that already has locked for writing (and vice versa).</p> @see <tt>QReadLocker</tt> @see <tt>QWriteLocker</tt> @see <a href="%2E%2E/core/QMutex.html"><tt>QMutex</tt></a> @see <a href="%2E%2E/core/QSemaphore.html"><tt>QSemaphore</tt></a> */"> <method name="public QReadWriteLock()" doc="/** <p>Constructs a <a href="QReadWriteLock.html#QReadWriteLock()"><tt>QReadWriteLock</tt></a> object.</p> @see <a href="QReadWriteLock.html#lockForRead()"><tt>lockForRead</tt></a> @see <a href="QReadWriteLock.html#lockForWrite()"><tt>lockForWrite</tt></a> */"/> <method name="public final void lockForRead()" doc="/** <p>Locks the lock for reading. This function will block the current thread if any thread (including the current) has locked for writing.</p> @see <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> @see <a href="QReadWriteLock.html#lockForWrite()"><tt>lockForWrite</tt></a> @see <a href="QReadWriteLock.html#tryLockForRead(int)"><tt>tryLockForRead</tt></a> */"/> <method name="public final void lockForWrite()" doc="/** <p>Locks the lock for writing. This function will block the current thread if another thread has locked for reading or writing.</p> @see <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> @see <a href="QReadWriteLock.html#lockForRead()"><tt>lockForRead</tt></a> @see <a href="QReadWriteLock.html#tryLockForWrite()"><tt>tryLockForWrite</tt></a> */"/> <method name="public final boolean tryLockForRead()" doc="/** <p>Attempts to lock for reading. If the lock was obtained, this function returns true, otherwise it returns false instead of waiting for the lock to become available, i.e&#x2e; it does not block.</p> <p>The lock attempt will fail if another thread has locked for writing.</p> <p>If the lock was obtained, the lock must be unlocked with <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> before another thread can successfully lock it.</p> @see <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> @see <a href="QReadWriteLock.html#lockForRead()"><tt>lockForRead</tt></a> */"/> <method name="public final boolean tryLockForRead(int timeout)" doc="/** <p>Attempts to lock for reading. This function returns true if the lock was obtained; otherwise it returns false. If another thread has locked for writing, this function will wait for at most <tt>timeout</tt> milliseconds for the lock to become available.</p> <p>Note: Passing a negative number as the <tt>timeout</tt> is equivalent to calling <a href="QReadWriteLock.html#lockForRead()"><tt>lockForRead</tt></a>, i.e&#x2e; this function will wait forever until lock can be locked for reading when <tt>timeout</tt> is negative.</p> <p>If the lock was obtained, the lock must be unlocked with <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> before another thread can successfully lock it.</p> @see <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> @see <a href="QReadWriteLock.html#lockForRead()"><tt>lockForRead</tt></a> */"/> <method name="public final boolean tryLockForWrite(int timeout)" doc="/** <p>Attempts to lock for writing. This function returns true if the lock was obtained; otherwise it returns false. If another thread has locked for reading or writing, this function will wait for at most <tt>timeout</tt> milliseconds for the lock to become available.</p> <p>Note: Passing a negative number as the <tt>timeout</tt> is equivalent to calling <a href="QReadWriteLock.html#lockForWrite()"><tt>lockForWrite</tt></a>, i.e&#x2e; this function will wait forever until lock can be locked for writing when <tt>timeout</tt> is negative.</p> <p>If the lock was obtained, the lock must be unlocked with <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> before another thread can successfully lock it.</p> @see <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> @see <a href="QReadWriteLock.html#lockForWrite()"><tt>lockForWrite</tt></a> */"/> <method name="public final boolean tryLockForWrite()" doc="/** <p>Attempts to lock for writing. If the lock was obtained, this function returns true; otherwise, it returns false immediately.</p> <p>The lock attempt will fail if another thread has locked for reading or writing.</p> <p>If the lock was obtained, the lock must be unlocked with <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> before another thread can successfully lock it.</p> @see <a href="QReadWriteLock.html#unlock()"><tt>unlock</tt></a> @see <a href="QReadWriteLock.html#lockForWrite()"><tt>lockForWrite</tt></a> */"/> <method name="public final void unlock()" doc="/** <p>Unlocks the lock.</p> <p>Attempting to unlock a lock that is not locked is an error, and will result in program termination.</p> @see <a href="QReadWriteLock.html#lockForRead()"><tt>lockForRead</tt></a> @see <a href="QReadWriteLock.html#lockForWrite()"><tt>lockForWrite</tt></a> @see <a href="QReadWriteLock.html#tryLockForRead(int)"><tt>tryLockForRead</tt></a> @see <a href="QReadWriteLock.html#tryLockForWrite()"><tt>tryLockForWrite</tt></a> */"/> </class>