QtTaskTree::QTaskTree Class

メンバ関数のドキュメント

[explicit] QTaskTree::QTaskTree(QObject *parent)

指定されたparent を用いて、空のタスクツリーを構築します。setRecipe() を使用すると、タスクツリーがタスクをどのように実行すべきか、また完了したタスクをどのように処理すべきかについて、宣言的な記述を渡すことができます。

空のタスクツリーの起動はノーオペレーション（何もしない）であり、関連する警告メッセージが表示されます。

setRecipe() およびstart()も参照してください 。

[explicit] QTaskTree::QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr)

指定されたrecipe およびparent を用いてタスクツリーを構築します。タスクツリーが起動されると、recipe 内に含まれるタスクを実行し、渡された記述に従って完了したタスクを処理します。

setRecipe() およびstart()も参照してください 。

[override virtual noexcept] QTaskTree::~QTaskTree()

タスクツリーを破棄します。

タスクツリーが破棄中に実行中の場合、実行中のすべてのタスクを直ちにキャンセルします。 この場合、グループやタスクのdoneハンドラやonStorageDone()ハンドラを含め、いかなるハンドラも呼び出されません。また、タスクツリーはデストラクタからいかなるシグナルも発信せず、done()やprogressValueChanged()シグナルさえも発信しません。この挙動は常に信頼できます。実行中のタスクツリーを破棄することは完全に安全です。

実行中のタスクツリーを破棄することは、一般的なパターンです。使用されているタスクが非ブロッキングな方法でデストラクタを実装している限り、現在実行中のタスクが終了するのを待つことなく、破棄処理が迅速に実行されることが保証されています。

cancel()も参照してください 。

qsizetype QTaskTree::asyncCount() const

非同期の呼び出しチェーンの現在の実数を返します。

返される値は、タスクツリーの実行中に制御が呼び出し元のイベントループに戻った回数を示します。 初期値は0 です。タスクツリーの実行が完全に同期的に終了した場合、この値は0 のままとなります。タスクツリーに、start()の呼び出し中に正常に開始された非同期タスクが含まれている場合、この値はstart()の呼び出しが終了する直前に1 にインクリメントされます。 その後、非同期タスクが終了し、可能な継続が開始されると、この値は再びインクリメントされます。このインクリメントは、タスクツリーが終了するまで続きます。タスクツリーがdone()シグナルを発生させると、インクリメントは停止します。この値がインクリメントされるたびに、asyncCountChanged()シグナルが発生します。

asyncCountChanged()も参照してください 。

[signal] void QTaskTree::asyncCountChanged(qsizetype count)

このシグナルは、実行中のタスクツリーが呼び出し元のイベントループに制御を戻そうとする際に発せられます。タスクツリーが開始されると、このシグナルはcount の値が0 である状態で発せられ、その後、asyncCount()の値が更新されるたびに、count の値が更新された状態で発せられます。 送信されるすべてのシグナル（0 の値を持つ最初のシグナルを除く）は、送信後もタスクツリーが非同期で実行され続けていることを保証します。

asyncCount()も参照してください 。

void QTaskTree::cancel()

実行中のタスクツリーの実行を中止します。

実行中のすべてのタスクを直ちにキャンセルします。実行中のすべてのタスクおよびグループはエラーで終了し、DoneWith::Cancel を使用してそれぞれのdoneハンドラが呼び出されます。ストレージのonStorageDone()ハンドラも呼び出されます。また、progressValueChanged()シグナルも送信されます。この動作は常に信頼できます。

cancel()関数は同期的に実行されるため、cancel()の呼び出し後、すべての実行中のタスクは終了し、ツリーはすでにキャンセルされた状態になります。使用されているタスクが非ブロッキングな方法でデストラクタを実装している限り、cancel()は現在実行中のタスクの終了を待つブロックなしで、迅速に実行されることが保証されています。

タスクツリーが空の場合、つまりデフォルトコンストラクタで構築された場合、cancel() の呼び出しはノーオペレーションとなり、関連する警告メッセージが表示されます。

それ以外の場合、つまりタスクツリーが起動されていないときは、cancel() の呼び出しは無視されます。

~QTaskTree()も参照してください 。

[signal] void QTaskTree::done(QtTaskTree::DoneWith result)

このシグナルは、タスクツリーが終了した際に、実行の最終的なresult を渡して発信されます。このシグナルが発信された後、タスクツリーはハンドラを呼び出すことも、シグナルを発信することもありません。

started()も参照してください 。

[override virtual protected] bool QTaskTree::event(QEvent *event)

QObject::event(QEvent *e) を再実装します。

bool QTaskTree::isRunning() const

タスクツリーが現在実行中の場合は `true ` を返し、そうでない場合は `false` を返します。

start() およびcancel()も参照してください 。

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageDone(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

storage 向けに、handler によるストレージをインストールし、実行中のタスクツリーから最終データを動的に取得できるようにします。

StorageHandler は、StorageStruct インスタンスへのconst 参照を受け取ります：

staticQByteArray load(constQString&fileName) {...}

Storage<QByteArray>storage;

const autoonLoaderSetup= [](QThreadFunction<QByteArray> &task) {
    task.setThreadFunctionData(&load, "foo.txt");
};
const autoonLoaderDone= [storage](constQThreadFunction<QByteArray> &task) {
    *storage =task.result();
};

constGroup root {
    storage,
    QThreadFunctionTask(onLoaderSetup,onLoaderDone,CallDoneFlag::OnSuccess)
};

QTaskTree taskTree(root);
autocollectStorage= [](constQByteArray&storage){
    qDebug() << "final content" << storage;
};
taskTree.onStorageDone(storage,collectStorage);
taskTree.start();

実行中のタスクツリーが、storage が配置されているGroup を離れる直前に、StorageStruct インスタンスを破棄します。StorageStruct インスタンスが破棄される直前、かつこのグループから呼び出し可能なすべてのハンドラが呼び出された後、タスクツリーは渡されたhandler を呼び出します。これにより、指定されたストレージの最終的な内容を動的に読み取り、タスクツリーの外でさらに処理を行うことが可能になります。

このハンドラは、実行中のツリーがキャンセルされた場合にも呼び出されます。ただし、実行中のツリーが破棄された場合には呼び出されません。

onStorageSetup()も参照してください 。

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageSetup(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

storage 向けに、初期データを実行中のタスクツリーに動的に渡すためのストレージ設定 `handler ` をインストールします。

StorageHandler は、StorageStruct インスタンスへの参照を受け取ります：

static void save(const QString &fileName, const QByteArray &array) { ... }

Storage<QByteArray> storage;

const auto onSaverSetup = [storage](QThreadFunction<QByteArray> &task) {
    task.setThreadFunctionData(&save, "foo.txt", *storage);
};

const Group root {
    storage,
    QThreadFunctionTask(onSaverSetup)
};

QTaskTree taskTree(root);
auto initStorage = [](QByteArray &storage){
    storage = "initial content";
};
taskTree.onStorageSetup(storage, initStorage);
taskTree.start();

実行中のタスクツリーが、storage が配置されているグループに入ると、そのグループ内で使用可能なStorageStruct インスタンスを作成します。StorageStruct インスタンスが作成された直後、かつこのグループのハンドラが呼び出される前に、タスクツリーは渡されたhandler を呼び出します。これにより、指定されたストレージの初期コンテンツを動的に設定できるようになります。その後、いずれかのグループのハンドラが呼び出されると、タスクツリーは作成・初期化済みのストレージを有効化し、どのグループのハンドラ内でも利用できるようにします。

onStorageDone()も参照してください 。

qsizetype QTaskTree::progressMaximum() const

progressValue() の最大値を返します。

関連項目： progressValue()。

qsizetype QTaskTree::progressValue() const

現在の進行状況の値を返します。この値は、0 からprogressMaximum( ) の範囲にあります。

返される数値は、タスクツリーの実行中に、すでに完了、キャンセル、またはスキップされたタスクの数を示します。タスクツリーが開始されると、この数値は `0` に設定されます。タスクツリーが終了すると、この数値は常に `progressMaximum()` になります。

progressMaximum() およびprogressValueChanged()も参照してください 。

[signal] void QTaskTree::progressValueChanged(qsizetype value)

このシグナルは、実行中のタスクツリーが終了、キャンセル、または一部のタスクをスキップしたときに発生します。value は、完了、キャンセル、またはスキップされたタスクの現在の総数を返します。タスクツリーが開始され、started()シグナルが発信された後、このシグナルは初期のvalue として0 で発信されます。タスクツリーが終了しようとしており、done()シグナルが発信される前に、このシグナルは最終的なvalue としてprogressMaximum()で発信されます。

progressValue() およびprogressMaximum()も参照してください 。

QtTaskTree::DoneWith QTaskTree::runBlocking()

QEventLoop::ExcludeUserInputEvents を使用してローカルイベントループを実行し、タスクツリーを起動します。

タスクツリーが正常に完了した場合はDoneWith::Success を返し、そうでない場合はDoneWith::Error を返します。

start()も参照してください 。

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe)

渡されたrecipe を使用して一時的なタスクツリーを構築し、ブロック方式で実行します。

タスクツリーが正常に完了した場合はDoneWith::Success を返し、そうでない場合はDoneWith::Error を返します。

start()も参照してください 。

QtTaskTree::DoneWith QTaskTree::runBlocking(const QFuture<void> &future)

渡されたfuture は、キャンセルイベントをリッスンするために使用されます。タスクツリーがキャンセルされると、このメソッドは渡されたfuture をキャンセルします。

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe, const QFuture<void> &future)

引数として渡されたfuture は、キャンセルイベントをリッスンするために使用されます。タスクツリーがキャンセルされると、このメソッドは引数として渡されたfuture をキャンセルします。

void QTaskTree::setRecipe(const QtTaskTree::Group &recipe)

タスクツリーに対して、指定されたrecipe を設定します。タスクツリーが起動されると、recipe 内に含まれるタスクを実行し、渡された記述に従って完了したタスクを処理します。

関連項目： QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr) およびstart()。

void QTaskTree::start()

タスクツリーを開始します。

setRecipe() またはコンストラクタを使用して、タスクツリーが包含するタスクを実行し、完了したタスクを処理するための宣言的な記述を設定します。

タスクツリーが空の場合、つまりデフォルトのコンストラクタで構築された場合、start() の呼び出しはノーオペレーションとなり、関連する警告メッセージが出力されます。

それ以外の場合、つまりタスクツリーがすでに実行中の場合は、start() の呼び出しは無視され、関連する警告メッセージが出力されます。

それ以外の場合は、タスクツリーが起動されます。

開始されたタスクツリーは、たとえばメイングループの start ハンドラが `SetupResult::StopWithError` を返した場合など、同期的に終了することがあります。このため、`start()` を呼び出す前に、`done` シグナルへの接続を確立しておく必要があります。`start()` の呼び出し後にタスクツリーがまだ実行中であるかどうかを検出するには、`isRunning()` を使用してください。

タスクツリーの実装は、実行中のイベントループに依存しています。このメソッドを呼び出す際は、QEventLoop 、QCoreApplication 、またはそのサブクラスのいずれかが実行中（または実行されようとしている）であることを確認してください。

QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr)、setRecipe()、isRunning()、およびcancel()も参照してください 。

[signal] void QTaskTree::started()

このシグナルは、タスクツリーが起動されたときに発火します。このシグナルの発火に続いて、初期値が `0 ` である `progressValueChanged()` シグナルが同期的に発火します。

start() およびdone()も参照してください 。

qsizetype QTaskTree::taskCount() const

保存されたレシピに含まれる非同期タスクの数を返します。

関連項目： setRecipe() およびprogressMaximum()。