QThread: add static create function

In the spirit of std::thread, which takes a function to call and its
parameters, and runs it in a new thread. Since the user might want to
connect to signals, move QObjects into the new thread, etc., the new
thread is not immediately started.

Although technically all of this _should_ be implementable in pure
C++11, there is nothing in the Standard to help us not reinvent all the
plumbing: packing the decay'd parameters, storing them, invoking the
function over the parameters (honoring INVOKE/std::invoke semantics).
std::function does not do the job, as it's copiable and therefore does
not support move-only functors; std::bind does not have INVOKE
semantics.

I certainly do not want to reimplement all the required facilities
inside of Qt. Therefore, the full blown implementation requires C++17
(std::invoke).

In order to make this useful also in pre-C++17, there are two additional
implementations (C++11 and C++14) that support just a callable, without
any arguments passed to it. The C++11 implementation makes use of a
class to store and call the callable (even move-only ones); basically,
it's what a closure type for a C++14 lambda would look like.

An alternative implementation could've used some of the existing
facilities inside QObject::connect implementation that store a functor
(for the connect() overload connecting to free functions), namely:
the QtPrivate::QFunctorSlotObject class. However:

* QFunctorSlotObject does not support move-only callables (see
QTBUG-60339);
* QFunctorSlotObject itself is not a callable (apparently by design),
and requires to be wrapped in a lambda that calls call() on it;
* the moment QTBUG-60339 is solved, we'd need the same handwritten
closure to keep QFunctorSlotObject working with move-only callabes.

So: just use the handwritten one.

The C++14 implementation is a simplified version of the C++11 one,
actually using a generalized lambda capture (corresponding to the
handwritten C++11 closure type).

All three implementations use std::async (with a deferred launch policy,
a nice use case for it!) under the hood. It's certainly an overkill for
our use case, as we don't need the std::future, but at least std::async
does all the plumbing for us.

[ChangeLog][QtCore][QThread] Added the QThread::create function.

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

2 files changed, 165 insertions, 0 deletions

diff --git a/src/corelib/thread/qthread.cpp b/src/corelib/thread/qthread.cpp
index 0828400733..c42e120978 100644
--- a/src/corelib/thread/qthread.cpp
+++ b/src/corelib/thread/qthread.cpp
@@ -880,6 +880,51 @@ bool QThread::isInterruptionRequested() const
     return d->interruptionRequested;
 }
 
+/*
+    \fn template <typename Function, typename Args...> static QThread *QThread::create(Function &&f, Args &&... args)
+    \since 5.10
+
+    Creates a new QThread object that will execute the function \a f with the
+    arguments \a args.
+
+    The new thread is not started -- it must be started by an explicit call
+    to start(). This allows you to connect to its signals, move QObjects
+    to the thread, choose the new thread's priority and so on. The function
+    \a f will be called in the new thread.
+
+    Returns the newly created QThread instance.
+
+    \note the caller acquires ownership of the returned QThread instance.
+
+    \note this function is only available when using C++17.
+
+    \warning do not call start() on the returned QThread instance more than once;
+    doing so will result in undefined behavior.
+
+    \sa start()
+*/
+
+/*
+    \fn template <typename Function> static QThread *QThread::create(Function &&f)
+    \since 5.10
+
+    Creates a new QThread object that will execute the function \a f.
+
+    The new thread is not started -- it must be started by an explicit call
+    to start(). This allows you to connect to its signals, move QObjects
+    to the thread, choose the new thread's priority and so on. The function
+    \a f will be called in the new thread.
+
+    Returns the newly created QThread instance.
+
+    \note the caller acquires ownership of the returned QThread instance.
+
+    \warning do not call start() on the returned QThread instance more than once;
+    doing so will result in undefined behavior.
+
+    \sa start()
+*/
+
 /*!
     \class QDaemonThread
     \since 5.5
diff --git a/src/corelib/thread/qthread.h b/src/corelib/thread/qthread.h
index 45786537e2..801bbfe02a 100644
--- a/src/corelib/thread/qthread.h
+++ b/src/corelib/thread/qthread.h
@@ -42,6 +42,23 @@
 
 #include <QtCore/qobject.h>
 
+// The implementation of QThread::create uses various C++14/C++17 facilities;
+// we must check for their presence. For std::async (used in all codepaths)
+// there is no SG10 feature macro; just test for the header presence.
+// For the C++17 codepath do some more throughout checks for std::invoke and
+// C++14 lambdas availability.
+#if QT_HAS_INCLUDE(<future>)
+#  define QTHREAD_HAS_CREATE
+#  include <future> // for std::async
+#  include <functional> // for std::invoke; no guard needed as it's a C++98 header
+
+#  if defined(__cpp_lib_invoke) && __cpp_lib_invoke >= 201411 \
+      && defined(__cpp_init_captures) && __cpp_init_captures >= 201304 \
+      && defined(__cpp_generic_lambdas) &&  __cpp_generic_lambdas >= 201304
+#    define QTHREAD_HAS_VARIADIC_CREATE
+#  endif
+#endif
+
 #include <limits.h>
 
 QT_BEGIN_NAMESPACE
@@ -98,6 +115,16 @@ public:
     bool event(QEvent *event) Q_DECL_OVERRIDE;
     int loopLevel() const;
 
+#ifdef QTHREAD_HAS_CREATE
+#ifdef QTHREAD_HAS_VARIADIC_CREATE
+    template <typename Function, typename... Args>
+    static QThread *create(Function &&f, Args &&... args);
+#else
+    template <typename Function>
+    static QThread *create(Function &&f);
+#endif
+#endif
+
 public Q_SLOTS:
     void start(Priority = InheritPriority);
     void terminate();
@@ -131,6 +158,99 @@ private:
     friend class QThreadData;
 };
 
+#ifdef QTHREAD_HAS_CREATE
+namespace QtPrivate {
+
+class QThreadCreateThread : public QThread
+{
+public:
+#if defined(QTHREAD_HAS_VARIADIC_CREATE)
+    // C++17: std::thread's constructor complying call
+    template <typename Function, typename... Args>
+    explicit QThreadCreateThread(Function &&f, Args &&... args)
+        : m_future(std::async(std::launch::deferred,
+                   [f = static_cast<typename std::decay<Function>::type>(std::forward<Function>(f))](auto &&... args) mutable -> void
+                   {
+                       (void)std::invoke(std::move(f), std::forward<decltype(args)>(args)...);
+                   }, std::forward<Args>(args)...))
+    {
+    }
+#elif defined(__cpp_init_captures) && __cpp_init_captures >= 201304
+    // C++14: implementation for just one callable
+    template <typename Function>
+    explicit QThreadCreateThread(Function &&f)
+        : m_future(std::async(std::launch::deferred,
+                   [f = static_cast<typename std::decay<Function>::type>(std::forward<Function>(f))]() mutable -> void
+                   {
+                       (void)f();
+                   }))
+    {
+    }
+#else
+private:
+    // C++11: same as C++14, but with a workaround for not having generalized lambda captures
+    template <typename Function>
+    struct Callable
+    {
+        explicit Callable(Function &&f)
+            : m_function(std::forward<Function>(f))
+        {
+        }
+
+#if defined(Q_COMPILER_DEFAULT_MEMBERS) && defined(Q_COMPILER_DELETE_MEMBERS)
+        // Apply the same semantics of a lambda closure type w.r.t. the special
+        // member functions, if possible: delete the copy assignment operator,
+        // bring back all the others as per the RO5 (cf. §8.1.5.1/11 [expr.prim.lambda.closure])
+        ~Callable() = default;
+        Callable(const Callable &) = default;
+        Callable(Callable &&) = default;
+        Callable &operator=(const Callable &) = delete;
+        Callable &operator=(Callable &&) = default;
+#endif
+
+        void operator()()
+        {
+            (void)m_function();
+        }
+
+        typename std::decay<Function>::type m_function;
+    };
+
+public:
+    template <typename Function>
+    explicit QThreadCreateThread(Function &&f)
+        : m_future(std::async(std::launch::deferred, Callable<Function>(std::forward<Function>(f))))
+    {
+    }
+#endif // QTHREAD_HAS_VARIADIC_CREATE
+
+private:
+    void run() override
+    {
+        m_future.get();
+    }
+
+    std::future<void> m_future;
+};
+
+} // namespace QtPrivate
+
+#ifdef QTHREAD_HAS_VARIADIC_CREATE
+template <typename Function, typename... Args>
+QThread *QThread::create(Function &&f, Args &&... args)
+{
+    return new QtPrivate::QThreadCreateThread(std::forward<Function>(f), std::forward<Args>(args)...);
+}
+#else
+template <typename Function>
+QThread *QThread::create(Function &&f)
+{
+    return new QtPrivate::QThreadCreateThread(std::forward<Function>(f));
+}
+#endif // QTHREAD_HAS_VARIADIC_CREATE
+
+#endif // QTHREAD_HAS_CREATE
+
 #else // QT_NO_THREAD
 
 class Q_CORE_EXPORT QThread : public QObject