Revision control
++ // Copyright (C) 2025 Jarek Kobus
++ // Copyright (C) 2025 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
++ // Qt-Security score:significant reason:default
++
++
++ #include <QtTaskTree/qtasktreerunner.h>
++
++ #include <QtTaskTree/qtasktree.h>
++
++ #include <QtCore/private/qobject_p.h>
++
++ QT_BEGIN_NAMESPACE
++
++ namespace QtTaskTree {
++
++ /*!
++ \typealias QtTaskTree::TreeSetupHandler
++
++ Type alias for std::function<void(QTaskTree &)>.
++
++ The \c TreeSetupHandler is an optional argument of
++ task tree runners' functions scheduling the task tree execution.
++ The function is called when the task tree runner is about
++ to execute it's recipe. The access to the QTaskTree is via
++ the passed argument.
++
++ The task tree runners accept also handlers in a shortened form
++ of \c std::function<void(void)>.
++ */
++
++ /*!
++ \typealias QtTaskTree::TreeDoneHandler
++
++ Type alias for std::function<void(const QTaskTree &, QtTaskTree::DoneWith)>.
++
++ The \c TreeDoneHandler is an optional argument of
++ task tree runners' functions scheduling the task tree execution.
++ The function is called when the task tree runner's recipe
++ finished the execution. The access to the QTaskTree and recipe's
++ result is via the passed arguments.
++
++ The task tree runners accept also handlers in a shortened form of
++ \c std::function<void(const QTaskTree &)>,
++ \c std::function<void(QtTaskTree::DoneWith)>, or
++ \c std::function<void(void)>.
++ */
++
++ class QSingleTaskTreeRunnerPrivate
++ {
++ public:
++ std::unique_ptr<QTaskTree> m_taskTree;
++ };
++
++ /*!
++ \class QtTaskTree::QSingleTaskTreeRunner
++ \inheaderfile qtasktreerunner.h
++ \inmodule QtTaskTree
++ \brief A single task tree execution controller.
++
++ Manages single task tree execution.
++ Use the start() method to execute a given recipe,
++ resetting any possibly running task tree.
++ It's guaranteed that at most one task tree is executing at any given time.
++
++ \sa {Task Tree Runners}
++ */
++
++ /*!
++ Constructs a single task tree runner.
++ */
++ QSingleTaskTreeRunner::QSingleTaskTreeRunner() : d_ptr(new QSingleTaskTreeRunnerPrivate) {}
++
++ /*!
++ Destroys the single task tree runner. A possibly running
++ task tree is deleted. No task tree's done handler is called.
++
++ \sa {QTaskTree::~QTaskTree()} {~QTaskTree()}
++ */
++ QSingleTaskTreeRunner::~QSingleTaskTreeRunner() = default;
++
++ /*!
++ Returns whether the single task tree runner is currently
++ executing a task tree.
++ */
++ bool QSingleTaskTreeRunner::isRunning() const { return bool(d_func()->m_taskTree); }
++
++ /*!
++ Cancels the running task tree. Calls task tree' done
++ handler with \l {QtTaskTree::} {DoneWith::Cancel}.
++ */
++ void QSingleTaskTreeRunner::cancel()
++ {
++ if (d_func()->m_taskTree)
++ d_func()->m_taskTree->cancel();
++ }
++
++ /*!
++ Resets the running task tree. No task tree's done handler is called.
++ */
++ void QSingleTaskTreeRunner::reset()
++ {
++ d_func()->m_taskTree.reset();
++ }
++
++ /*!
++ \fn template <typename SetupHandler = TreeSetupHandler, typename DoneHandler = TreeDoneHandler> void QSingleTaskTreeRunner::start(const QtTaskTree::Group &recipe, SetupHandler &&setupHandler = {}, DoneHandler &&doneHandler = {}, QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)
++
++ Starts the \a recipe unconditionally, resetting any possibly
++ running task tree.
++ Calls \a setupHandler when new task tree is about to be started.
++ Calls \a doneHandler when the task tree is finished.
++ The \a doneHandler is called according to the passed \a callDone.
++ */
++
++ void QSingleTaskTreeRunner::startImpl(const Group &recipe,
++ const TreeSetupHandler &setupHandler,
++ const TreeDoneHandler &doneHandler,
++ CallDone callDone)
++ {
++ Q_D(QSingleTaskTreeRunner);
++ d->m_taskTree.reset(new QTaskTree(recipe));
++ QObject::connect(d->m_taskTree.get(), &QTaskTree::done, d->m_taskTree.get(),
++ [d, doneHandler, callDone](DoneWith result) {
++ QTaskTree *taskTree = d->m_taskTree.release();
++ taskTree->deleteLater();
++ if (doneHandler && shouldCallDone(callDone, result))
++ doneHandler(*taskTree, result);
++ });
++ if (setupHandler)
++ setupHandler(*d->m_taskTree);
++ d->m_taskTree->start();
++ }
++
++ struct TreeData
++ {
++ Group recipe;
++ TreeSetupHandler setupHandler;
++ TreeDoneHandler doneHandler;
++ CallDone callDone;
++ };
++
++ class QSequentialTaskTreeRunnerPrivate
++ {
++ public:
++ void startNext();
++
++ QList<TreeData> m_treeDataQueue;
++ QSingleTaskTreeRunner m_taskTreeRunner;
++ };
++
++ /*!
++ \class QtTaskTree::QSequentialTaskTreeRunner
++ \inheaderfile qtasktreerunner.h
++ \inmodule QtTaskTree
++ \brief A sequential task tree execution controller.
++
++ Manages sequential task tree execution.
++ Use the enqueue() method to schedule the execution of a given recipe.
++ It's guaranteed that at most one task tree is executing at any given time.
++
++ \sa {Task Tree Runners}
++ */
++
++ void QSequentialTaskTreeRunnerPrivate::startNext()
++ {
++ if (m_treeDataQueue.isEmpty())
++ return;
++
++ const auto data = m_treeDataQueue.takeFirst();
++ const auto doneHandler = [this, doneHandler = data.doneHandler, callDone = data.callDone]
++ (const QTaskTree &taskTree, QtTaskTree::DoneWith result) {
++ if (doneHandler && shouldCallDone(callDone, result))
++ doneHandler(taskTree, result);
++ startNext();
++ };
++ m_taskTreeRunner.start(data.recipe, data.setupHandler, doneHandler);
++ }
++
++ /*!
++ Constructs a sequential task tree runner.
++ */
++ QSequentialTaskTreeRunner::QSequentialTaskTreeRunner() : d_ptr(new QSequentialTaskTreeRunnerPrivate) {}
++
++ /*!
++ Destroys the sequential task tree runner. A possibly running
++ task tree is deleted and enqueued tasks are removed.
++ No task tree's done handler is called.
++
++ \sa {QTaskTree::~QTaskTree()} {~QTaskTree()}
++ */
++ QSequentialTaskTreeRunner::~QSequentialTaskTreeRunner() = default;
++
++ /*!
++ Returns whether the sequential task tree runner is currently
++ executing a task tree.
++ */
++ bool QSequentialTaskTreeRunner::isRunning() const
++ {
++ Q_D(const QSequentialTaskTreeRunner);
++ return !d->m_treeDataQueue.isEmpty() || d->m_taskTreeRunner.isRunning();
++ }
++
++ /*!
++ Cancels the running task tree. Calls task tree' done
++ handler with \l {QtTaskTree::} {DoneWith::Cancel}.
++ All queued tasks are removed.
++ */
++ void QSequentialTaskTreeRunner::cancel()
++ {
++ Q_D(QSequentialTaskTreeRunner);
++ d->m_treeDataQueue.clear();
++ d->m_taskTreeRunner.cancel();
++ }
++
++ /*!
++ Resets the running task tree. No task tree's done handler is called.
++ All queued tasks are removed.
++ */
++ void QSequentialTaskTreeRunner::reset()
++ {
++ Q_D(QSequentialTaskTreeRunner);
++ d->m_treeDataQueue.clear();
++ d->m_taskTreeRunner.reset();
++ }
++
++ /*!
++ Cancels the running task tree. Calls task tree' done
++ handler with \l {QtTaskTree::} {DoneWith::Cancel}.
++ If there are any enqueued recipes, the dequeued recipe is started.
++ */
++ void QSequentialTaskTreeRunner::cancelCurrent()
++ {
++ Q_D(QSequentialTaskTreeRunner);
++ d->m_taskTreeRunner.cancel();
++ }
++
++ /*!
++ Resets the running task tree. No task tree's done handler is called.
++ If there are any enqueued recipes, the dequeued recipe is started.
++ */
++ void QSequentialTaskTreeRunner::resetCurrent()
++ {
++ Q_D(QSequentialTaskTreeRunner);
++ d->m_taskTreeRunner.reset();
++ d->startNext();
++ }
++
++ /*!
++ \fn template <typename SetupHandler = TreeSetupHandler, typename DoneHandler = TreeDoneHandler> void QSequentialTaskTreeRunner::enqueue(const QtTaskTree::Group &recipe, SetupHandler &&setupHandler = {}, DoneHandler &&doneHandler = {}, QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)
++
++ Schedules the \a recipe execution. If no task tree is executing,
++ the runner starts a new task tree synchronously, otherwise
++ the \a recipe is enqueued. When the currently executing task tree
++ finished, the runner starts a new task tree with a dequeued recipe.
++ Calls \a setupHandler when new task tree is about to be started.
++ Calls \a doneHandler when the task tree is finished.
++ The \a doneHandler is called according to the passed \a callDone.
++ */
++
++ void QSequentialTaskTreeRunner::enqueueImpl(const Group &recipe,
++ const TreeSetupHandler &setupHandler,
++ const TreeDoneHandler &doneHandler,
++ CallDone callDone)
++ {
++ Q_D(QSequentialTaskTreeRunner);
++ d->m_treeDataQueue.append({recipe, setupHandler, doneHandler, callDone});
++ if (!d->m_taskTreeRunner.isRunning())
++ d->startNext();
++ }
++
++ class QParallelTaskTreeRunnerPrivate
++ {
++ public:
++ std::unordered_map<QTaskTree *, std::unique_ptr<QTaskTree>> m_taskTrees;
++ };
++
++ /*!
++ \class QtTaskTree::QParallelTaskTreeRunner
++ \inheaderfile qtasktreerunner.h
++ \inmodule QtTaskTree
++ \brief A parallel task tree execution controller.
++
++ Manages parallel task tree execution.
++ Use the start() method to execute a given recipe instantly,
++ keeping other possibly running task trees in parallel.
++
++ \sa {Task Tree Runners}
++ */
++
++ /*!
++ Constructs a parallel task tree runner.
++ */
++ QParallelTaskTreeRunner::QParallelTaskTreeRunner() : d_ptr(new QParallelTaskTreeRunnerPrivate) {}
++
++ /*!
++ Destroys the parallel task tree runner. All running
++ task trees are deleted. No task trees' done handlers are called.
++
++ \sa {QTaskTree::~QTaskTree()} {~QTaskTree()}
++ */
++ QParallelTaskTreeRunner::~QParallelTaskTreeRunner() = default;
++
++ /*!
++ Returns whether the parallel task tree runner is currently
++ executing at least one task tree.
++ */
++ bool QParallelTaskTreeRunner::isRunning() const { return !d_func()->m_taskTrees.empty(); }
++
++ /*!
++ Cancels all running task trees. Calls task trees' done
++ handlers with \l {QtTaskTree::} {DoneWith::Cancel}.
++ The order of task trees' cancellation is random.
++ */
++ void QParallelTaskTreeRunner::cancel()
++ {
++ Q_D(QParallelTaskTreeRunner);
++ while (!d->m_taskTrees.empty())
++ d->m_taskTrees.begin()->second->cancel();
++ }
++
++ /*!
++ Resets all running task trees. No task trees' done handlers are called.
++ */
++ void QParallelTaskTreeRunner::reset()
++ {
++ d_func()->m_taskTrees.clear();
++ }
++
++ /*!
++ \fn template <typename SetupHandler = TreeSetupHandler, typename DoneHandler = TreeDoneHandler> void QParallelTaskTreeRunner::start(const QtTaskTree::Group &recipe, SetupHandler &&setupHandler = {}, DoneHandler &&doneHandler = {}, QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)
++
++ Starts the \a recipe instantly and keeps other possibly running
++ task trees in parallel.
++ Calls \a setupHandler when new task tree is about to be started.
++ Calls \a doneHandler when the task tree is finished.
++ The \a doneHandler is called according to the passed \a callDone.
++ */
++
++ void QParallelTaskTreeRunner::startImpl(const Group &recipe,
++ const TreeSetupHandler &setupHandler,
++ const TreeDoneHandler &doneHandler,
++ CallDone callDone)
++ {
++ Q_D(QParallelTaskTreeRunner);
++ QTaskTree *taskTree = new QTaskTree(recipe);
++ QObject::connect(taskTree, &QTaskTree::done, taskTree, [d, taskTree, doneHandler, callDone](DoneWith result) {
++ const auto it = d->m_taskTrees.find(taskTree);
++ it->second.release()->deleteLater();
++ d->m_taskTrees.erase(it);
++ if (doneHandler && shouldCallDone(callDone, result))
++ doneHandler(*taskTree, result);
++ });
++ d->m_taskTrees.emplace(taskTree, taskTree);
++ if (setupHandler)
++ setupHandler(*taskTree);
++ taskTree->start();
++ }
++
++ /*!
++ \class QtTaskTree::QMappedTaskTreeRunner
++ \inheaderfile qtasktreerunner.h
++ \inmodule QtTaskTree
++ \brief A mapped task tree execution controller with a given Key type.
++
++ Manages mapped task tree execution using the \a Key type.
++ Use the start() method to execute a recipe for a given key unconditionally,
++ resetting a possibly running task tree with the same key,
++ and keeping other possibly running task trees with different keys
++ in parallel.
++
++ \sa {Task Tree Runners}
++ */
++
++ /*!
++ \fn template <typename Key> QMappedTaskTreeRunner<Key>::QMappedTaskTreeRunner()
++
++ Constructs a mapped task tree runner.
++ The \c Key type is used for task tree mapping.
++ */
++
++ /*!
++ \fn template <typename Key> QMappedTaskTreeRunner<Key>::~QMappedTaskTreeRunner()
++
++ Destroys the mapped task tree runner. All running
++ task trees are deleted. No task trees' done handlers are called.
++
++ \sa {QTaskTree::~QTaskTree()} {~QTaskTree()}
++ */
++
++ /*!
++ \fn template <typename Key> bool QMappedTaskTreeRunner<Key>::isRunning() const
++
++ Returns whether the mapped task tree runner is currently
++ executing at least one task tree.
++ */
++
++ /*!
++ \fn template <typename Key> void QMappedTaskTreeRunner<Key>::cancel()
++
++ Cancels all running task trees. Calls task trees' done
++ handlers with \l {QtTaskTree::} {DoneWith::Cancel}.
++ The order of task trees' cancellation is random.
++ */
++
++ /*!
++ \fn template <typename Key> void QMappedTaskTreeRunner<Key>::reset()
++
++ Resets all running task trees. No task trees' done handlers are called.
++ */
++
++ /*!
++ \fn template <typename Key> bool QMappedTaskTreeRunner<Key>::isKeyRunning(const Key &key) const
++
++ Returns whether the mapped task tree runner is currently
++ executing a task tree that was started with the \a key.
++ */
++
++ /*!
++ \fn template <typename Key> void QMappedTaskTreeRunner<Key>::cancelKey(const Key &key)
++
++ Cancels a potentially running task tree that was started with the \a key.
++ Calls task tree's done handler with \l {QtTaskTree::} {DoneWith::Cancel}.
++ */
++
++ /*!
++ \fn template <typename Key> void QMappedTaskTreeRunner<Key>::resetKey(const Key &key)
++
++ Resets a potentially running task tree that was started with the \a key.
++ No task tree's done handlers is called.
++ */
++
++ /*!
++ \fn template <typename Key> template <typename SetupHandler = TreeSetupHandler, typename DoneHandler = TreeDoneHandler> void QMappedTaskTreeRunner<Key>::start(const Key &key, const QtTaskTree::Group &recipe, SetupHandler &&setupHandler = {}, DoneHandler &&doneHandler = {}, QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)
++
++ Starts the \a recipe for a given \a key unconditionally,
++ resetting any possibly running task tree with the same key,
++ and keeping other possibly running task trees with different keys
++ in parallel.
++ Calls \a setupHandler when new task tree is about to be started.
++ Calls \a doneHandler when the task tree is finished.
++ The \a doneHandler is called according to the passed \a callDone.
++ */
++
++ } // namespace QtTaskTree
++
++ QT_END_NAMESPACE