Short live qt_unique_lock/qt_scoped_lock! (until C++17)

Now that QRecursiveMutex is getting split off of QMutex, QMutexLocker
will stop working on QRecursiveMutex once the split has been finalized
in Qt 6.

Even today, QMutexLocker contains casts from QBasicMutex to QMutex
that some reviewers are uncomfortable with. One way to carry
QMutexLocker forward is to template it on the mutex type, possibly
with aliases like QBasicMutexLocker and QRecursiveMutexLocker. C++17
code would then not require a port, thanks to CTAD.

But we have the problem now, and we can't template QMutexLocker in Qt 5.

The alternative is to look at std and realize that they have surpassed
QMutexLocker in expressiveness already. A scoped_lock cannot be
unlocked again, a unique_lock can be moved around. QMutexLocker
doesn't do either. The only "problem" is that the std lock classes are
already templates, but we can't, yet, rely on C++17 CTAD to make them
look as if they weren't.

So, prepare for a future with C++17 CTAD by writing factory functions,
qt_scoped_lock and qt_unique_lock, which will later port mechanically
to their C++17 equivalents (mostly).

The functions are added to a new private qlocking_p.h becauee we don't
want to make them public. These are for use in Qt's own implementation,
or for users that don't care about compatibility and will not mind them
to be removed once we depend on C++17. Originally, I planned to use
qmutex_p.h instead, but that header is not self-contained and causes
build errors when we started to include it into libraries other than
QtCore.

Regarding the return value of qt_scoped_lock: Ideally, we'd like to
return a std::scoped_lock, but two things stand in the way: First,
scoped_lock was only added in C++17 (we fall back to lock_guard if
scoped_lock is not available). Second, returning one from a function
requires C++17 guaranteed copy elision, because neither scoped_lock
not lock_guard have a copy ctor. In order for code not to come to
depend on a particular lock class, we return any of lock_guard,
unique_lock or scoped_guard, depending on what the compiler supports,
and therefore wrap the functions in the unnamed namespace to avoid
running into ODR if (private) headers are used from different projects
(autotests, e.g.). By the time we can drop them, however, qt_*_lock
will be semantically 100% identical to their replacements.

Port some initial users.

Change-Id: I2a208ef2a4a533ee8e675812273986460e6b4d00
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

2 files changed, 120 insertions, 0 deletions

diff --git a/src/corelib/thread/qlocking_p.h b/src/corelib/thread/qlocking_p.h
new file mode 100644
index 0000000000..9a796cf7f7
--- /dev/null
+++ b/src/corelib/thread/qlocking_p.h
@@ -0,0 +1,119 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com>
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtCore module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QLOCKING_P_H
+#define QLOCKING_P_H
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is not part of the Qt API.  It exists for the convenience
+// of qmutex.cpp, qmutex_unix.cpp, and qmutex_win.cpp.  This header
+// file may change from version to version without notice, or even be
+// removed.
+//
+// We mean it.
+//
+
+#include <QtCore/qmutex.h>
+
+#include <mutex>
+
+QT_BEGIN_NAMESPACE
+
+//
+// This API is bridging the time until we can depend on C++17:
+//
+// - qt_scoped_lock returns a lock that cannot be unlocked again before the end of the scope
+// - qt_unique_lock returns a lock that can be unlock()ed and moved around
+// - for compat with QMutexLocker, qt_unique_lock supports passing by pointer.
+//   Do NOT use this overload lightly; it's only for cases such as where a Q_GLOBAL_STATIC
+//   may have already been deleted. In particular, do NOT port from
+//       QMutexLocker locker(&mutex);
+//   to
+//       auto locker = qt_unique_lock(&mutex);
+//   as this will not port automatically to std::unique_lock come C++17!
+//
+// The intent, come C++17, is to replace
+//     qt_scoped_lock(mutex);
+//     qt_unique_lock(mutex); // except qt_unique_lock(&mutex)
+// with
+//     std::scoped_lock(mutex);
+//     std::unique_lock(mutex);
+// resp. (C++17 meaning CTAD, guaranteed copy elision + scoped_lock available on all platforms),
+// so please use these functions only in ways which don't break this mechanical search & replace.
+//
+
+namespace {
+
+template <typename Mutex, typename Lock =
+#if defined(__cpp_guaranteed_copy_elision) && __cpp_guaranteed_copy_elision >= 201606L
+# if defined(__cpp_lib_scoped_lock) && __cpp_lib_scoped_lock >= 201703L
+          std::scoped_lock
+# else
+          std::lock_guard
+# endif
+#else
+          std::unique_lock
+#endif
+          <typename std::decay<Mutex>::type>
+>
+Lock qt_scoped_lock(Mutex &mutex)
+{
+    return Lock(mutex);
+}
+
+template <typename Mutex, typename Lock = std::unique_lock<typename std::decay<Mutex>::type>>
+Lock qt_unique_lock(Mutex &mutex)
+{
+    return Lock(mutex);
+}
+
+template <typename Mutex, typename Lock = std::unique_lock<typename std::decay<Mutex>::type>>
+Lock qt_unique_lock(Mutex *mutex)
+{
+    return mutex ? Lock(*mutex) : Lock() ;
+}
+
+} // unnamed namespace
+
+QT_END_NAMESPACE
+
+#endif // QLOCKING_P_H
diff --git a/src/corelib/thread/thread.pri b/src/corelib/thread/thread.pri
index d11e6500ff..9fc9af0e65 100644
--- a/src/corelib/thread/thread.pri
+++ b/src/corelib/thread/thread.pri
@@ -28,6 +28,7 @@ qtConfig(thread) {
         thread/qbasicatomic.h \
         thread/qfutex_p.h \
         thread/qgenericatomic.h \
+        thread/qlocking_p.h \
         thread/qmutex_p.h \
         thread/qorderedmutexlocker_p.h \
         thread/qreadwritelock_p.h \