You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
237 lines
11 KiB
237 lines
11 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/shclass.doc:36 -->
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>Shared Classes</title>
|
|
<style type="text/css"><!--
|
|
fn { margin-left: 1cm; text-indent: -1cm; }
|
|
a:link { color: #004faf; text-decoration: none }
|
|
a:visited { color: #672967; text-decoration: none }
|
|
body { background: #ffffff; color: black; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|
<tr bgcolor="#E5E5E5">
|
|
<td valign=center>
|
|
<a href="index.html">
|
|
<font color="#004faf">Home</font></a>
|
|
| <a href="classes.html">
|
|
<font color="#004faf">All Classes</font></a>
|
|
| <a href="mainclasses.html">
|
|
<font color="#004faf">Main Classes</font></a>
|
|
| <a href="annotated.html">
|
|
<font color="#004faf">Annotated</font></a>
|
|
| <a href="groups.html">
|
|
<font color="#004faf">Grouped Classes</font></a>
|
|
| <a href="functions.html">
|
|
<font color="#004faf">Functions</font></a>
|
|
</td>
|
|
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Shared Classes</h1>
|
|
|
|
|
|
|
|
<p> <!-- index reference counting --><a name="reference-counting"></a><!-- index implicit sharing --><a name="implicit-sharing"></a><!-- index explicit sharing --><a name="explicit-sharing"></a><!-- index implicitly shared --><a name="implicitly-shared"></a><!-- index explicitly shared --><a name="explicitly-shared"></a><!-- index explicit sharing --><a name="explicit-sharing"></a><!-- index shared implicitly --><a name="shared-implicitly"></a><!-- index shared explicitly --><a name="shared-explicitly"></a>
|
|
<p> Many C++ classes in Qt use <em>explicit</em> and <em>implicit</em> data sharing
|
|
to maximize resource usage and minimize copying of data.
|
|
<p> <!-- toc -->
|
|
<ul>
|
|
<li><a href="#1"> Overview
|
|
</a>
|
|
<li><a href="#2"> A QByteArray Example
|
|
</a>
|
|
<li><a href="#3"> Explicit vs. Implicit Sharing
|
|
</a>
|
|
<li><a href="#4"> Explicitly Shared Classes
|
|
</a>
|
|
<li><a href="#5"> Implicitly Shared Classes
|
|
</a>
|
|
<li><a href="#6"> QCString: implicit or explicit?
|
|
</a>
|
|
</ul>
|
|
<!-- endtoc -->
|
|
|
|
<p> <h2> Overview
|
|
</h2>
|
|
<a name="1"></a><p> A shared class consists of a pointer to a shared data block that
|
|
contains a reference count and the data.
|
|
<p> When a shared object is created, it sets the reference count to 1. The
|
|
reference count is incremented whenever a new object references the
|
|
shared data, and decremented when the object dereferences the shared
|
|
data. The shared data is deleted when the reference count becomes
|
|
zero.
|
|
<p> <!-- index deep copy --><a name="deep-copy"></a><!-- index shallow copy --><a name="shallow-copy"></a>
|
|
<p> When dealing with shared objects, there are two ways of copying an
|
|
object. We usually speak about <em>deep</em> and <em>shallow</em> copies. A deep
|
|
copy implies duplicating an object. A shallow copy is a reference
|
|
copy, i.e. just a pointer to a shared data block. Making a deep copy
|
|
can be expensive in terms of memory and CPU. Making a shallow copy is
|
|
very fast, because it only involves setting a pointer and incrementing
|
|
the reference count.
|
|
<p> Object assignment (with operator=()) for implicitly and explicitly
|
|
shared objects is implemented using shallow copies. A deep copy can be
|
|
made by calling a copy() function or by using <a href="qdeepcopy.html">QDeepCopy</a>.
|
|
<p> The benefit of sharing is that a program does not need to duplicate
|
|
data unnecessarily, which results in lower memory use and less copying
|
|
of data. Objects can easily be assigned, sent as function arguments,
|
|
and returned from functions.
|
|
<p> Now comes the distinction between <em>explicit</em> and <em>implicit</em> sharing.
|
|
Explicit sharing means that the programmer must be aware of the fact
|
|
that objects share common data. Implicit sharing means that the
|
|
sharing mechanism takes place behind the scenes and the programmer
|
|
does not need to worry about it.
|
|
<p> <h2> A <a href="qbytearray.html">QByteArray</a> Example
|
|
</h2>
|
|
<a name="2"></a><p> QByteArray is an example of a shared class that uses explicit sharing.
|
|
Example:
|
|
<pre>
|
|
//Line a= b= c=
|
|
<a href="qbytearray.html">QByteArray</a> a(3),b(2) // 1: {?,?,?} {?,?}
|
|
b[0] = 12; b[1] = 34; // 2: {?,?,?} {12,34}
|
|
a = b; // 3: {12,34} {12,34}
|
|
a[1] = 56; // 4: {12,56} {12,56}
|
|
<a href="qbytearray.html">QByteArray</a> c = a; // 5: {12,56} {12,56} {12,56}
|
|
a.<a href="qmemarray.html#detach">detach</a>(); // 6: {12,56} {12,56} {12,56}
|
|
a[1] = 78; // 7: {12,78} {12,56} {12,56}
|
|
b = a.<a href="qmemarray.html#copy">copy</a>(); // 8: {12,78} {12,78} {12,56}
|
|
a[1] = 90; // 9: {12,90} {12,78} {12,56}
|
|
</pre>
|
|
|
|
<p> The assignment <tt>a = b</tt> on line 3 throws away <tt>a</tt>'s original shared
|
|
block (the reference count becomes zero), sets <tt>a</tt>'s shared block to
|
|
point to <tt>b</tt>'s shared block and increments the reference count.
|
|
<p> On line 4, the contents of <tt>a</tt> is modified. <tt>b</tt> is also modified,
|
|
because <tt>a</tt> and <tt>b</tt> refer to the same data block. This is the
|
|
difference between explicit and implicit sharing (explained below).
|
|
<p> The <tt>a</tt> object detaches from the common data on line 6. Detaching
|
|
means that the shared data is copied to make sure that an object has
|
|
its own private data. Therefore, modifying <tt>a</tt> on line 7 does not
|
|
affect <tt>b</tt> or <tt>c</tt>.
|
|
<p> Finally, on line 8 we make a deep copy of <tt>a</tt> and assign it to <tt>b</tt>,
|
|
so that when <tt>a</tt> is modified on line 9, <tt>b</tt> remains unchanged.
|
|
<p> <h2> Explicit vs. Implicit Sharing
|
|
</h2>
|
|
<a name="3"></a><p> Implicit sharing automatically detaches the object from a shared block
|
|
if the object is about to change and the reference count is greater
|
|
than one. (This is often called "copy-on-write".) Explicit sharing
|
|
leaves this job to the programmer. If an explicitly shared object is
|
|
not detached, changing an object will change all other objects that
|
|
refer to the same data.
|
|
<p> Implicit sharing optimizes memory use and copying of data without
|
|
this side effect. So why didn't we implement implicit sharing for all
|
|
shared classes? The answer is that a class that allows direct access
|
|
to its internal data (for efficiency reasons), like <a href="qbytearray.html">QByteArray</a>, cannot
|
|
be implicitly shared, because it can be changed without letting
|
|
QByteArray know.
|
|
<p> An implicitly shared class has total control of its internal data. In
|
|
any member functions that modify its data, it automatically detaches
|
|
before modifying the data.
|
|
<p> The <a href="qpen.html">QPen</a> class, which uses implicit sharing, detaches from the shared
|
|
data in all member functions that change the internal data.
|
|
<p> Code fragment:
|
|
<pre>
|
|
void QPen::setStyle( PenStyle s )
|
|
{
|
|
detach(); // detach from common data
|
|
data->style = s; // set the style member
|
|
}
|
|
|
|
void QPen::detach()
|
|
{
|
|
if ( data->count != 1 ) // only if >1 reference
|
|
*this = copy();
|
|
}
|
|
</pre>
|
|
|
|
<p> This is clearly not possible for QByteArray, because the programmer
|
|
can do the following:
|
|
<p> <pre>
|
|
<a href="qbytearray.html">QByteArray</a> array( 10 );
|
|
array.<a href="qmemarray.html#fill">fill</a>( 'a' );
|
|
array[0] = 'f'; // will modify array
|
|
array.<a href="qmemarray.html#data">data</a>()[1] = 'i'; // will modify array
|
|
</pre>
|
|
|
|
<p> If we monitor changes in a <a href="qbytearray.html">QByteArray</a>, the QByteArray class would
|
|
become unacceptably slow.
|
|
<p> <h2> Explicitly Shared Classes
|
|
</h2>
|
|
<a name="4"></a><p> All classes that are instances of the <a href="qmemarray.html">QMemArray</a> template class are
|
|
explicitly shared:
|
|
<p> <ul>
|
|
<li> <a href="qbitarray.html">QBitArray</a>
|
|
<li> <a href="qpointarray.html">QPointArray</a>
|
|
<li> <a href="qbytearray.html">QByteArray</a>
|
|
<li> Any other instantiation of <a href="qmemarray.html">QMemArray<type></a>
|
|
</ul>
|
|
<p> These classes have a detach() function that can be called if you want
|
|
your object to get a private copy of the shared data. They also have a
|
|
copy() function that returns a deep copy with a reference count of 1.
|
|
<p> The same is true for <a href="qimage.html">QImage</a>, which does not inherit QMemArray. <a href="qmovie.html">QMovie</a> is also explicitly shared, but it does not support detach() or
|
|
copy().
|
|
<p> <h2> Implicitly Shared Classes
|
|
</h2>
|
|
<a name="5"></a><p> The Qt classes that are implicitly shared are:
|
|
<ul>
|
|
<li> <a href="qbitmap.html">QBitmap</a>
|
|
<li> <a href="qbrush.html">QBrush</a>
|
|
<li> <a href="qcursor.html">QCursor</a>
|
|
<li> <a href="qfont.html">QFont</a>
|
|
<li> <a href="qfontinfo.html">QFontInfo</a>
|
|
<li> <a href="qfontmetrics.html">QFontMetrics</a>
|
|
<li> <a href="qiconset.html">QIconSet</a>
|
|
<li> <a href="qmap.html">QMap</a>
|
|
<li> <a href="qpalette.html">QPalette</a>
|
|
<li> <a href="qpen.html">QPen</a>
|
|
<li> <a href="qpicture.html">QPicture</a>
|
|
<li> <a href="qpixmap.html">QPixmap</a>
|
|
<li> <a href="qregion.html">QRegion</a>
|
|
<li> <a href="qregexp.html">QRegExp</a>
|
|
<li> <a href="qstring.html">QString</a>
|
|
<li> <a href="qstringlist.html">QStringList</a>
|
|
<li> <a href="qvaluelist.html">QValueList</a>
|
|
<li> <a href="qvaluestack.html">QValueStack</a>
|
|
</ul>
|
|
<p> These classes automatically detach from common data if an object is
|
|
about to be changed. The programmer will not even notice that the
|
|
objects are shared. Thus you should treat separate instances of them
|
|
as separate objects. They will always behave as separate objects but
|
|
with the added benefit of sharing data whenever possible. For this
|
|
reason, you can pass instances of these classes as arguments to
|
|
functions by value without concern for the copying overhead.
|
|
<p> Example:
|
|
<pre>
|
|
<a href="qpixmap.html">QPixmap</a> p1, p2;
|
|
p1.<a href="qpixmap.html#load">load</a>( "image.bmp" );
|
|
p2 = p1; // p1 and p2 share data
|
|
<a href="qpainter.html">QPainter</a> paint;
|
|
paint.<a href="qpainter.html#begin">begin</a>( &p2 ); // cuts p2 loose from p1
|
|
paint.<a href="qpainter.html#drawText">drawText</a>( 0,50, "Hi" );
|
|
paint.<a href="qpainter.html#end">end</a>();
|
|
</pre>
|
|
|
|
<p> In this example, <tt>p1</tt> and <tt>p2</tt> share data until <a href="qpainter.html#begin">QPainter::begin</a>() is
|
|
called for <tt>p2</tt>, because painting a pixmap will modify it. The same
|
|
also happens if anything is <a href="qimage.html#bitBlt">bitBlt()</a>'ed into
|
|
<tt>p2</tt>.
|
|
<p> <b>Warning:</b> Do not copy an implicitly shared container (<a href="qmap.html">QMap</a>,
|
|
<a href="qvaluevector.html">QValueVector</a>, etc.) while you are iterating over it.
|
|
<p> <h2> QCString: implicit or explicit?
|
|
</h2>
|
|
<a name="6"></a><p> <a href="qcstring.html">QCString</a> uses a mixture of implicit and explicit sharing. Functions
|
|
inherited from <a href="qbytearray.html">QByteArray</a>, such as data(), employ explicit sharing, while
|
|
those only in <a href="qcstring.html">QCString</a> detach automatically. Thus, QCString is rather an
|
|
"experts only" class, provided mainly to ease porting from Qt 1.x to Qt 2.0.
|
|
We recommend that you use <a href="qstring.html">QString</a>, a purely implicitly shared class.
|
|
<p>
|
|
<!-- eof -->
|
|
<p><address><hr><div align=center>
|
|
<table width=100% cellspacing=0 border=0><tr>
|
|
<td>Copyright © 2007
|
|
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
|
<td align=right><div align=right>Qt 3.3.8</div>
|
|
</table></div></address></body>
|
|
</html>
|