source: trunk/doc/html/qdeepcopy.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 7.6 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/tools/qdeepcopy.cpp:40 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QDeepCopy Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QDeepCopy Class Reference</h1>
33
34<p>The QDeepCopy class is a template class which ensures that
35implicitly shared and explicitly shared classes reference unique
36data.
37<a href="#details">More...</a>
38<p>All the functions in this class are <a href="threads.html#reentrant">reentrant</a> when Qt is built with thread support.</p>
39<p><tt>#include &lt;<a href="qdeepcopy-h.html">qdeepcopy.h</a>&gt;</tt>
40<p><a href="qdeepcopy-members.html">List of all member functions.</a>
41<h2>Public Members</h2>
42<ul>
43<li class=fn><a href="#QDeepCopy"><b>QDeepCopy</b></a> ()</li>
44<li class=fn><a href="#QDeepCopy-2"><b>QDeepCopy</b></a> ( const&nbsp;T&nbsp;&amp;&nbsp;t )</li>
45<li class=fn>QDeepCopy&lt;T&gt; &amp; <a href="#operator-eq"><b>operator=</b></a> ( const&nbsp;T&nbsp;&amp;&nbsp;t )</li>
46<li class=fn><a href="#operator-T"><b>operator T</b></a> ()</li>
47</ul>
48<hr><a name="details"></a><h2>Detailed Description</h2>
49
50
51The QDeepCopy class is a template class which ensures that
52<a href="shclass.html#implicitly-shared">implicitly shared</a> and <a href="shclass.html#explicitly-shared">explicitly shared</a> classes reference unique
53data.
54<p>
55<p>
56
57<p> Normally, shared copies reference the same data to optimize memory
58use and for maximum speed. In the example below, <tt>s1</tt>, <tt>s2</tt>, <tt>s3</tt>, <tt>s4</tt> and <tt>s5</tt> share data.
59<p> <pre>
60 // all 5 strings share the same data
61 <a href="qstring.html">QString</a> s1 = "abcd";
62 <a href="qstring.html">QString</a> s2 = s1;
63 <a href="qstring.html">QString</a> s3 = s2;
64 <a href="qstring.html">QString</a> s4 = s3;
65 <a href="qstring.html">QString</a> s5 = s2;
66 </pre>
67
68<p> QDeepCopy can be used several ways to ensure that an object
69references unique, unshared data. In the example below, <tt>s1</tt>, <tt>s2</tt> and <tt>s5</tt> share data, while neither <tt>s3</tt> nor <tt>s4</tt> share data.
70<pre>
71 // s1, s2 and s5 share the same data, neither s3 nor s4 are shared
72 <a href="qstring.html">QString</a> s1 = "abcd";
73 <a href="qstring.html">QString</a> s2 = s1;
74 QDeepCopy&lt;QString&gt; s3 = s2; // s3 is a <a href="shclass.html#deep-copy">deep copy</a> of s2
75 <a href="qstring.html">QString</a> s4 = s3; // s4 is a deep copy of s3
76 <a href="qstring.html">QString</a> s5 = s2;
77 </pre>
78
79<p> In the example below, <tt>s1</tt>, <tt>s2</tt> and <tt>s5</tt> share data, and <tt>s3</tt>
80and <tt>s4</tt> share data.
81<pre>
82 // s1, s2 and s5 share the same data, s3 and s4 share the same data
83 <a href="qstring.html">QString</a> s1 = "abcd";
84 <a href="qstring.html">QString</a> s2 = s1;
85 <a href="qstring.html">QString</a> s3 = QDeepCopy&lt;QString&gt;( s2 ); // s3 is a deep copy of s2
86 <a href="qstring.html">QString</a> s4 = s3; // s4 is a <a href="shclass.html#shallow-copy">shallow copy</a> of s3
87 <a href="qstring.html">QString</a> s5 = s2;
88 </pre>
89
90<p> QDeepCopy can also provide safety in multithreaded applications
91that use shared classes. In the example below, the variable <tt>global_string</tt> is used safely since the data contained in <tt>global_string</tt> is always a deep copy. This ensures that all threads
92get a unique copy of the data, and that any assignments to <tt>global_string</tt> will result in a deep copy.
93<p> <pre>
94 QDeepCopy&lt;QString&gt; global_string; // global string data
95 <a href="qmutex.html">QMutex</a> global_mutex; // mutex to protext global_string
96
97 ...
98
99 void setGlobalString( const <a href="qstring.html">QString</a> &amp;str )
100 {
101 global_mutex.<a href="qmutex.html#lock">lock</a>();
102 global_string = str; // global_string is a deep copy of str
103 global_mutex.<a href="qmutex.html#unlock">unlock</a>();
104 }
105
106 ...
107
108 void MyThread::run()
109 {
110 global_mutex.<a href="qmutex.html#lock">lock</a>();
111 <a href="qstring.html">QString</a> str = global_string; // str is a deep copy of global_string
112 global_mutex.<a href="qmutex.html#unlock">unlock</a>();
113
114 // process the string data
115 ...
116
117 // update global_string
118 setGlobalString( str );
119 }
120 </pre>
121
122<p> <b>Warning:</b> It is the application developer's responsibility to
123protect the object shared across multiple threads.
124<p> The examples above use <a href="qstring.html">QString</a>, which is an implicitly shared
125class. The behavior of QDeepCopy is the same when using explicitly
126shared classes like <a href="qbytearray.html">QByteArray</a>.
127<p> Currently, QDeepCopy works with the following classes:
128<ul>
129<li> <a href="qmemarray.html">QMemArray</a> (including subclasses like QByteArray and <a href="qcstring.html">QCString</a>)
130<li> <a href="qmap.html">QMap</a>
131<li> QString
132<li> <a href="qvaluelist.html">QValueList</a> (including subclasses like <a href="qstringlist.html">QStringList</a> and <a href="qvaluestack.html">QValueStack</a>)
133<li> <a href="qvaluevector.html">QValueVector</a>
134</ul>
135<p> <p>See also <a href="threads.html">Thread Support in Qt</a>, <a href="shared.html">Implicitly and Explicitly Shared Classes</a>, and <a href="tools.html">Non-GUI Classes</a>.
136
137<hr><h2>Member Function Documentation</h2>
138<h3 class=fn><a name="QDeepCopy"></a>QDeepCopy::QDeepCopy ()
139</h3>
140
141<p> Constructs an empty instance of type <em>T</em>.
142
143<h3 class=fn><a name="QDeepCopy-2"></a>QDeepCopy::QDeepCopy ( const&nbsp;T&nbsp;&amp;&nbsp;t )
144</h3>
145
146<p> Constructs a <a href="shclass.html#deep-copy">deep copy</a> of <em>t</em>.
147
148<h3 class=fn><a name="operator-T"></a>QDeepCopy::operator T ()
149</h3>
150
151<p> Returns a <a href="shclass.html#deep-copy">deep copy</a> of the encapsulated data.
152
153<h3 class=fn><a href="qdeepcopy.html">QDeepCopy</a>&lt;T&gt;&nbsp;&amp; <a name="operator-eq"></a>QDeepCopy::operator= ( const&nbsp;T&nbsp;&amp;&nbsp;t )
154</h3>
155
156<p> Assigns a <a href="shclass.html#deep-copy">deep copy</a> of <em>t</em>.
157
158<!-- eof -->
159<hr><p>
160This file is part of the <a href="index.html">Qt toolkit</a>.
161Copyright &copy; 1995-2007
162<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
163<table width=100% cellspacing=0 border=0><tr>
164<td>Copyright &copy; 2007
165<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
166<td align=right><div align=right>Qt 3.3.8</div>
167</table></div></address></body>
168</html>
Note: See TracBrowser for help on using the repository browser.