source: trunk/src/tools/qdeepcopy.cpp@ 95

Last change on this file since 95 was 2, checked in by dmik, 20 years ago

Imported xplatform parts of the official release 3.3.1 from Trolltech
  • Property svn:keywords set to Id
File size: 5.1 KB
Line 
1/****************************************************************************
2** $Id: qdeepcopy.cpp 2 2005-11-16 15:49:26Z dmik $
3**
4** Implementation of QDeepCopy class
5**
6** Created : 20020613
7**
8** Copyright (C) 1992-2002 Trolltech AS. All rights reserved.
9**
10** This file is part of the kernel module of the Qt GUI Toolkit.
11**
12** This file may be distributed under the terms of the Q Public License
13** as defined by Trolltech AS of Norway and appearing in the file
14** LICENSE.QPL included in the packaging of this file.
15**
16** This file may be distributed and/or modified under the terms of the
17** GNU General Public License version 2 as published by the Free Software
18** Foundation and appearing in the file LICENSE.GPL included in the
19** packaging of this file.
20**
21** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
22** licenses may use this file in accordance with the Qt Commercial License
23** Agreement provided with the Software.
24**
25** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
26** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
27**
28** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
29** information about Qt Commercial License Agreements.
30** See http://www.trolltech.com/qpl/ for QPL licensing information.
31** See http://www.trolltech.com/gpl/ for GPL licensing information.
32**
33** Contact info@trolltech.com if any conditions of this licensing are
34** not clear to you.
35**
36**********************************************************************/
37
38#include "qdeepcopy.h"
39
40/*!
41 \class QDeepCopy qdeepcopy.h
42 \brief The QDeepCopy class is a template class which ensures that
43 implicitly shared and explicitly shared classes reference unique
44 data.
45
46 \reentrant
47
48 \ingroup tools
49 \ingroup shared
50
51 Normally, shared copies reference the same data to optimize memory
52 use and for maximum speed. In the example below, \c s1, \c s2, \c
53 s3, \c s4 and \c s5 share data.
54
55 \code
56 // all 5 strings share the same data
57 QString s1 = "abcd";
58 QString s2 = s1;
59 QString s3 = s2;
60 QString s4 = s3;
61 QString s5 = s2;
62 \endcode
63
64 QDeepCopy can be used several ways to ensure that an object
65 references unique, unshared data. In the example below, \c s1, \c
66 s2 and \c s5 share data, while neither \c s3 nor \c s4 share data.
67 \code
68 // s1, s2 and s5 share the same data, neither s3 nor s4 are shared
69 QString s1 = "abcd";
70 QString s2 = s1;
71 QDeepCopy<QString> s3 = s2; // s3 is a deep copy of s2
72 QString s4 = s3; // s4 is a deep copy of s3
73 QString s5 = s2;
74 \endcode
75
76 In the example below, \c s1, \c s2 and \c s5 share data, and \c s3
77 and \c s4 share data.
78 \code
79 // s1, s2 and s5 share the same data, s3 and s4 share the same data
80 QString s1 = "abcd";
81 QString s2 = s1;
82 QString s3 = QDeepCopy<QString>( s2 ); // s3 is a deep copy of s2
83 QString s4 = s3; // s4 is a shallow copy of s3
84 QString s5 = s2;
85 \endcode
86
87 QDeepCopy can also provide safety in multithreaded applications
88 that use shared classes. In the example below, the variable \c
89 global_string is used safely since the data contained in \c
90 global_string is always a deep copy. This ensures that all threads
91 get a unique copy of the data, and that any assignments to \c
92 global_string will result in a deep copy.
93
94 \code
95 QDeepCopy<QString> global_string; // global string data
96 QMutex global_mutex; // mutex to protext global_string
97
98 ...
99
100 void setGlobalString( const QString &str )
101 {
102 global_mutex.lock();
103 global_string = str; // global_string is a deep copy of str
104 global_mutex.unlock();
105 }
106
107 ...
108
109 void MyThread::run()
110 {
111 global_mutex.lock();
112 QString str = global_string; // str is a deep copy of global_string
113 global_mutex.unlock();
114
115 // process the string data
116 ...
117
118 // update global_string
119 setGlobalString( str );
120 }
121 \endcode
122
123 \warning It is the application developer's responsibility to
124 protect the object shared across multiple threads.
125
126 The examples above use QString, which is an implicitly shared
127 class. The behavior of QDeepCopy is the same when using explicitly
128 shared classes like QByteArray.
129
130 Currently, QDeepCopy works with the following classes:
131 \list
132 \i QMemArray (including subclasses like QByteArray and QCString)
133 \i QMap
134 \i QString
135 \i QValueList (including subclasses like QStringList and QValueStack)
136 \i QValueVector
137 \endlist
138
139 \sa \link threads.html Thread Support in Qt \endlink
140*/
141
142/*!
143 \fn QDeepCopy::QDeepCopy()
144
145 Constructs an empty instance of type \e T.
146*/
147
148/*!
149 \fn QDeepCopy::QDeepCopy( const T &t )
150
151 Constructs a deep copy of \a t.
152*/
153
154/*!
155 \fn QDeepCopy<T>& QDeepCopy::operator=( const T &t )
156
157 Assigns a deep copy of \a t.
158*/
159
160/*!
161 \fn QDeepCopy::operator T ()
162
163 Returns a deep copy of the encapsulated data.
164*/
165
Note: See TracBrowser for help on using the repository browser.