src/corelib/tools/qshareddata.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtCore module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Lesser General Public License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include <qshareddata.h>
  43
  44 QT_BEGIN_NAMESPACE
  45
  46 /*!
  47     \class QSharedData
  48     \inmodule QtCore
  49     \brief The QSharedData class is a base class for shared data objects.
  50     \reentrant
  51
  52     QSharedData is designed to be used with QSharedDataPointer or
  53     QExplicitlySharedDataPointer to implement custom \l{implicitly
  54     shared} or explicitly shared classes. QSharedData provides
  55     \l{thread-safe} reference counting.
  56
  57     See QSharedDataPointer and QExplicitlySharedDataPointer for details.
  58 */
  59
  60 /*! \fn QSharedData::QSharedData()
  61     Constructs a QSharedData object with a reference count of 0.
  62 */
  63
  64 /*! \fn QSharedData::QSharedData(const QSharedData& other)
  65     Constructs a QSharedData object with reference count 0.
  66     \a other is ignored.
  67 */
  68
  69 /*!
  70     \class QSharedDataPointer
  71     \inmodule QtCore
  72     \brief The QSharedDataPointer class represents a pointer to an implicitly shared object.
  73     \since 4.0
  74     \reentrant
  75
  76     QSharedDataPointer\<T\> makes writing your own \l {implicitly
  77     shared} classes easy. QSharedDataPointer implements \l {thread-safe}
  78     reference counting, ensuring that adding QSharedDataPointers to your
  79     \l {reentrant} classes won't make them non-reentrant.
  80
  81     \l {Implicit sharing} is used by many Qt classes to combine the
  82     speed and memory efficiency of pointers with the ease of use of
  83     classes. See the \l{Shared Classes} page for more information.
  84
  85     \target Employee example
  86     Suppose you want to make an \c Employee class implicitly shared. The
  87     procedure is:
  88
  89     \list
  90
  91     \li Define the class \c Employee to have a single data member of
  92      type \c {QSharedDataPointer<EmployeeData>}.
  93
  94     \li Define the \c EmployeeData class derived from \l QSharedData to
  95      contain all the data members you would normally have put in the
  96      \c Employee class.
  97
  98     \endlist
  99
 100     To show this in practice, we review the source code for the
 101     implicitly shared \c Employee class. In the header file we define the
 102     two classes \c Employee and \c EmployeeData.
 103
 104     \snippet sharedemployee/employee.h 0
 105
 106     In class \c Employee, note the single data member, a \e {d pointer}
 107     of type \c {QSharedDataPointer<EmployeeData>}. All accesses of
 108     employee data must go through the \e {d pointer's} \c
 109     {operator->()}.  For write accesses, \c {operator->()} will
 110     automatically call detach(), which creates a copy of the shared data
 111     object if the shared data object's reference count is greater than
 112     1. This ensures that writes to one \c Employee object don't affect
 113     any other \c Employee objects that share the same \c EmployeeData
 114     object.
 115
 116     Class \c EmployeeData inherits QSharedData, which provides the
 117     \e{behind the scenes} reference counter. \c EmployeeData has a default
 118     constructor, a copy constructor, and a destructor. Normally, trivial
 119     implementations of these are all that is needed in the \e {data}
 120     class for an implicitly shared class.
 121
 122     Implementing the two constructors for class \c Employee is also
 123     straightforward. Both create a new instance of \c EmployeeData
 124     and assign it to the \e{d pointer} .
 125
 126     \snippet sharedemployee/employee.h 1
 127     \codeline
 128     \snippet sharedemployee/employee.h 2
 129
 130     Note that class \c Employee also has a trivial copy constructor
 131     defined, which is not strictly required in this case.
 132
 133     \snippet sharedemployee/employee.h 7
 134
 135     The copy constructor is not strictly required here, because class \c
 136     EmployeeData is included in the same file as class \c Employee
 137     (\c{employee.h}). However, including the private subclass of
 138     QSharedData in the same file as the public class containing the
 139     QSharedDataPointer is not typical. Normally, the idea is to hide the
 140     private subclass of QSharedData from the user by putting it in a
 141     separate file which would not be included in the public file. In
 142     this case, we would normally put class \c EmployeeData in a separate
 143     file, which would \e{not} be included in \c{employee.h}. Instead, we
 144     would just predeclare the private subclass \c EmployeeData in \c
 145     {employee.h} this way:
 146
 147     \code
 148     class EmployeeData;
 149     \endcode
 150
 151     If we had done it that way here, the copy constructor shown would be
 152     required. Since the copy constructor is trivial, you might as well
 153     just always include it.
 154
 155     Behind the scenes, QSharedDataPointer automatically increments the
 156     reference count whenever an \c Employee object is copied, assigned,
 157     or passed as a parameter. It decrements the reference count whenever
 158     an \c Employee object is deleted or goes out of scope.  The shared
 159     \c EmployeeData object is deleted automatically if and when the
 160     reference count reaches 0.
 161
 162     In a non-const member function of \c Employee, whenever the \e {d
 163     pointer} is dereferenced, QSharedDataPointer automatically calls
 164     detach() to ensure that the function operates on its own copy of the
 165     data.
 166
 167     \snippet sharedemployee/employee.h 3
 168     \codeline
 169     \snippet sharedemployee/employee.h 4
 170
 171     Note that if detach() is called more than once in a member function
 172     due to multiple dereferences of the \e {d pointer}, detach() will
 173     only create a copy of the shared data the first time it is called,
 174     if at all, because on the second and subsequent calls of detach(),
 175     the reference count will be 1 again.
 176
 177     But note that in the second \c Employee constructor, which takes an
 178     employee ID and a name, both setId() and setName() are called, but
 179     they don't cause \e{copy on write}, because the reference count for
 180     the newly constructed \c EmployeeData object has just been set to 1.
 181
 182     In \c Employee's \e const member functions, dereferencing the \e {d
 183     pointer} does \e not cause detach() to be called.
 184
 185     \snippet sharedemployee/employee.h 5
 186     \codeline
 187     \snippet sharedemployee/employee.h 6
 188
 189     Notice that there is no need to implement a copy constructor or an
 190     assignment operator for the \c Employee class, because the copy
 191     constructor and assignment operator provided by the C++ compiler
 192     will do the \e{member by member} shallow copy required. The only
 193     member to copy is the \e {d pointer}, which is a QSharedDataPointer,
 194     whose \c {operator=()} just increments the reference count of the
 195     shared \c EmployeeData object.
 196
 197     \target Implicit vs Explicit Sharing
 198     \section1 Implicit vs Explicit Sharing
 199
 200     Implicit sharing might not be right for the \c Employee class.
 201     Consider a simple example that creates two instances of the
 202     implicitly shared \c Employee class.
 203
 204     \snippet sharedemployee/main.cpp 0
 205
 206     After the second employee e2 is created and e1 is assigned to it,
 207     both \c e1 and \c e2 refer to Albrecht Durer, employee 1001. Both \c
 208     Employee objects point to the same instance of \c EmployeeData,
 209     which has reference count 2. Then \c {e1.setName("Hans Holbein")} is
 210     called to change the employee name, but because the reference count
 211     is greater than 1, a \e{copy on write} is performed before the name
 212     is changed. Now \c e1 and \c e2 point to different \c EmployeeData
 213     objects. They have different names, but both have ID 1001, which is
 214     probably not what you want. You can, of course, just continue with
 215     \c {e1.setId(1002)}, if you really mean to create a second, unique
 216     employee, but if you only want to change the employee's name
 217     everywhere, consider using \l {QExplicitlySharedDataPointer}
 218     {explicit sharing} in the \c Employee class instead of implicit
 219     sharing.
 220
 221     If you declare the \e {d pointer} in the \c Employee class to be
 222     \c {QExplicitlySharedDataPointer<EmployeeData>}, then explicit
 223     sharing is used and \e{copy on write} operations are not performed
 224     automatically (i.e. detach() is not called in non-const
 225     functions). In that case, after \c {e1.setName("Hans Holbein")}, the
 226     employee's name has been changed, but both e1 and e2 still refer to
 227     the same instance of \c EmployeeData, so there is only one employee
 228     with ID 1001.
 229
 230     In the member function documentation, \e{d pointer} always refers
 231     to the internal pointer to the shared data object.
 232
 233     \section1 Optimize performance for usage in Qt Containers
 234
 235     You should consider marking your implicitly shared class as a movable type
 236     using the Q_DECLARE_TYPEINFO() macro if it resembles the \c Employee class
 237     above and uses a QSharedDataPointer or QExplicitlySharedDataPointer as the
 238     only member. This can improve performance and memory efficiency when using
 239     Qt's \l{container classes}.
 240
 241     \sa QSharedData, QExplicitlySharedDataPointer, QScopedPointer, QSharedPointer
 242 */
 243
 244 /*! \typedef QSharedDataPointer::Type
 245     This is the type of the shared data object. The \e{d pointer}
 246     points to an object of this type.
 247  */
 248
 249 /*! \typedef QSharedDataPointer::pointer
 250   \internal
 251  */
 252
 253 /*! \fn T& QSharedDataPointer::operator*()
 254     Provides access to the shared data object's members.
 255     This function calls detach().
 256 */
 257
 258 /*! \fn const T& QSharedDataPointer::operator*() const
 259     Provides const access to the shared data object's members.
 260     This function does \e not call detach().
 261 */
 262
 263 /*! \fn T* QSharedDataPointer::operator->()
 264     Provides access to the shared data object's members.
 265     This function calls detach().
 266 */
 267
 268 /*! \fn const T* QSharedDataPointer::operator->() const
 269     Provides const access to the shared data object's members.
 270     This function does \e not call detach().
 271 */
 272
 273 /*! \fn QSharedDataPointer::operator T*()
 274     Returns a pointer to the shared data object.
 275     This function calls detach().
 276
 277     \sa data(), constData()
 278 */
 279
 280 /*! \fn QSharedDataPointer::operator const T*() const
 281     Returns a pointer to the shared data object.
 282     This function does \e not call detach().
 283 */
 284
 285 /*! \fn T* QSharedDataPointer::data()
 286     Returns a pointer to the shared data object.
 287     This function calls detach().
 288
 289     \sa constData()
 290 */
 291
 292 /*! \fn const T* QSharedDataPointer::data() const
 293     Returns a pointer to the shared data object.
 294     This function does \e not call detach().
 295 */
 296
 297 /*! \fn const T* QSharedDataPointer::constData() const
 298     Returns a const pointer to the shared data object.
 299     This function does \e not call detach().
 300
 301     \sa data()
 302 */
 303
 304 /*! \fn void QSharedDataPointer::swap(QSharedDataPointer &other)
 305   Swap this instance's shared data pointer with the shared
 306   data pointer in \a other.
 307  */
 308
 309 /*! \fn bool QSharedDataPointer::operator==(const QSharedDataPointer<T>& other) const
 310     Returns true if \a other and \e this have the same \e{d pointer}.
 311     This function does \e not call detach().
 312 */
 313
 314 /*! \fn bool QSharedDataPointer::operator!=(const QSharedDataPointer<T>& other) const
 315     Returns true if \a other and \e this do \e not have the same
 316     \e{d pointer}. This function does \e not call detach().
 317 */
 318
 319 /*! \fn QSharedDataPointer::QSharedDataPointer()
 320     Constructs a QSharedDataPointer initialized with a null \e{d pointer}.
 321 */
 322
 323 /*! \fn QSharedDataPointer::~QSharedDataPointer()
 324     Decrements the reference count of the shared data object.
 325     If the reference count becomes 0, the shared data object
 326     is deleted. \e This is then destroyed.
 327 */
 328
 329 /*! \fn QSharedDataPointer::QSharedDataPointer(T* sharedData)
 330     Constructs a QSharedDataPointer with \e{d pointer} set to
 331     \a sharedData and increments \a{sharedData}'s reference count.
 332 */
 333
 334 /*! \fn QSharedDataPointer::QSharedDataPointer(const QSharedDataPointer<T>& other)
 335     Sets the \e{d pointer} of \e this to the \e{d pointer} in
 336     \a other and increments the reference count of the shared
 337     data object.
 338 */
 339
 340 /*! \fn QSharedDataPointer<T>& QSharedDataPointer::operator=(const QSharedDataPointer<T>& other)
 341     Sets the \e{d pointer} of \e this to the \e{d pointer} of
 342     \a other and increments the reference count of the shared
 343     data object. The reference count of the old shared data
 344     object of \e this is decremented.  If the reference count
 345     of the old shared data object becomes 0, the old shared
 346     data object is deleted.
 347 */
 348
 349 /*! \fn QSharedDataPointer& QSharedDataPointer::operator=(T* sharedData)
 350     Sets the \e{d pointer} og \e this to \a sharedData and increments
 351     \a{sharedData}'s reference count. The reference count of the old
 352     shared data object of \e this is decremented.  If the reference
 353     count of the old shared data object becomes 0, the old shared data
 354     object is deleted.
 355 */
 356
 357 /*! \fn bool QSharedDataPointer::operator!() const
 358     Returns true if the \e{d pointer} of \e this is null.
 359 */
 360
 361 /*! \fn void QSharedDataPointer::detach()
 362     If the shared data object's reference count is greater than 1, this
 363     function creates a deep copy of the shared data object and sets the
 364     \e{d pointer} of \e this to the copy.
 365
 366     This function is called automatically by non-const member
 367     functions of QSharedDataPointer if \e{copy on write} is
 368     required. You don't need to call it yourself.
 369 */
 370
 371 /*! \fn T *QSharedDataPointer::clone()
 372     \since 4.5
 373
 374     Creates and returns a deep copy of the current data. This function
 375     is called by detach() when the reference count is greater than 1 in
 376     order to create the new copy. This function uses the \e {operator
 377     new} and calls the copy constructor of the type T.
 378
 379     This function is provided so that you may support "virtual copy
 380     constructors" for your own types. In order to so, you should declare
 381     a template-specialization of this function for your own type, like
 382     the example below:
 383
 384     \code
 385       template<>
 386       EmployeeData *QSharedDataPointer<EmployeeData>::clone()
 387       {
 388           return d->clone();
 389       }
 390     \endcode
 391
 392     In the example above, the template specialization for the clone()
 393     function calls the \e {EmployeeData::clone()} virtual function. A
 394     class derived from EmployeeData could override that function and
 395     return the proper polymorphic type.
 396 */
 397
 398 /*!
 399     \class QExplicitlySharedDataPointer
 400     \inmodule QtCore
 401     \brief The QExplicitlySharedDataPointer class represents a pointer to an explicitly shared object.
 402     \since 4.4
 403     \reentrant
 404
 405     QExplicitlySharedDataPointer\<T\> makes writing your own explicitly
 406     shared classes easy. QExplicitlySharedDataPointer implements
 407     \l {thread-safe} reference counting, ensuring that adding
 408     QExplicitlySharedDataPointers to your \l {reentrant} classes won't
 409     make them non-reentrant.
 410
 411     Except for one big difference, QExplicitlySharedDataPointer is just
 412     like QSharedDataPointer. The big difference is that member functions
 413     of QExplicitlySharedDataPointer \e{do not} do the automatic
 414     \e{copy on write} operation (detach()) that non-const members of
 415     QSharedDataPointer do before allowing the shared data object to be
 416     modified. There is a detach() function available, but if you really
 417     want to detach(), you have to call it yourself. This means that
 418     QExplicitlySharedDataPointers behave like regular C++ pointers,
 419     except that by doing reference counting and not deleting the shared
 420     data object until the reference count is 0, they avoid the dangling
 421     pointer problem.
 422
 423     It is instructive to compare QExplicitlySharedDataPointer with
 424     QSharedDataPointer by way of an example. Consider the \l {Employee
 425     example} in QSharedDataPointer, modified to use explicit sharing as
 426     explained in the discussion \l {Implicit vs Explicit Sharing}.
 427
 428     Note that if you use this class but find you are calling detach() a
 429     lot, you probably should be using QSharedDataPointer instead.
 430
 431     In the member function documentation, \e{d pointer} always refers
 432     to the internal pointer to the shared data object.
 433
 434     \sa QSharedData, QSharedDataPointer
 435 */
 436
 437 /*! \fn T& QExplicitlySharedDataPointer::operator*() const
 438     Provides access to the shared data object's members.
 439 */
 440
 441 /*! \fn T* QExplicitlySharedDataPointer::operator->()
 442     Provides access to the shared data object's members.
 443 */
 444
 445 /*! \fn const T* QExplicitlySharedDataPointer::operator->() const
 446     Provides const access to the shared data object's members.
 447 */
 448
 449 /*! \fn T* QExplicitlySharedDataPointer::data() const
 450     Returns a pointer to the shared data object.
 451 */
 452
 453 /*! \fn const T* QExplicitlySharedDataPointer::constData() const
 454     Returns a const pointer to the shared data object.
 455
 456     \sa data()
 457 */
 458
 459 /*! \fn void QExplicitlySharedDataPointer::swap(QExplicitlySharedDataPointer &other)
 460   Swap this instance's explicitly shared data pointer with
 461   the explicitly shared data pointer in \a other.
 462  */
 463
 464 /*! \fn bool QExplicitlySharedDataPointer::operator==(const QExplicitlySharedDataPointer<T>& other) const
 465     Returns true if \a other and \e this have the same \e{d pointer}.
 466 */
 467
 468 /*! \fn bool QExplicitlySharedDataPointer::operator==(const T* ptr) const
 469     Returns true if the \e{d pointer} of \e this is \a ptr.
 470  */
 471
 472 /*! \fn bool QExplicitlySharedDataPointer::operator!=(const QExplicitlySharedDataPointer<T>& other) const
 473     Returns true if \a other and \e this do \e not have the same
 474     \e{d pointer}.
 475 */
 476
 477 /*! \fn bool QExplicitlySharedDataPointer::operator!=(const T* ptr) const
 478     Returns true if the \e{d pointer} of \e this is \e not \a ptr.
 479  */
 480
 481 /*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer()
 482     Constructs a QExplicitlySharedDataPointer initialized with a null
 483     \e{d pointer}.
 484 */
 485
 486 /*! \fn QExplicitlySharedDataPointer::~QExplicitlySharedDataPointer()
 487     Decrements the reference count of the shared data object.
 488     If the reference count becomes 0, the shared data object
 489     is deleted. \e This is then destroyed.
 490 */
 491
 492 /*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer(T* sharedData)
 493     Constructs a QExplicitlySharedDataPointer with \e{d pointer}
 494     set to \a sharedData and increments \a{sharedData}'s reference
 495     count.
 496 */
 497
 498 /*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<T>& other)
 499     This standard copy constructor sets the \e {d pointer} of \e this to
 500     the \e {d pointer} in \a other and increments the reference count of
 501     the shared data object.
 502 */
 503
 504 /*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<X>& other)
 505     This copy constructor is different in that it allows \a other to be
 506     a different type of explicitly shared data pointer but one that has
 507     a compatible shared data object. It performs a static cast of the
 508     \e{d pointer} in \a other and sets the \e {d pointer} of \e this to
 509     the converted \e{d pointer}. It increments the reference count of
 510     the shared data object.
 511 */
 512
 513 /*! \fn QExplicitlySharedDataPointer<T>& QExplicitlySharedDataPointer::operator=(const QExplicitlySharedDataPointer<T>& other)
 514     Sets the \e{d pointer} of \e this to the \e{d pointer} of
 515     \a other and increments the reference count of the shared
 516     data object. The reference count of the old shared data
 517     object of \e this is decremented.  If the reference count
 518     of the old shared data object becomes 0, the old shared
 519     data object is deleted.
 520 */
 521
 522 /*! \fn QExplicitlySharedDataPointer& QExplicitlySharedDataPointer::operator=(T* sharedData)
 523     Sets the \e{d pointer} of \e this to \a sharedData and
 524     increments \a{sharedData}'s reference count. The reference
 525     count of the old shared data object of \e this is decremented.
 526     If the reference count of the old shared data object becomes
 527     0, the old shared data object is deleted.
 528 */
 529
 530 /*! \fn void QExplicitlySharedDataPointer::reset()
 531     Resets \e this to be null. i.e., this function sets the
 532     \e{d pointer} of \e this to 0, but first it decrements
 533     the reference count of the shared data object and deletes
 534     the shared data object if the reference count became 0.
 535  */
 536
 537 /*! \fn QExplicitlySharedDataPointer::operator bool () const
 538     Returns true if the \e{d pointer} of \e this is \e not null.
 539  */
 540
 541 /*! \fn bool QExplicitlySharedDataPointer::operator!() const
 542     Returns true if the \e{d pointer} of \e this is null.
 543 */
 544
 545 /*! \fn void QExplicitlySharedDataPointer::detach()
 546     If the shared data object's reference count is greater than 1, this
 547     function creates a deep copy of the shared data object and sets the
 548     \e{d pointer} of \e this to the copy.
 549
 550     Because QExplicitlySharedDataPointer does not do the automatic
 551     \e{copy on write} operations that members of QSharedDataPointer do,
 552     detach() is \e not called automatically anywhere in the member
 553     functions of this class. If you find that you are calling detach()
 554     everywhere in your code, consider using QSharedDataPointer instead.
 555 */
 556
 557 /*! \fn T *QExplicitlySharedDataPointer::clone()
 558     \since 4.5
 559
 560     Creates and returns a deep copy of the current data. This function
 561     is called by detach() when the reference count is greater than 1 in
 562     order to create the new copy. This function uses the \e {operator
 563     new} and calls the copy constructor of the type T.
 564
 565     See QSharedDataPointer::clone() for an explanation of how to use it.
 566 */
 567
 568 /*!
 569     \typedef QExplicitlySharedDataPointer::Type
 570
 571     This is the type of the shared data object. The \e{d pointer}
 572     points to an object of this type.
 573 */
 574
 575 /*! \typedef QExplicitlySharedDataPointer::pointer
 576   \internal
 577  */
 578
 579 QT_END_NAMESPACE