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 handler)나 ` 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 참조를 인수로 받습니다:

static QByteArray load(const QString&fileName) {... }

Storage<QByteArray> storage;

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

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

QTaskTree taskTree(root);
auto collectStorage = [](const QByteArray&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() 호출은 무시되고 관련 경고 메시지가 출력됩니다.

그 외의 경우, 태스크 트리가 시작됩니다.

시작된 태스크 트리는, 예를 들어 메인 그룹의 시작 핸들러가 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()도 참조하십시오 .