summaryrefslogtreecommitdiffstats
path: root/doc/src/core/implicit-sharing.qdoc
diff options
context:
space:
mode:
authorLars Knoll <lars.knoll@nokia.com>2012-01-18 09:51:03 +0100
committerQt by Nokia <qt-info@nokia.com>2012-01-19 10:07:34 +0100
commit2a742eba7a9be98354dc0e60c3644db484fe09db (patch)
tree0dfd4d3c31dd930c2f9463b43437f81088e0c245 /doc/src/core/implicit-sharing.qdoc
parent57738689cd51af2111c35bffa769efbcd3ed5c97 (diff)
core as a directory name is usually not a good idea
Let's follow the other places in qtbase where the directory is named corelib. Change-Id: Ib426f4ee7311f622a89b252b9915aca1d3dd688d Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com> Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Diffstat (limited to 'doc/src/core/implicit-sharing.qdoc')
-rw-r--r--doc/src/core/implicit-sharing.qdoc138
1 files changed, 0 insertions, 138 deletions
diff --git a/doc/src/core/implicit-sharing.qdoc b/doc/src/core/implicit-sharing.qdoc
deleted file mode 100644
index e745d127d5..0000000000
--- a/doc/src/core/implicit-sharing.qdoc
+++ /dev/null
@@ -1,138 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
-** All rights reserved.
-** Contact: Nokia Corporation (qt-info@nokia.com)
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** GNU Free Documentation License
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file.
-**
-** Other Usage
-** Alternatively, this file may be used in accordance with the terms
-** and conditions contained in a signed written agreement between you
-** and Nokia.
-**
-**
-**
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/* TODO: Move some of the documentation from QSharedDataPointer into this
- document. */
-
-/*!
- \group shared
- \title Implicitly Shared Classes
-*/
-
-/*!
- \page implicit-sharing.html
- \title Implicit Sharing
- \ingroup qt-basic-concepts
-
- \brief Reference counting for fast copying.
-
- \keyword implicit data sharing
- \keyword implicit sharing
- \keyword implicitly shared
- \keyword reference counting
- \keyword shared implicitly
- \keyword shared classes
-
- 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., \e {copy-on-write}.
-
- \tableofcontents
-
- \section1 Overview
-
- A shared class consists of a pointer to a shared data block that
- contains a reference count and the data.
-
- 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.
-
- \keyword deep copy
- \keyword shallow copy
-
- When dealing with shared objects, there are two ways of copying an
- object. We usually speak about \e deep and \e shallow 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.
-
- Object assignment (with operator=()) for implicitly shared objects is
- implemented using shallow copies.
-
- 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.
-
- 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
- \l{Thread-Support in Qt Modules#Threads and Implicitly Shared Classes}
- {Threads and Implicitly Shared Classes}.
-
- When implementing your own implicitly shared classes, use the
- QSharedData and QSharedDataPointer classes.
-
- \section1 Implicit Sharing in Detail
-
- 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 \e {copy-on-write} or
- \e {value semantics}.)
-
- 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.
-
- The QPen class, which uses implicit sharing, detaches from the shared
- data in all member functions that change the internal data.
-
- Code fragment:
- \snippet doc/src/snippets/code/doc_src_groups.cpp 0
-
-
- \section1 List of Classes
-
- 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.
-
- Example:
- \snippet doc/src/snippets/code/doc_src_groups.cpp 1
-
- In this example, \c p1 and \c p2 share data until QPainter::begin()
- is called for \c p2, because painting a pixmap will modify it.
-
- \warning Do not copy an implicitly shared container (QMap,
- QVector, etc.) while you are iterating over it using an non-const
- \l{STL-style iterator}.
-
- \keyword implicitly shared classes
- \annotatedlist shared
-*/