Revision control
Copy as Markdown
// 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
#ifndef QTASKTREE_QTASKTREE_H
#define QTASKTREE_QTASKTREE_H
#include <QtTaskTree/qttasktreeglobal.h>
#include <QtCore/QList>
#include <QtCore/QObject>
#include <QtCore/QSharedData>
#include <memory>
#include <QtCore/qxptype_traits.h>
QT_BEGIN_NAMESPACE
#if QT_CONFIG(future)
template <class T>
class QFuture;
#endif
namespace QtTaskTree {
class Do;
class DoPrivate;
class For;
class ForPrivate;
class Group;
class GroupItem;
class GroupItemPrivate;
using GroupItems = QList<GroupItem>;
class IteratorPrivate;
class QTaskInterface;
class QTaskTree;
class QTaskTreePrivate;
class StorageBasePrivate;
class When;
}
#define QT_TASKTREE_DECLARE_SMFS(Class, ExportMacro) \
ExportMacro ~Class(); \
ExportMacro Class(const Class &other); \
ExportMacro Class &operator=(const Class &other); \
Class(Class &&other) = default; \
QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_MOVE_AND_SWAP(Class) \
void swap(Class &other) noexcept { d.swap(other.d); } \
/* end */
#define QT_TASKTREE_DEFINE_SMF(Class) \
Class::~Class() = default; \
Class::Class(const Class &other) = default; \
Class &Class::operator=(const Class &other) = default; \
/* end */
QT_DECLARE_QESDP_SPECIALIZATION_DTOR(QtTaskTree::DoPrivate)
QT_DECLARE_QESDP_SPECIALIZATION_DTOR(QtTaskTree::ForPrivate)
QT_DECLARE_QESDP_SPECIALIZATION_DTOR(QtTaskTree::GroupItemPrivate)
QT_DECLARE_QESDP_SPECIALIZATION_DTOR(QtTaskTree::IteratorPrivate)
QT_DECLARE_QESDP_SPECIALIZATION_DTOR(QtTaskTree::StorageBasePrivate)
namespace QtTaskTree {
Q_NAMESPACE_EXPORT(Q_TASKTREE_EXPORT)
enum class WorkflowPolicy
{
StopOnError,
ContinueOnError,
StopOnSuccess,
ContinueOnSuccess,
StopOnSuccessOrError,
FinishAllAndSuccess,
FinishAllAndError,
};
Q_ENUM_NS(WorkflowPolicy)
enum class SetupResult
{
Continue,
StopWithSuccess,
StopWithError,
};
Q_ENUM_NS(SetupResult)
enum class DoneResult
{
Success,
Error,
};
Q_ENUM_NS(DoneResult)
enum class DoneWith
{
Success,
Error,
Cancel
};
Q_ENUM_NS(DoneWith)
enum class CallDoneFlag
{
Never = 0,
OnSuccess = 1 << 0,
OnError = 1 << 1,
OnCancel = 1 << 2,
Always = OnSuccess | OnError | OnCancel,
};
Q_DECLARE_FLAGS(CallDone, CallDoneFlag)
Q_DECLARE_OPERATORS_FOR_FLAGS(CallDone)
Q_FLAG_NS(CallDone)
Q_TASKTREE_EXPORT DoneResult toDoneResult(bool success);
Q_TASKTREE_EXPORT bool shouldCallDone(CallDone callDone, DoneWith result);
// Checks if Function may be invoked with Args and if Function's return type is Result.
template <typename Result, typename Function, typename ...Args,
typename DecayedFunction = std::decay_t<Function>>
constexpr bool isInvocable()
{
// Note, that std::is_invocable_r_v doesn't check Result type properly.
if constexpr (std::is_invocable_r_v<Result, DecayedFunction, Args...>)
return std::is_same_v<Result, std::invoke_result_t<DecayedFunction, Args...>>;
return false;
}
class Iterator
{
public:
using Condition = std::function<bool(qsizetype)>; // Takes iteration, called prior to each iteration.
using ValueGetter = std::function<const void *(qsizetype)>; // Takes iteration, returns ptr to ref.
QT_TASKTREE_DECLARE_SMFS(Iterator, Q_TASKTREE_EXPORT)
Q_TASKTREE_EXPORT qsizetype iteration() const;
private:
struct LazyList {
std::function<std::shared_ptr<void>()> m_listGetter;
const void *(*m_valueGetter)(const void *, qsizetype);
qsizetype (*m_listSizer)(const void *);
};
Q_TASKTREE_EXPORT Iterator(); // ForeverIterator
Q_TASKTREE_EXPORT Iterator(qsizetype count, const ValueGetter &valueGetter = {}); // RepeatIterator, ListIterator (direct list)
Q_TASKTREE_EXPORT Iterator(const Condition &condition); // UntilIterator
Q_TASKTREE_EXPORT Iterator(LazyList &&lazyList); // ListIterator (LazyList)
Q_TASKTREE_EXPORT const void *valuePtr() const;
friend class ExecutionContextActivator;
friend class ForeverIterator;
friend class IteratorPrivate;
friend class QTaskTreePrivate;
friend class RepeatIterator;
friend class RuntimeContainer;
friend class UntilIterator;
template <typename T> friend class ListIterator;
QExplicitlySharedDataPointer<IteratorPrivate> d;
};
class ForeverIterator final : public Iterator
{
public:
Q_TASKTREE_EXPORT ForeverIterator();
};
class RepeatIterator final : public Iterator
{
public:
Q_TASKTREE_EXPORT explicit RepeatIterator(qsizetype count);
};
class UntilIterator final : public Iterator
{
public:
Q_TASKTREE_EXPORT explicit UntilIterator(const Condition &condition);
};
template <typename T>
class ListIterator final : public Iterator
{
// std::void_t makes the specialisation a SFINAE failure (rather than a hard error) when
// G is not invocable, its return type has no value_type matching T, or it is not a
// contiguous range (std::data() not supported).
template <typename, typename = void>
struct is_compatible_range_getter : std::false_type {};
template <typename G>
struct is_compatible_range_getter<G, std::void_t<
std::enable_if_t<std::is_same_v<typename std::invoke_result_t<G>::value_type, T>>,
decltype(std::data(std::declval<const std::invoke_result_t<G>>()))
>> : std::true_type {};
template <typename RangeGetter>
using if_compatible_range = std::enable_if_t<is_compatible_range_getter<std::decay_t<RangeGetter>>::value, bool>;
public:
explicit ListIterator(const QList<T> &list)
: Iterator(list.size(), [list](qsizetype i) { return std::addressof(list.at(i)); }) {}
template <typename RangeGetter,
if_compatible_range<RangeGetter> = true,
typename RangeType = std::invoke_result_t<std::decay_t<RangeGetter>>>
explicit ListIterator(RangeGetter &&rangeGetter)
: Iterator({
[rangeGetter = std::forward<RangeGetter>(rangeGetter)] {
return std::make_shared<RangeType>(rangeGetter());
},
[](const void *list, qsizetype i) -> const void * {
return std::data(*static_cast<const RangeType *>(list)) + i;
},
[](const void *list) -> qsizetype {
return static_cast<const RangeType *>(list)->size();
},
}) {}
const T *operator->() const { return static_cast<const T *>(valuePtr()); }
const T &operator*() const { return *static_cast<const T *>(valuePtr()); }
};
// C++17 deduction guide: deduces T from RangeGetter's return type value_type.
template <typename RangeGetter>
ListIterator(RangeGetter &&) -> ListIterator<typename std::invoke_result_t<RangeGetter>::value_type>;
class StorageBase
{
public:
QT_TASKTREE_DECLARE_SMFS(StorageBase, Q_TASKTREE_EXPORT)
private:
using StorageCreator = std::function<std::shared_ptr<void>()>;
using StorageHandler = std::function<void(void *)>;
Q_TASKTREE_EXPORT StorageBase(const StorageCreator &creator);
Q_TASKTREE_EXPORT void *activeStorageVoid() const;
// TODO: de-inline?
friend bool operator==(const StorageBase &first, const StorageBase &second)
{ return first.d == second.d; }
friend bool operator!=(const StorageBase &first, const StorageBase &second)
{ return first.d != second.d; }
friend size_t qHash(const StorageBase &storage, size_t seed = 0) noexcept
{ return size_t(storage.d.get()) ^ seed; }
QExplicitlySharedDataPointer<StorageBasePrivate> d;
template <typename StorageStruct> friend class Storage;
friend class ExecutionContextActivator;
friend class StorageBasePrivate;
friend class RuntimeContainer;
friend class QTaskTree;
friend class QTaskTreePrivate;
};
template <typename StorageStruct>
class Storage final : public StorageBase
{
public:
Storage() : StorageBase([] { return std::make_shared<StorageStruct>(); }) {}
template <typename FirstArg, typename ...Args,
std::enable_if_t<!std::is_same_v<q20::remove_cvref_t<FirstArg>, Storage<StorageStruct>>, bool> = true>
explicit Storage(const FirstArg &firstArg, const Args &...args)
: StorageBase([=] { return std::make_shared<StorageStruct>(firstArg, args...); }) {}
StorageStruct &operator*() const noexcept { return *activeStorage(); }
StorageStruct *operator->() const noexcept { return activeStorage(); }
StorageStruct *activeStorage() const {
return static_cast<StorageStruct *>(activeStorageVoid());
}
};
class GroupItem
{
public:
// Called when group entered, after group's storages are created
using GroupSetupHandler = std::function<SetupResult()>;
// Called when group done, before group's storages are deleted
using GroupDoneHandler = std::function<DoneResult(DoneWith)>;
template <typename StorageStruct>
GroupItem(const Storage<StorageStruct> &storage) : GroupItem(static_cast<StorageBase>(storage)) {}
// TODO: Add tests.
Q_TASKTREE_EXPORT GroupItem(const GroupItems &children);
Q_TASKTREE_EXPORT GroupItem(std::initializer_list<GroupItem> children);
QT_TASKTREE_DECLARE_SMFS(GroupItem, Q_TASKTREE_EXPORT)
protected:
Q_TASKTREE_EXPORT GroupItem(const Iterator &loop);
using TaskAdapterPtr = void *;
// Internal, provided by QCustomTask
using TaskAdapterCreator = std::function<std::shared_ptr<void>(void)>;
//
using TaskAdapterStarter = std::function<void(TaskAdapterPtr, QTaskInterface *)>;
// Called prior to task start, just after createHandler
using TaskAdapterSetupHandler = std::function<SetupResult(TaskAdapterPtr)>;
// Called on task done, just before deleteLater
using TaskAdapterDoneHandler = std::function<DoneResult(TaskAdapterPtr, DoneWith)>;
struct TaskHandler { // TODO: Make it a pimpled value type?
TaskAdapterCreator m_taskAdapterCreator;
TaskAdapterStarter m_taskAdapterStarter;
TaskAdapterSetupHandler m_taskAdapterSetupHandler = {};
TaskAdapterDoneHandler m_taskAdapterDoneHandler = {};
CallDone m_callDoneFlags = CallDoneFlag::Always;
};
struct GroupHandler { // TODO: Make it a pimpled value type?
GroupSetupHandler m_setupHandler;
GroupDoneHandler m_doneHandler = {};
CallDone m_callDoneFlags = CallDoneFlag::Always;
};
struct GroupData { // TODO: Make it a pimpled value type?
GroupHandler m_groupHandler = {};
std::optional<int> m_parallelLimit = std::nullopt;
std::optional<WorkflowPolicy> m_workflowPolicy = std::nullopt;
std::optional<Iterator> m_iterator = std::nullopt;
};
enum class Type {
List,
Group,
GroupData,
Storage,
TaskHandler,
};
Q_TASKTREE_EXPORT GroupItem();
Q_TASKTREE_EXPORT GroupItem(Type type);
Q_TASKTREE_EXPORT GroupItem(const GroupData &data);
Q_TASKTREE_EXPORT GroupItem(const TaskHandler &handler);
Q_TASKTREE_EXPORT void addChildren(const GroupItems &children);
Q_TASKTREE_EXPORT static GroupItem groupHandler(const GroupHandler &handler);
Q_TASKTREE_EXPORT TaskHandler taskHandler() const;
private:
Q_TASKTREE_EXPORT GroupItem(const StorageBase &storage);
Q_TASKTREE_EXPORT friend Group operator>>(const For &forItem, const Do &doItem);
friend class ContainerNode;
friend class GroupItemPrivate;
friend class TaskInterfaceAdapter;
friend class TaskNode;
friend class QTaskTreePrivate;
QExplicitlySharedDataPointer<GroupItemPrivate> d;
};
template <typename Signal>
struct ObjectSignal
{
typename QtPrivate::FunctionPointer<Signal>::Object *object;
Signal signal;
};
template <typename Signal>
ObjectSignal<std::decay_t<Signal>> makeObjectSignal(
typename QtPrivate::FunctionPointer<Signal>::Object *object, Signal &&signal)
{
return ObjectSignal<std::decay_t<Signal>>{object, std::forward<Signal>(signal)};
}
class ExecutableItem : public GroupItem
{
public:
Q_TASKTREE_EXPORT Group withTimeout(std::chrono::milliseconds timeout,
const std::function<void()> &handler = {}) const;
Q_TASKTREE_EXPORT Group withLog(const QString &logName) const;
template <typename ObjectSignalGetter>
Group withCancel(ObjectSignalGetter &&getter,
std::initializer_list<GroupItem> postCancelRecipe = {}) const;
template <typename ObjectSignalGetter>
Group withAccept(ObjectSignalGetter &&getter) const;
protected:
Q_TASKTREE_EXPORT ExecutableItem();
Q_TASKTREE_EXPORT ExecutableItem(const TaskHandler &handler);
private:
Q_TASKTREE_EXPORT friend Group operator!(const ExecutableItem &item);
// AXIVION DISABLE Style Qt-Generic-NoOverloadedOperators: Works in short-circuiting fashion when the recipe is executed
Q_TASKTREE_EXPORT friend Group operator&&(const ExecutableItem &first,
const ExecutableItem &second);
Q_TASKTREE_EXPORT friend Group operator||(const ExecutableItem &first,
const ExecutableItem &second);
Q_TASKTREE_EXPORT friend Group operator&&(const ExecutableItem &item, DoneResult result);
Q_TASKTREE_EXPORT friend Group operator||(const ExecutableItem &item, DoneResult result);
// AXIVION ENABLE Style Qt-Generic-NoOverloadedOperators
using ConnectWrapper = std::function<void(QObject *, const std::function<void()> &)>;
Q_TASKTREE_EXPORT Group withCancelImpl(const ConnectWrapper &connectWrapper,
const GroupItems &postCancelRecipe) const;
Q_TASKTREE_EXPORT Group withAcceptImpl(const ConnectWrapper &connectWrapper) const;
template <typename ObjectSignalGetter>
static ConnectWrapper connectWrapper(ObjectSignalGetter &&getter)
{
return [getter = std::forward<ObjectSignalGetter>(getter)](
QObject *guard, const std::function<void()> &trigger) {
const auto objectSignal = getter();
QObject::connect(objectSignal.object, objectSignal.signal, guard, trigger,
static_cast<Qt::ConnectionType>(Qt::QueuedConnection | Qt::SingleShotConnection));
};
}
friend class When;
};
class Group final : public ExecutableItem
{
public:
Q_TASKTREE_EXPORT Group(const GroupItems &children);
Q_TASKTREE_EXPORT Group(std::initializer_list<GroupItem> children);
// GroupData related:
template <typename Handler>
static GroupItem onGroupSetup(Handler &&handler) {
return groupHandler({wrapGroupSetup(std::forward<Handler>(handler))});
}
template <typename Handler>
static GroupItem onGroupDone(Handler &&handler, CallDone callDone = CallDoneFlag::Always) {
return groupHandler({{}, wrapGroupDone(std::forward<Handler>(handler)), callDone});
}
private:
template <typename Handler>
static GroupSetupHandler wrapGroupSetup(Handler &&handler)
{
return [handler = std::forward<Handler>(handler)] {
// R, V stands for: Setup[R]esult, [V]oid
constexpr bool isR = QtTaskTree::isInvocable<SetupResult, Handler>();
constexpr bool isV = QtTaskTree::isInvocable<void, Handler>();
static_assert(isR || isV,
"Group setup handler needs to take no arguments and has to return void or SetupResult. "
"The passed handler doesn't fulfill these requirements.");
if constexpr (isR)
return std::invoke(handler);
std::invoke(handler);
return SetupResult::Continue;
};
}
template <typename Handler>
static GroupDoneHandler wrapGroupDone(Handler &&handler)
{
return [handler = std::forward<Handler>(handler)](DoneWith result) {
constexpr bool isDoneResultType = std::is_same_v<std::decay_t<Handler>, DoneResult>;
// R, B, V, D stands for: Done[R]esult, [B]ool, [V]oid, [D]oneWith
constexpr bool isRD = QtTaskTree::isInvocable<DoneResult, Handler, DoneWith>();
constexpr bool isR = QtTaskTree::isInvocable<DoneResult, Handler>();
constexpr bool isBD = QtTaskTree::isInvocable<bool, Handler, DoneWith>();
constexpr bool isB = QtTaskTree::isInvocable<bool, Handler>();
constexpr bool isVD = QtTaskTree::isInvocable<void, Handler, DoneWith>();
constexpr bool isV = QtTaskTree::isInvocable<void, Handler>();
static_assert(isDoneResultType || isRD || isR || isBD || isB || isVD || isV,
"Group done handler should be a function taking (DoneWith) or (void) as an argument "
"and returning void, bool or DoneResult. "
"Alternatively, 'handler' may be an instance of DoneResult. "
"The passed handler doesn't fulfill these requirements.");
if constexpr (isDoneResultType)
return handler;
if constexpr (isRD)
return std::invoke(handler, result);
if constexpr (isR)
return std::invoke(handler);
if constexpr (isBD)
return toDoneResult(std::invoke(handler, result));
if constexpr (isB)
return toDoneResult(std::invoke(handler));
if constexpr (isVD)
std::invoke(handler, result);
else if constexpr (isV)
std::invoke(handler);
return toDoneResult(result == DoneWith::Success);
};
}
};
template <typename ObjectSignalGetter>
Group ExecutableItem::withCancel(ObjectSignalGetter &&getter,
std::initializer_list<GroupItem> postCancelRecipe) const
{
return withCancelImpl(connectWrapper(std::forward<ObjectSignalGetter>(getter)),
postCancelRecipe);
}
template <typename ObjectSignalGetter>
Group ExecutableItem::withAccept(ObjectSignalGetter &&getter) const
{
return withAcceptImpl(connectWrapper(std::forward<ObjectSignalGetter>(getter)));
}
template <typename Handler>
GroupItem onGroupSetup(Handler &&handler)
{
return Group::onGroupSetup(std::forward<Handler>(handler));
}
template <typename Handler>
GroupItem onGroupDone(Handler &&handler, CallDone callDone = CallDoneFlag::Always)
{
return Group::onGroupDone(std::forward<Handler>(handler), callDone);
}
class ExecutionMode : public GroupItem
{
private:
friend class ParallelLimit;
Q_TASKTREE_EXPORT ExecutionMode(int limit);
};
class ParallelLimit : public ExecutionMode
{
public:
Q_TASKTREE_EXPORT ParallelLimit(int limit);
};
// Default: WorkflowPolicy::StopOnError.
Q_TASKTREE_EXPORT GroupItem workflowPolicy(WorkflowPolicy policy);
Q_TASKTREE_EXPORT extern const ExecutionMode sequential;
Q_TASKTREE_EXPORT extern const ExecutionMode parallel;
Q_TASKTREE_EXPORT extern const ExecutionMode parallelIdealThreadCountLimit;
Q_TASKTREE_EXPORT extern const GroupItem stopOnError;
Q_TASKTREE_EXPORT extern const GroupItem continueOnError;
Q_TASKTREE_EXPORT extern const GroupItem stopOnSuccess;
Q_TASKTREE_EXPORT extern const GroupItem continueOnSuccess;
Q_TASKTREE_EXPORT extern const GroupItem stopOnSuccessOrError;
Q_TASKTREE_EXPORT extern const GroupItem finishAllAndSuccess;
Q_TASKTREE_EXPORT extern const GroupItem finishAllAndError;
Q_TASKTREE_EXPORT extern const GroupItem nullItem;
Q_TASKTREE_EXPORT extern const ExecutableItem successItem;
Q_TASKTREE_EXPORT extern const ExecutableItem errorItem;
class For final
{
public:
Q_TASKTREE_EXPORT explicit For(const Iterator &loop);
Q_TASKTREE_EXPORT explicit For(qsizetype count);
QT_TASKTREE_DECLARE_SMFS(For, Q_TASKTREE_EXPORT)
private:
Q_TASKTREE_EXPORT friend Group operator>>(const For &forItem, const Do &doItem);
Iterator iterator() const;
QExplicitlySharedDataPointer<ForPrivate> d;
};
class Do final
{
public:
Q_TASKTREE_EXPORT explicit Do(const GroupItems &children);
Q_TASKTREE_EXPORT explicit Do(std::initializer_list<GroupItem> children);
QT_TASKTREE_DECLARE_SMFS(Do, Q_TASKTREE_EXPORT)
private:
Q_TASKTREE_EXPORT friend Group operator>>(const For &forItem, const Do &doItem);
Q_TASKTREE_EXPORT friend Group operator>>(const When &whenItem, const Do &doItem);
GroupItem children() const;
QExplicitlySharedDataPointer<DoPrivate> d;
};
class Forever final : public ExecutableItem
{
public:
Q_TASKTREE_EXPORT explicit Forever(const GroupItems &children);
Q_TASKTREE_EXPORT explicit Forever(std::initializer_list<GroupItem> children);
Q_TASKTREE_EXPORT operator Group() const;
};
Q_TASKTREE_EXPORT ExecutableItem timeoutTask(const std::chrono::milliseconds &timeout,
DoneResult result = DoneResult::Error);
class QSyncTask final : public ExecutableItem
{
public:
template <typename Handler,
std::enable_if_t<!std::is_same_v<q20::remove_cvref_t<Handler>, QSyncTask>, bool> = true>
explicit QSyncTask(Handler &&handler) {
addChildren({ onGroupDone(wrapHandler(std::forward<Handler>(handler))) });
}
private:
template <typename Handler>
static auto wrapHandler(Handler &&handler) {
// R, B, V stands for: Done[R]esult, [B]ool, [V]oid
constexpr bool isR = QtTaskTree::isInvocable<DoneResult, Handler>();
constexpr bool isB = QtTaskTree::isInvocable<bool, Handler>();
constexpr bool isV = QtTaskTree::isInvocable<void, Handler>();
static_assert(isR || isB || isV,
"QSyncTask handler needs to take no arguments and has to return void, bool or DoneResult. "
"The passed handler doesn't fulfill these requirements.");
return handler;
}
};
class Q_TASKTREE_EXPORT QTaskInterface final : public QObject
{
Q_OBJECT
public:
QTaskInterface() : QTaskInterface(nullptr) {}
explicit QTaskInterface(QObject *parent);
void reportDone(DoneResult result);
Q_SIGNALS:
void done(QtTaskTree::DoneResult result, QPrivateSignal);
protected:
bool event(QEvent *event) override;
};
// A convenient default helper, when:
// 1. Task is derived from QObject.
// 2. Task::start() method starts the task.
// 3. Task::done(DoneResult) or Task::done(bool) signal is emitted when the task is finished.
template <typename Task>
class QDefaultTaskAdapter
{
public:
void operator()(Task *task, QTaskInterface *iface) const {
if constexpr (is_done_compatible_v<WithDoneResult>) {
QObject::connect(task, &Task::done, iface, &QTaskInterface::reportDone,
Qt::SingleShotConnection);
} else if constexpr (is_done_compatible_v<WithBool>) {
QObject::connect(task, &Task::done, iface, [iface](bool result) {
iface->reportDone(toDoneResult(result));
}, Qt::SingleShotConnection);
}
task->start();
}
private:
static_assert(std::is_base_of_v<QObject, Task>,
"QDefaultTaskAdapter<Task>: The Task type needs to be derived from QObject.");
template <typename T>
using HasStartTest = decltype(
std::declval<T>().start()
);
static_assert(qxp::is_detected_v<HasStartTest, Task>,
"QDefaultTaskAdapter<Task>: The Task type needs to specify public start() method.");
#define DoneError "QDefaultTaskAdapter<Task>: The Task type needs to specify " \
"public done(DoneResult) or done(bool) signal."
template <typename T>
using HasDoneTest = decltype(
&T::done
);
static_assert(qxp::is_detected_v<HasDoneTest, Task>, DoneError);
using WithDoneResult = std::function<void(DoneResult)>;
using WithBool = std::function<void(bool)>;
template <typename Arg, typename T = decltype(&Task::done)>
static inline constexpr bool is_done_compatible_v = QtPrivate::AreFunctionsCompatible<T, Arg>::value;
static_assert(is_done_compatible_v<WithDoneResult> || is_done_compatible_v<WithBool>, DoneError);
#undef DoneError
};
// TODO: Allow Task = void?
template <typename Task, typename Adapter = QDefaultTaskAdapter<Task>,
typename Deleter = std::default_delete<Task>>
class QCustomTask final : public ExecutableItem
{
public:
using TaskSetupHandler = std::function<SetupResult(Task &)>;
using TaskDoneHandler = std::function<DoneResult(const Task &, DoneWith)>;
template <typename SetupHandler = TaskSetupHandler, typename DoneHandler = TaskDoneHandler,
std::enable_if_t<!std::is_same_v<q20::remove_cvref_t<SetupHandler>, QCustomTask<Task, Adapter, Deleter>>, bool> = true>
explicit QCustomTask(SetupHandler &&setup = TaskSetupHandler(),
DoneHandler &&done = TaskDoneHandler(),
CallDone callDone = CallDoneFlag::Always)
: ExecutableItem(TaskHandler{&taskAdapterCreator, &taskAdapterStarter,
wrapSetup(std::forward<SetupHandler>(setup)),
wrapDone(std::forward<DoneHandler>(done)), callDone})
{}
private:
static_assert(std::is_default_constructible_v<Task>,
"QCustomTask<Type, Adapter, Deleter>: The Task type needs to "
"be default constructible.");
static_assert(std::is_default_constructible_v<Adapter>,
"QCustomTask<Type, Adapter, Deleter>: The Adapter type needs to "
"be default constructible.");
static_assert(std::is_invocable_v<Adapter, Task *, QTaskInterface *>,
"QCustomTask<Type, Adapter, Deleter>: The Adapter type needs to "
"implement public \"void operator()(Task *task, QTaskInterface *iface);\" "
"method.");
friend class When;
struct TaskAdapter {
TaskAdapter() : task(new Task()) {}
std::unique_ptr<Task, Deleter> task;
Adapter adapter;
};
static std::shared_ptr<void> taskAdapterCreator() { return std::make_shared<TaskAdapter>(); }
static void taskAdapterStarter(TaskAdapterPtr voidAdapter, QTaskInterface *iface) {
TaskAdapter *taskAdapter = static_cast<TaskAdapter *>(voidAdapter);
std::invoke(taskAdapter->adapter, taskAdapter->task.get(), iface);
}
template <typename Handler>
static TaskAdapterSetupHandler wrapSetup(Handler &&handler) {
if constexpr (std::is_same_v<std::decay_t<Handler>, TaskSetupHandler>) {
if (!handler)
return {}; // User passed {} for the setup handler.
}
return [handler = std::forward<Handler>(handler)](TaskAdapterPtr voidAdapter) {
// R, V stands for: Setup[R]esult, [V]oid
constexpr bool isR = QtTaskTree::isInvocable<SetupResult, Handler, Task &>();
constexpr bool isV = QtTaskTree::isInvocable<void, Handler, Task &>();
static_assert(isR || isV,
"Task setup handler needs to take (Task &) as an argument and has to return void or "
"SetupResult. The passed handler doesn't fulfill these requirements.");
Task *task = static_cast<TaskAdapter *>(voidAdapter)->task.get();
if constexpr (isR)
return std::invoke(handler, *task);
std::invoke(handler, *task);
return SetupResult::Continue;
};
}
template <typename Handler>
static TaskAdapterDoneHandler wrapDone(Handler &&handler) {
if constexpr (std::is_same_v<std::decay_t<Handler>, TaskDoneHandler>) {
if (!handler)
return {}; // User passed {} for the done handler.
}
return [handler = std::forward<Handler>(handler)](TaskAdapterPtr voidAdapter,
DoneWith result) {
constexpr bool isDoneResultType = std::is_same_v<std::decay_t<Handler>, DoneResult>;
// R, B, V, T, D stands for: Done[R]esult, [B]ool, [V]oid, [T]ask, [D]oneWith
constexpr bool isRTD = QtTaskTree::isInvocable<DoneResult, Handler, const Task &, DoneWith>();
constexpr bool isRT = QtTaskTree::isInvocable<DoneResult, Handler, const Task &>();
constexpr bool isRD = QtTaskTree::isInvocable<DoneResult, Handler, DoneWith>();
constexpr bool isR = QtTaskTree::isInvocable<DoneResult, Handler>();
constexpr bool isBTD = QtTaskTree::isInvocable<bool, Handler, const Task &, DoneWith>();
constexpr bool isBT = QtTaskTree::isInvocable<bool, Handler, const Task &>();
constexpr bool isBD = QtTaskTree::isInvocable<bool, Handler, DoneWith>();
constexpr bool isB = QtTaskTree::isInvocable<bool, Handler>();
constexpr bool isVTD = QtTaskTree::isInvocable<void, Handler, const Task &, DoneWith>();
constexpr bool isVT = QtTaskTree::isInvocable<void, Handler, const Task &>();
constexpr bool isVD = QtTaskTree::isInvocable<void, Handler, DoneWith>();
constexpr bool isV = QtTaskTree::isInvocable<void, Handler>();
static_assert(isDoneResultType || isRTD || isRT || isRD || isR
|| isBTD || isBT || isBD || isB
|| isVTD || isVT || isVD || isV,
"Task done handler should be a function taking (const Task &, DoneWith), "
"(const Task &), (DoneWith) or (void) as arguments and returning void, bool or "
"DoneResult. Alternatively, 'handler' may be an instance of DoneResult. "
"The passed handler doesn't fulfill these requirements.");
if constexpr (isDoneResultType)
return handler;
[[maybe_unused]] Task *task = static_cast<TaskAdapter *>(voidAdapter)->task.get();
if constexpr (isRTD)
return std::invoke(handler, *task, result);
if constexpr (isRT)
return std::invoke(handler, *task);
if constexpr (isRD)
return std::invoke(handler, result);
if constexpr (isR)
return std::invoke(handler);
if constexpr (isBTD)
return toDoneResult(std::invoke(handler, *task, result));
if constexpr (isBT)
return toDoneResult(std::invoke(handler, *task));
if constexpr (isBD)
return toDoneResult(std::invoke(handler, result));
if constexpr (isB)
return toDoneResult(std::invoke(handler));
if constexpr (isVTD)
std::invoke(handler, *task, result);
else if constexpr (isVT)
std::invoke(handler, *task);
else if constexpr (isVD)
std::invoke(handler, result);
else if constexpr (isV)
std::invoke(handler);
return toDoneResult(result == DoneWith::Success);
};
}
};
class Q_TASKTREE_EXPORT QTaskTree : public QObject
{
Q_OBJECT
Q_DECLARE_PRIVATE(QTaskTree)
public:
QTaskTree() : QTaskTree(nullptr) {}
explicit QTaskTree(QObject *parent);
explicit QTaskTree(const Group &recipe, QObject *parent = nullptr);
~QTaskTree() override;
void setRecipe(const Group &recipe);
void start();
void cancel();
bool isRunning() const;
// Helper methods. They execute a local event loop with ExcludeUserInputEvents.
// The passed future is used for listening to the cancel event.
// Don't use it in main thread. To be used in non-main threads or in auto tests.
DoneWith runBlocking();
static DoneWith runBlocking(const Group &recipe);
#if QT_CONFIG(future)
DoneWith runBlocking(const QFuture<void> &future);
static DoneWith runBlocking(const Group &recipe, const QFuture<void> &future);
#endif
qsizetype asyncCount() const;
qsizetype taskCount() const;
qsizetype progressMaximum() const { return taskCount(); }
qsizetype progressValue() const; // all finished / skipped / stopped tasks, groups itself excluded
template <typename StorageStruct, typename Handler>
void onStorageSetup(const Storage<StorageStruct> &storage, Handler &&handler) {
static_assert(std::is_invocable_v<std::decay_t<Handler>, StorageStruct &>,
"Storage setup handler needs to take (Storage &) as an argument. "
"The passed handler doesn't fulfill this requirement.");
setupStorageHandler(storage,
wrapHandler<StorageStruct>(std::forward<Handler>(handler)), {});
}
template <typename StorageStruct, typename Handler>
void onStorageDone(const Storage<StorageStruct> &storage, Handler &&handler) {
static_assert(std::is_invocable_v<std::decay_t<Handler>, const StorageStruct &>,
"Storage done handler needs to take (const Storage &) as an argument. "
"The passed handler doesn't fulfill this requirement.");
setupStorageHandler(storage, {},
wrapHandler<const StorageStruct>(std::forward<Handler>(handler)));
}
Q_SIGNALS:
void started();
void done(QtTaskTree::DoneWith result);
void asyncCountChanged(qsizetype count);
void progressValueChanged(qsizetype value); // updated whenever task finished / skipped / stopped
protected:
bool event(QEvent *event) override;
private:
void setupStorageHandler(const StorageBase &storage,
const StorageBase::StorageHandler &setupHandler,
const StorageBase::StorageHandler &doneHandler);
template <typename StorageStruct, typename Handler>
StorageBase::StorageHandler wrapHandler(Handler &&handler) {
return [handler](void *voidStruct) {
auto *storageStruct = static_cast<StorageStruct *>(voidStruct);
std::invoke(handler, *storageStruct);
};
}
};
class QTaskTreeTaskAdapter
{
public:
Q_TASKTREE_EXPORT void operator()(QTaskTree *task, QTaskInterface *iface) const;
};
class QTimeoutTaskAdapter final
{
public:
QTimeoutTaskAdapter() = default;
Q_TASKTREE_EXPORT ~QTimeoutTaskAdapter();
Q_TASKTREE_EXPORT void operator()(std::chrono::milliseconds *task, QTaskInterface *iface);
private:
Q_DISABLE_COPY_MOVE(QTimeoutTaskAdapter)
std::optional<size_t> m_timerId = std::nullopt;
};
using QTaskTreeTask = QCustomTask<QTaskTree, QTaskTreeTaskAdapter>;
using QTimeoutTask = QCustomTask<std::chrono::milliseconds, QTimeoutTaskAdapter>;
} // namespace QtTaskTree
QT_END_NAMESPACE
#endif // QTASKTREE_QTASKTREE_H