| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** 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. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page atomic-operations.html |
| \title Implementing Atomic Operations |
| \brief A guide to implementing atomic operations on new architectures. |
| |
| \ingroup best-practices |
| \ingroup qt-embedded-linux |
| |
| Qt uses an optimization called \l {Implicitly Shared |
| Classes}{implicit sharing} for many of its value classes. |
| |
| Starting with Qt 4, all of Qt's implicitly shared classes can |
| safely be copied across threads like any other value classes, |
| i.e., they are fully \l {Reentrancy and Thread-Safety}{reentrant}. |
| This is accomplished by implementing reference counting |
| operations using atomic hardware instructions on all the |
| different platforms supported by Qt. |
| |
| To support a new architecture, it is important to ensure that |
| these platform-specific atomic operations are implemented in a |
| corresponding header file (\c qatomic_ARCH.h), and that this file |
| is located in Qt's \c src/corelib/arch directory. For example, the |
| Intel 80386 implementation is located in \c |
| src/corelib/arch/qatomic_i386.h. |
| |
| Currently, Qt provides two classes providing several atomic |
| operations, QAtomicInt and QAtomicPointer. These classes inherit |
| from QBasicAtomicInt and QBasicAtomicPointer, respectively. |
| |
| When porting Qt to a new architecture, the QBasicAtomicInt and |
| QBasicAtomicPointer classes must be implemented, \e not QAtomicInt |
| and QAtomicPointer. The former classes do not have constructors, |
| which makes them POD (plain-old-data). Both classes only have a |
| single member variable called \c _q_value, which stores the |
| value. This is the value that all of the atomic operations read |
| and modify. |
| |
| All of the member functions mentioned in the QAtomicInt and |
| QAtomicPointer API documentation must be implemented. Note that |
| these the implementations of the atomic operations in these |
| classes must be atomic with respect to both interrupts and |
| multiple processors. |
| |
| \warning The QBasicAtomicInt and QBasicAtomicPointer classes |
| mentioned in this document are used internally by Qt and are not |
| part of the public API. They may change in future versions of |
| Qt. The purpose of this document is to aid people interested in |
| porting Qt to a new architecture. |
| */ |