src/corelib/tools/qshareddata.cpp

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