1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the Qt3Support module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "q3deepcopy.h"

    43 

    44 QT_BEGIN_NAMESPACE

    45 

    46 /*!

    47     \class Q3DeepCopy

    48     \brief The Q3DeepCopy class is a template class which ensures that

    49     implicitly shared and explicitly shared classes reference unique

    50     data.

    51 

    52     \reentrant

    53 

    54     \compat

    55 

    56     Normally, shared copies reference the same data to optimize memory

    57     use and for maximum speed. In the example below, \c s1, \c s2, \c

    58     s3, \c s4 and \c s5 share data.

    59 

    60     \snippet doc/src/snippets/code/src_qt3support_tools_q3deepcopy.cpp 0

    61 

    62     Q3DeepCopy can be used several ways to ensure that an object

    63     references unique, unshared data. In the example below, \c s1, \c

    64     s2 and \c s5 share data, while neither \c s3 nor \c s4 share data.

    65     \snippet doc/src/snippets/code/src_qt3support_tools_q3deepcopy.cpp 1

    66 

    67     In the example below, \c s1, \c s2 and \c s5 share data, and \c s3

    68     and \c s4 share data.

    69     \snippet doc/src/snippets/code/src_qt3support_tools_q3deepcopy.cpp 2

    70 

    71     Q3DeepCopy can also provide safety in multithreaded applications

    72     that use shared classes. In the example below, the variable \c

    73     global_string is used safely since the data contained in \c

    74     global_string is always a deep copy. This ensures that all threads

    75     get a unique copy of the data, and that any assignments to \c

    76     global_string will result in a deep copy.

    77 

    78     \snippet doc/src/snippets/code/src_qt3support_tools_q3deepcopy.cpp 3

    79 

    80     \warning It is the application developer's responsibility to

    81     protect the object shared across multiple threads.

    82 

    83     The examples above use QString, which is an implicitly shared

    84     class. The behavior of Q3DeepCopy is the same when using explicitly

    85     shared classes like QByteArray.

    86 

    87     Currently, Q3DeepCopy works with the following classes:

    88     \list

    89     \i QMemArray (including subclasses like QByteArray and QCString)

    90     \i QMap

    91     \i QString

    92     \i QValueList (including subclasses like QStringList and QValueStack)

    93     \i QValueVector

    94     \endlist

    95 

    96     \sa \link threads.html Thread Support in Qt \endlink

    97 */

    98 

    99 /*!

   100     \fn Q3DeepCopy::Q3DeepCopy()

   101 

   102     Constructs an empty instance of type \e T.

   103 */

   104 

   105 /*!

   106     \fn Q3DeepCopy::Q3DeepCopy( const T &t )

   107 

   108     Constructs a deep copy of \a t.

   109 */

   110 

   111 /*!

   112     \fn Q3DeepCopy<T>& Q3DeepCopy::operator=( const T &t )

   113 

   114     Assigns a deep copy of \a t.

   115 */

   116 

   117 /*!

   118     \fn Q3DeepCopy::operator T ()

   119 

   120     Returns a deep copy of the encapsulated data.

   121 */

   122 

   123 QT_END_NAMESPACE