← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to src/qt3support/tools/q3deepcopy.cpp

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-08-24 04:09:09 UTC
  • Revision ID: james.westby@ubuntu.com-20050824040909-xmxe9jfr4a0w5671
Tags: upstream-4.0.0
Import upstream version 4.0.0

Show diffs side-by-side

added added

removed removed

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