diff options
Diffstat (limited to 'src/corelib/tools/qshareddata.cpp')
| -rw-r--r-- | src/corelib/tools/qshareddata.cpp | 137 |
1 files changed, 81 insertions, 56 deletions
diff --git a/src/corelib/tools/qshareddata.cpp b/src/corelib/tools/qshareddata.cpp index 187bfa7a5d..8ef174ebfc 100644 --- a/src/corelib/tools/qshareddata.cpp +++ b/src/corelib/tools/qshareddata.cpp @@ -1,41 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the QtCore module of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 3 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL3 included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 3 requirements -** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 2.0 or (at your option) the GNU General -** Public license version 3 or any later version approved by the KDE Free -** Qt Foundation. The licenses are as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 -** included in the packaging of this file. Please review the following -** information to ensure the GNU General Public License requirements will -** be met: https://www.gnu.org/licenses/gpl-2.0.html and -** https://www.gnu.org/licenses/gpl-3.0.html. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only #include <qshareddata.h> @@ -65,6 +29,20 @@ QT_BEGIN_NAMESPACE */ /*! + \class QAdoptSharedDataTag + \inmodule QtCore + \threadsafe + \brief The QAdoptSharedDataTag is a helper tag class. + \since 6.0 + + QAdoptSharedDataTag objects are used in QSharedDataPointer + and QExplicitlySharedDataPointer to adopt a pointer to + shared data. + + See QSharedDataPointer and QExplicitlySharedDataPointer for details. +*/ + +/*! \class QSharedDataPointer \inmodule QtCore \brief The QSharedDataPointer class represents a pointer to an implicitly shared object. @@ -302,6 +280,18 @@ QT_BEGIN_NAMESPACE Same as data(). This function is provided for STL compatibility. */ +/*! \fn template <class T> const T* QSharedDataPointer<T>::take() + \since 6.0 + + Returns a pointer to the shared object, and resets \e this to be \nullptr. + (That is, this function sets the \e{d pointer} of \e this to \nullptr.) + + \note The reference count of the returned object will \b{not} be + decremented. This function can be used together with the + constructor that takes a QAdoptSharedDataTag tag object to transfer + the shared data object without intervening atomic operations. +*/ + /*! \fn template <class T> const T* QSharedDataPointer<T>::constData() const Returns a const pointer to the shared data object. This function does \e not call detach(). @@ -309,6 +299,15 @@ QT_BEGIN_NAMESPACE \sa data() */ +/*! \fn template <class T> void QSharedDataPointer<T>::reset(T *ptr = nullptr) + \since 6.0 + + Sets the \e{d pointer} of \e this to \a ptr and increments \a{ptr}'s reference + count if \a ptr is not \nullptr. + The reference count of the old shared data object is decremented, + and the object deleted if the reference count reaches 0. + */ + /*! \fn template <class T> void QSharedDataPointer<T>::swap(QSharedDataPointer &other) Swap this instance's shared data pointer with the shared data pointer in \a other. @@ -322,13 +321,23 @@ QT_BEGIN_NAMESPACE \since 5.2 */ -/*! \fn template <class T> bool QSharedDataPointer<T>::operator==(const QSharedDataPointer<T>& other) const - Returns \c true if \a other and \e this have the same \e{d pointer}. +/*! \fn template <class T> bool QSharedDataPointer<T>::operator==(const QSharedDataPointer<T>& lhs, const QSharedDataPointer<T>& rhs) + Returns \c true if \a lhs and \a rhs have the same \e{d pointer}. + This function does \e not call detach(). +*/ + +/*! \fn template <class T> bool QSharedDataPointer<T>::operator!=(const QSharedDataPointer<T>& lhs, const QSharedDataPointer<T>& rhs) + Returns \c true if \a lhs and \a rhs do \e not have the same + \e{d pointer}. This function does \e not call detach(). +*/ + +/*! \fn template <class T> bool QSharedDataPointer<T>::operator==(const T *ptr, const QSharedDataPointer<T>& rhs) + Returns \c true if the \e{d pointer} of \a rhs is \a ptr. This function does \e not call detach(). */ -/*! \fn template <class T> bool QSharedDataPointer<T>::operator!=(const QSharedDataPointer<T>& other) const - Returns \c true if \a other and \e this do \e not have the same +/*! \fn template <class T> bool QSharedDataPointer<T>::operator!=(const T *ptr, const QSharedDataPointer<T>& rhs) + Returns \c true if the \e{d pointer} of \a rhs is \e not \a ptr. \e{d pointer}. This function does \e not call detach(). */ @@ -356,6 +365,15 @@ QT_BEGIN_NAMESPACE \a data and increments \a{data}'s reference count. */ +/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(T* data, QAdoptSharedDataTag) + \since 6.0 + Constructs a QSharedDataPointer with \e{d pointer} set to + \a data. \a data's reference counter is \b{not} incremented; + this can be used to adopt pointers obtained from take(). + + \sa take() +*/ + /*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(const QSharedDataPointer<T>& o) Sets the \e{d pointer} of \e this to the \e{d pointer} in \a o and increments the reference count of the shared @@ -486,8 +504,8 @@ QT_BEGIN_NAMESPACE the explicitly shared data pointer in \a other. */ -/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const QExplicitlySharedDataPointer<T>& other) const - Returns \c true if \a other and \e this have the same \e{d pointer}. +/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs) + Returns \c true if \a lhs and \a rhs have the same \e{d pointer}. */ /*! @@ -498,17 +516,17 @@ QT_BEGIN_NAMESPACE \since 5.2 */ -/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const T* ptr) const - Returns \c true if the \e{d pointer} of \e this is \a ptr. +/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const T* ptr, const QExplicitlySharedDataPointer<T>& rhs) + Returns \c true if the \e{d pointer} of \a rhs is \a ptr. */ -/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const QExplicitlySharedDataPointer<T>& other) const - Returns \c true if \a other and \e this do \e not have the same +/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs) + Returns \c true if \a lhs and \a rhs do \e not have the same \e{d pointer}. */ -/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const T* ptr) const - Returns \c true if the \e{d pointer} of \e this is \e not \a ptr. +/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const T* ptr, const QExplicitlySharedDataPointer<T>& rhs) + Returns \c true if the \e{d pointer} of \a rhs is \e not \a ptr. */ /*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer() @@ -590,18 +608,25 @@ QT_BEGIN_NAMESPACE 0, the old shared data object is deleted. */ -/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::reset() - Resets \e this to be null - i.e., this function sets the - \e{d pointer} of \e this to \nullptr, but first it decrements - the reference count of the shared data object and deletes - the shared data object if the reference count became 0. +/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::reset(T *ptr = nullptr) + \since 6.0 + + Sets the \e{d pointer} of \e this to \a ptr and increments \a{ptr}'s reference + count if \a ptr is not \nullptr. + The reference count of the old shared data object is decremented, + and the object deleted if the reference count reaches 0. */ /*! \fn template <class T> T *QExplicitlySharedDataPointer<T>::take() \since 5.12 Returns a pointer to the shared object, and resets \e this to be \nullptr. - That is, this function sets the \e{d pointer} of \e this to \nullptr. + (That is, this function sets the \e{d pointer} of \e this to \nullptr.) + + \note The reference count of the returned object will \b{not} be + decremented. This function can be used together with the + constructor that takes a QAdoptSharedDataTag tag object to transfer + the shared data object without intervening atomic operations. */ /*! \fn template <class T> QExplicitlySharedDataPointer<T>::operator bool () const |