summaryrefslogtreecommitdiffstats
path: root/src/tools/qdeepcopy.cpp
diff options
context:
space:
mode:
Diffstat (limited to 'src/tools/qdeepcopy.cpp')
-rw-r--r--src/tools/qdeepcopy.cpp168
1 files changed, 168 insertions, 0 deletions
diff --git a/src/tools/qdeepcopy.cpp b/src/tools/qdeepcopy.cpp
new file mode 100644
index 0000000..fda109e
--- /dev/null
+++ b/src/tools/qdeepcopy.cpp
@@ -0,0 +1,168 @@
+/****************************************************************************
+**
+** Implementation of QDeepCopy class
+**
+** Created : 20020613
+**
+** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
+**
+** This file is part of the kernel module of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing requirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at [email protected].
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file. Licensees holding valid Qt
+** Commercial licenses may use this file in accordance with the Qt
+** Commercial License Agreement provided with the Software.
+**
+** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
+** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+
+#include "qdeepcopy.h"
+
+/*!
+ \class QDeepCopy qdeepcopy.h
+ \brief The QDeepCopy class is a template class which ensures that
+ implicitly shared and explicitly shared classes reference unique
+ data.
+
+ \reentrant
+
+ \ingroup tools
+ \ingroup shared
+
+ Normally, shared copies reference the same data to optimize memory
+ use and for maximum speed. In the example below, \c s1, \c s2, \c
+ s3, \c s4 and \c s5 share data.
+
+ \code
+ // all 5 strings share the same data
+ QString s1 = "abcd";
+ QString s2 = s1;
+ QString s3 = s2;
+ QString s4 = s3;
+ QString s5 = s2;
+ \endcode
+
+ QDeepCopy can be used several ways to ensure that an object
+ references unique, unshared data. In the example below, \c s1, \c
+ s2 and \c s5 share data, while neither \c s3 nor \c s4 share data.
+ \code
+ // s1, s2 and s5 share the same data, neither s3 nor s4 are shared
+ QString s1 = "abcd";
+ QString s2 = s1;
+ QDeepCopy<QString> s3 = s2; // s3 is a deep copy of s2
+ QString s4 = s3; // s4 is a deep copy of s3
+ QString s5 = s2;
+ \endcode
+
+ In the example below, \c s1, \c s2 and \c s5 share data, and \c s3
+ and \c s4 share data.
+ \code
+ // s1, s2 and s5 share the same data, s3 and s4 share the same data
+ QString s1 = "abcd";
+ QString s2 = s1;
+ QString s3 = QDeepCopy<QString>( s2 ); // s3 is a deep copy of s2
+ QString s4 = s3; // s4 is a shallow copy of s3
+ QString s5 = s2;
+ \endcode
+
+ QDeepCopy can also provide safety in multithreaded applications
+ that use shared classes. In the example below, the variable \c
+ global_string is used safely since the data contained in \c
+ global_string is always a deep copy. This ensures that all threads
+ get a unique copy of the data, and that any assignments to \c
+ global_string will result in a deep copy.
+
+ \code
+ QDeepCopy<QString> global_string; // global string data
+ QMutex global_mutex; // mutex to protext global_string
+
+ ...
+
+ void setGlobalString( const QString &str )
+ {
+ global_mutex.lock();
+ global_string = str; // global_string is a deep copy of str
+ global_mutex.unlock();
+ }
+
+ ...
+
+ void MyThread::run()
+ {
+ global_mutex.lock();
+ QString str = global_string; // str is a deep copy of global_string
+ global_mutex.unlock();
+
+ // process the string data
+ ...
+
+ // update global_string
+ setGlobalString( str );
+ }
+ \endcode
+
+ \warning It is the application developer's responsibility to
+ protect the object shared across multiple threads.
+
+ The examples above use QString, which is an implicitly shared
+ class. The behavior of QDeepCopy is the same when using explicitly
+ shared classes like QByteArray.
+
+ Currently, QDeepCopy works with the following classes:
+ \list
+ \i QMemArray (including subclasses like QByteArray and QCString)
+ \i QMap
+ \i QString
+ \i QValueList (including subclasses like QStringList and QValueStack)
+ \i QValueVector
+ \endlist
+
+ \sa \link threads.html Thread Support in Qt \endlink
+*/
+
+/*!
+ \fn QDeepCopy::QDeepCopy()
+
+ Constructs an empty instance of type \e T.
+*/
+
+/*!
+ \fn QDeepCopy::QDeepCopy( const T &t )
+
+ Constructs a deep copy of \a t.
+*/
+
+/*!
+ \fn QDeepCopy<T>& QDeepCopy::operator=( const T &t )
+
+ Assigns a deep copy of \a t.
+*/
+
+/*!
+ \fn QDeepCopy::operator T ()
+
+ Returns a deep copy of the encapsulated data.
+*/
+