<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- implicit-sharing.qdoc -->
<title>Qt 4.8: Implicit Sharing</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Implicit Sharing</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#overview">Overview</a></li>
<li class="level1"><a href="#implicit-sharing-in-detail">Implicit Sharing in Detail</a></li>
<li class="level1"><a href="#list-of-classes">List of Classes</a></li>
</ul>
</div>
<h1 class="title">Implicit Sharing</h1>
<span class="subtitle"></span>
<!-- $$$implicit-sharing.html-description -->
<div class="descr"> <a name="details"></a>
<a name="implicit-data-sharing"></a><a name="implicit-sharing"></a><a name="implicitly-shared"></a><a name="reference-counting"></a><a name="shared-implicitly"></a><a name="shared-classes"></a><p>Many C++ classes in Qt use implicit data sharing to maximize resource usage and minimize copying. Implicitly shared classes are both safe and efficient when passed as arguments, because only a pointer to the data is passed around, and the data is copied only if and when a function writes to it, i.e., <i>copy-on-write</i>.</p>
<a name="overview"></a>
<h2>Overview</h2>
<p>A shared class consists of a pointer to a shared data block that contains a reference count and the data.</p>
<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>
<a name="deep-copy"></a><a name="shallow-copy"></a><p>When dealing with shared objects, there are two ways of copying an object. We usually speak about <i>deep</i> and <i>shallow</i> 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>
<p>Object assignment (with operator=()) for implicitly shared objects is implemented using shallow copies.</p>
<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>
<p>Implicit sharing takes place behind the scenes; the programmer does not need to worry about it. Even in multithreaded applications, implicit sharing takes place, as explained in <a href="threads-modules.html#threads-and-implicitly-shared-classes">Threads and Implicitly Shared Classes</a>.</p>
<p>When implementing your own implicitly shared classes, use the <a href="qshareddata.html">QSharedData</a> and <a href="qshareddatapointer.html">QSharedDataPointer</a> classes.</p>
<a name="implicit-sharing-in-detail"></a>
<h2>Implicit Sharing in Detail</h2>
<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 <i>copy-on-write</i> or <i>value semantics</i>.)</p>
<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>
<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>
<p>Code fragment:</p>
<pre class="cpp"> <span class="type">void</span> <span class="type"><a href="qpen.html">QPen</a></span><span class="operator">::</span>setStyle(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>PenStyle style)
{
detach(); <span class="comment">// detach from common data</span>
d<span class="operator">-</span><span class="operator">></span>style <span class="operator">=</span> style; <span class="comment">// set the style member</span>
}
<span class="type">void</span> <span class="type"><a href="qpen.html">QPen</a></span><span class="operator">::</span>detach()
{
<span class="keyword">if</span> (d<span class="operator">-</span><span class="operator">></span>ref <span class="operator">!</span><span class="operator">=</span> <span class="number">1</span>) {
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> <span class="comment">// perform a deep copy</span>
}
}</pre>
<a name="list-of-classes"></a>
<h2>List of Classes</h2>
<p>The classes listed below 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>
<p>Example:</p>
<pre class="cpp"> <span class="type"><a href="qpixmap.html">QPixmap</a></span> p1<span class="operator">,</span> p2;
p1<span class="operator">.</span>load(<span class="string">"image.bmp"</span>);
p2 <span class="operator">=</span> p1; <span class="comment">// p1 and p2 share data</span>
<span class="type"><a href="qpainter.html">QPainter</a></span> paint;
paint<span class="operator">.</span>begin(<span class="operator">&</span>p2); <span class="comment">// cuts p2 loose from p1</span>
paint<span class="operator">.</span>drawText(<span class="number">0</span><span class="operator">,</span><span class="number">50</span><span class="operator">,</span> <span class="string">"Hi"</span>);
paint<span class="operator">.</span>end();</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.</p>
<p><b>Warning:</b> Do not copy an implicitly shared container (<a href="qmap.html">QMap</a>, <a href="qvector.html">QVector</a>, etc.) while you are iterating over it using an non-const <a href="containers.html#stl-style-iterators">STL-style iterator</a>.</p>
<a name="implicitly-shared-classes"></a><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qbitarray.html">QBitArray</a></p></td><td class="tblDescr"><p>Array of bits</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qbitmap.html">QBitmap</a></p></td><td class="tblDescr"><p>Monochrome (1-bit depth) pixmaps</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qbrush.html">QBrush</a></p></td><td class="tblDescr"><p>Defines the fill pattern of shapes drawn by QPainter</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qbytearray.html">QByteArray</a></p></td><td class="tblDescr"><p>Array of bytes</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcache.html">QCache</a></p></td><td class="tblDescr"><p>Template class that provides a cache</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontiguouscache.html">QContiguousCache</a></p></td><td class="tblDescr"><p>Template class that provides a contiguous cache</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcursor.html">QCursor</a></p></td><td class="tblDescr"><p>Mouse cursor with an arbitrary shape</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qdir.html">QDir</a></p></td><td class="tblDescr"><p>Access to directory structures and their contents</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qfileinfo.html">QFileInfo</a></p></td><td class="tblDescr"><p>System-independent file information</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qfont.html">QFont</a></p></td><td class="tblDescr"><p>Specifies a font used for drawing text</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qfontinfo.html">QFontInfo</a></p></td><td class="tblDescr"><p>General information about fonts</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qfontmetrics.html">QFontMetrics</a></p></td><td class="tblDescr"><p>Font metrics information</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qfontmetricsf.html">QFontMetricsF</a></p></td><td class="tblDescr"><p>Font metrics information</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qglcolormap.html">QGLColormap</a></p></td><td class="tblDescr"><p>Used for installing custom colormaps into a QGLWidget</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qgradient.html">QGradient</a></p></td><td class="tblDescr"><p>Used in combination with QBrush to specify gradient fills</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qhash.html">QHash</a></p></td><td class="tblDescr"><p>Template class that provides a hash-table-based dictionary</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qicon.html">QIcon</a></p></td><td class="tblDescr"><p>Scalable icons in different modes and states</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qimage.html">QImage</a></p></td><td class="tblDescr"><p>Hardware-independent image representation that allows direct access to the pixel data, and can be used as a paint device</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qkeysequence.html">QKeySequence</a></p></td><td class="tblDescr"><p>Encapsulates a key sequence as used by shortcuts</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qlinkedlist.html">QLinkedList</a></p></td><td class="tblDescr"><p>Template class that provides linked lists</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qlist.html">QList</a></p></td><td class="tblDescr"><p>Template class that provides lists</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qlocale.html">QLocale</a></p></td><td class="tblDescr"><p>Converts between numbers and their string representations in various languages</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qmap.html">QMap</a></p></td><td class="tblDescr"><p>Template class that provides a skip-list-based dictionary</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qmultihash.html">QMultiHash</a></p></td><td class="tblDescr"><p>Convenience QHash subclass that provides multi-valued hashes</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qmultimap.html">QMultiMap</a></p></td><td class="tblDescr"><p>Convenience QMap subclass that provides multi-valued maps</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qpainterpath.html">QPainterPath</a></p></td><td class="tblDescr"><p>Container for painting operations, enabling graphical shapes to be constructed and reused</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qpalette.html">QPalette</a></p></td><td class="tblDescr"><p>Contains color groups for each widget state</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qpen.html">QPen</a></p></td><td class="tblDescr"><p>Defines how a QPainter should draw lines and outlines of shapes</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qpicture.html">QPicture</a></p></td><td class="tblDescr"><p>Paint device that records and replays QPainter commands</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qpixmap.html">QPixmap</a></p></td><td class="tblDescr"><p>Off-screen image representation that can be used as a paint device</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qpolygon.html">QPolygon</a></p></td><td class="tblDescr"><p>Vector of points using integer precision</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qpolygonf.html">QPolygonF</a></p></td><td class="tblDescr"><p>Vector of points using floating point precision</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qqueue.html">QQueue</a></p></td><td class="tblDescr"><p>Generic container that provides a queue</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qregexp.html">QRegExp</a></p></td><td class="tblDescr"><p>Pattern matching using regular expressions</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qregion.html">QRegion</a></p></td><td class="tblDescr"><p>Specifies a clip region for a painter</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qset.html">QSet</a></p></td><td class="tblDescr"><p>Template class that provides a hash-table-based set</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qsqlfield.html">QSqlField</a></p></td><td class="tblDescr"><p>Manipulates the fields in SQL database tables and views</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qsqlquery.html">QSqlQuery</a></p></td><td class="tblDescr"><p>Means of executing and manipulating SQL statements</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qsqlrecord.html">QSqlRecord</a></p></td><td class="tblDescr"><p>Encapsulates a database record</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qstack.html">QStack</a></p></td><td class="tblDescr"><p>Template class that provides a stack</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qstring.html">QString</a></p></td><td class="tblDescr"><p>Unicode character string</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qstringlist.html">QStringList</a></p></td><td class="tblDescr"><p>List of strings</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qtextboundaryfinder.html">QTextBoundaryFinder</a></p></td><td class="tblDescr"><p>Way of finding Unicode text boundaries in a string</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qtextcursor.html">QTextCursor</a></p></td><td class="tblDescr"><p>Offers an API to access and modify QTextDocuments</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qtextdocumentfragment.html">QTextDocumentFragment</a></p></td><td class="tblDescr"><p>Represents a piece of formatted text from a QTextDocument</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qtextformat.html">QTextFormat</a></p></td><td class="tblDescr"><p>Formatting information for a QTextDocument</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qurl.html">QUrl</a></p></td><td class="tblDescr"><p>Convenient interface for working with URLs</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qvariant.html">QVariant</a></p></td><td class="tblDescr"><p>Acts like a union for the most common Qt data types</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qvector.html">QVector</a></p></td><td class="tblDescr"><p>Template class that provides a dynamic array</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qx11info.html">QX11Info</a></p></td><td class="tblDescr"><p>Information about the X display configuration</p></td></tr>
</table>
</div>
<!-- @@@implicit-sharing.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
