QtTaskTree::QCustomTask Class
template <typename Task, typename Adapter, typename Deleter> class QtTaskTree::QCustomTask사용자 정의 작업 항목을 선언하고 해당 설정 및 완료 핸들러를 정의하는 데 사용되는 클래스 템플릿입니다. 더 보기...
| 헤더: | #include <qtasktree.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS TaskTree) target_link_libraries(mytarget PRIVATE Qt6::TaskTree) |
| qmake: | QT += tasktree |
| 다음부터: | Qt 6.11 |
| 상속: | QtTaskTree::ExecutableItem |
| 상태: | 기술 미리보기 |
이 클래스는 기술 미리보기 단계에 있으며 변경될 수 있습니다.
참고: 이 클래스의 모든 함수는 재입력이 가능합니다.
공개 유형
공개 함수
| QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always) |
관련 비멤버
| QBarrierTask | |
| QNetworkReplyWrapperTask | |
| QProcessTask | |
| QTaskTreeTask | |
| QTcpSocketWrapperTask | |
| QThreadFunctionTask | |
| QTimeoutTask |
상세 설명
작업 트리 레시피 내의 사용자 지정 작업 항목을 설명합니다.
사용자 정의 작업 이름은 주어진 ` Task`, ` Adapter ` 및 ` Deleter`을 사용하여 `QCustomTask` 템플릿을 통해 고유한 이름으로 별칭이 지정됩니다. 예를 들어, ` QThreadFunctionTask<T>`는 ` QThreadFunction<T>`를 연관된 작업 클래스로 사용하도록 정의된 `QCustomTask`에 대한 별칭입니다. 다음 표에는 TaskTree 라이브러리가 제공하는 사용자 정의 작업과 관련 작업 클래스가 포함되어 있습니다:
| 별칭이 지정된 태스크 이름 | 연관된 작업 클래스 | 간략한 설명 |
|---|---|---|
| QBarrierTask | QBarrier | 어웨이터 태스크를 시작합니다. |
| QThreadFunctionTask<ReturnType> | QThreadFunction<반환 유형> | 비동기 작업을 시작합니다. 별도의 스레드에서 실행됩니다. |
| QProcessTask | QProcess | 프로세스를 시작합니다. |
| QNetworkReplyWrapperTask | QNetworkReplyWrapper | 네트워크 쿼리를 전송합니다. |
| QTaskTreeTask | QTaskTree | 중첩된 작업 트리를 시작합니다. |
| QTcpSocketWrapperTask | QTcpSocketWrapper | TCP 연결을 설정합니다. |
| QTimeoutTask | std::chrono::milliseconds | 타이머를 시작합니다. |
Task 템플릿 매개변수는 필수이며, 레시피의 일부인 경우 실행 중인 QTaskTree 가 어떤 유형의 Task 를 인스턴스화할지 지정합니다. Task 유형은 기본 생성 가능해야 합니다.
Adapter 템플릿 인자는 선택 사항입니다. QDefaultTaskAdapter<Task>가 Task 유형을 적용하는 데 문제가 없다면 생략할 수 있습니다. 그렇지 않은 경우, 특정 Task 에 대한 Adapter 는 다음 형식을 가져야 합니다:
class Adapter
{
public:
void operator()(Task *task, QTaskInterface *iface) { ... }
};task 를 시작하려면 위의 operator()를 구현하고, 작업이 완료되면 전달된 iface 에 대해 QTaskInterface::reportDone() 메서드를 호출하십시오.
전달된 ` Task `와 ` QTaskInterface `는 ` Adapter`보다 오래 유지된다는 점이 보장됩니다. 필요한 경우, ` Adapter `의 소멸자에서도 전달된 ` Task`에 여전히 접근할 수 있습니다.
자세한 내용은 QTaskInterface 을 참조하십시오.
Deleter 템플릿 인수는 선택 사항입니다. 기본적으로 std::default_delete<Task> 가 사용됩니다. 사용자 정의 Deleter 는 실행 중인 Task 의 소멸자가 호출자 스레드를 잠재적으로 차단할 수 있는 경우에 유용합니다. 사용자 정의 델리터는 차단하는 대신 실행 중인 태스크를 별도의 스레드로 이동시켜 그곳에서 차단 소멸을 구현할 수 있습니다. 이러한 방식으로, 차단되는 소멸자를 가진 실행 중인 태스크를 (호출자 스레드 관점에서 볼 때) 빠르게 소멸시킬 수 있습니다.
QTaskInterface도 참조하십시오 .
멤버 유형 문서
[alias] QCustomTask::TaskDoneHandler
std::function<QtTaskTree::DoneResult(const Task &, QtTaskTree::DoneWith)> 또는 DoneResult 의 유형 별칭입니다.
TaskDoneHandler는 사용자 정의 태스크 요소 생성자의 선택적 인자입니다. 위의 시그니처를 갖는 함수는 태스크 완료 핸들러로 전달될 경우, 태스크 실행이 완료된 후 및 실행의 최종 결과가 상위 그룹에 보고되기 전에 실행 중인 태스크 트리에서 호출됩니다.
핸들러 본문 내에서 완료된 태스크의 최종 데이터를 가져올 수 있습니다. 스토리지(storage)를 포함한 추가 매개변수는 람다 캡처를 통해 핸들러로 전달될 수 있습니다. 또한 태스크가 반환 값으로 종료되어야 하는지, 아니면 최종 결과를 조정해야 하는지를 동적으로 결정할 수도 있습니다.
` DoneWith ` 인수는 선택 사항이며, 완료 핸들러에서 이를 생략할 수 있습니다. 이 인수가 제공되면, 상위 그룹에 보고될 태스크의 최종 결과에 대한 정보를 담게 됩니다.
완료된 태스크에서 데이터를 읽을 계획이 없다면, ` const Task & ` 인수를 생략할 수 있습니다.
반환되는 ` DoneResult ` 값은 선택 사항이며, 핸들러는 대신 ` void `를 반환할 수도 있습니다. 이 경우, 태스크의 최종 결과는 ` DoneResult ` 인자가 지정한 값과 동일해집니다. 핸들러가 ` DoneResult ` 값을 반환하면, 태스크의 최종 결과는 반환된 값을 통해 done 핸들러 본문 내에서 조정될 수 있습니다.
DoneResult 유형의 TaskDoneHandler의 경우, 추가 처리는 실행되지 않으며 태스크는 전달된 DoneResult 값으로 무조건 종료됩니다.
QCustomTask(), TaskSetupHandler, GroupDoneHandler도 참조하십시오 .
[alias] QCustomTask::TaskSetupHandler
std::function<SetupResult(Task &)> 의 타입 별칭입니다.
TaskSetupHandler는 사용자 정의 태스크 요소 생성자의 선택적 인자입니다. 위 시그니처를 갖는 함수는 태스크 설정 핸들러로 전달될 경우, 태스크가 생성된 후 시작되기 전에 실행 중인 태스크 트리에서 호출됩니다.
핸들러 본문 내에서 필요에 따라 태스크를 구성할 수 있습니다. 스토리지 등을 포함한 추가 매개변수는 람다 캡처를 통해 핸들러로 전달될 수 있습니다. 태스크를 시작할지, 성공 또는 오류와 함께 건너뛸지 동적으로 결정할 수 있습니다.
참고: 시작 핸들러 내부에서 직접 태스크를 시작하지마십시오 . 이는 ` QTaskTree`에 맡겨야 하며, 그렇지 않을 경우 동작이 정의되지 않습니다. ` QTaskTree `는 ` QCustomTask`의 `<Task, Adapter, Deleter>` 생성자에 전달된 `Adapter` 템플릿 매개변수 덕분에 태스크를 시작하는 방법을 이미 알고 있습니다.
핸들러의 반환 값은 핸들러 호출이 완료된 후 실행 중인 태스크 트리가 어떻게 진행해야 하는지를 지시합니다. SetupResult::Continue 의 반환 값은 태스크 트리에 실행을 계속하도록, 즉 연관된 Task 를 실행하도록 지시합니다. SetupResult::StopWithSuccess 또는 SetupResult::StopWithError 의 반환 값은 태스크 트리에 태스크 실행을 건너뛰고 각각 성공 또는 오류로 즉시 종료하도록 지시합니다.
반환 유형이 SetupResult::StopWithSuccess 또는 SetupResult::StopWithError 인 경우, 해당 태스크의 완료 핸들러(지정된 경우)는 이후에 호출되지 않습니다.
사용자 정의 태스크의 생성자는 std::function<void(Task &)> 의 축약형인 함수도 받아들이며, 이 경우 반환 값은 void 입니다. 이 경우 반환 값은 SetupResult::Continue 로 간주됩니다.
QCustomTask(), TaskDoneHandler 및 GroupSetupHandler도 참조하십시오 .
멤버 함수 문서
[explicit] template <
typename SetupHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskSetupHandler,
typename DoneHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskDoneHandler,
std::enable_if_t<!std::is_same_v<q20::remove_cvref_t<SetupHandler>, QCustomTask<Task, Adapter, Deleter>>, bool> = true
>
QCustomTask::QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)
QCustomTask 인스턴스를 생성하고, setup 및 done 핸들러를 해당 태스크에 연결합니다. 실행 중인 작업 트리가 작업을 시작하려고 할 때, 관련 Task 객체를 인스턴스화하고, 생성된 작업에 대한 참조와 함께 setup 핸들러를 호출한 후 작업을 시작합니다. 실행 중인 작업이 완료되면, 작업 트리는 생성된 작업에 대한 const 참조와 함께 done 핸들러를 호출합니다.
전달된 setup 핸들러는 TaskSetupHandler 유형입니다. 예를 들어:
static void parseAndLog(const QString &input);
...
const QString input = ...;
const auto onFirstSetup = [input](QThreadFunction<void> &task) {
if (input == "Skip")
return SetupResult::StopWithSuccess; // This task won't start, the next one will
if (input == "Error")
return SetupResult::StopWithError; // This task and the next one won't start
task.setThreadFunctionData(parseAndLog, input);
// This task will start, and the next one will start after this one finished with success
return SetupResult::Continue;
};
const auto onSecondSetup = [input](QThreadFunction<void> &task) {
task.setThreadFunctionData(parseAndLog, input);
};
const Group group {
QThreadFunctionTask<void>(onFirstSetup),
QThreadFunctionTask<void>(onSecondSetup)
};done 핸들러는 TaskDoneHandler 유형입니다. 기본적으로 done 핸들러는 작업이 완료될 때마다 호출됩니다. 핸들러가 성공, 실패 또는 취소된 실행 시에만 호출되도록 하려면 callDone 인자에 기본값이 아닌 값을 전달하십시오.
TaskSetupHandler 및 TaskDoneHandler도 참조하십시오 .
관련 비멤버
[alias] QBarrierTask
레시피 내에서 사용할 QCustomTask<QBarrier>에 대한 타입 별칭입니다.
[alias] QNetworkReplyWrapperTask
레시피 내에서 사용할 QCustomTask<QNetworkReplyWrapper>에 대한 타입 별칭입니다.
[alias] QProcessTask
레시피 내에서 사용할 수 있도록 QProcessTaskDeleter 를 사용하여 QCustomTask<QProcess>의 유형 별칭을 정의합니다.
[alias] QTaskTreeTask
레시피 내에서 사용하기 위한 QCustomTask<QTaskTree>의 타입 별칭입니다.
[alias] QTcpSocketWrapperTask
레시피 내에서 사용할 QCustomTask<QTcpSocketWrapper>에 대한 타입 별칭입니다.
[alias] template <typename ResultType> QThreadFunctionTask
레시피 내에서 사용하기 위한 QCustomTask<QThreadFunction<ResultType>>에 대한 타입 별칭으로, 여기서 ResultType 은 스레드 함수의 반환 타입을 지정합니다.
[alias] QTimeoutTask
레시피 내에서 사용할 수 있는 QCustomTask<std::chrono::milliseconds> 의 타입 별칭입니다. std::chrono::milliseconds 는 타임아웃 기간을 설정하는 데 사용됩니다. 기본 타임아웃은 std::chrono::milliseconds::zero() 이며, 즉 QTimeoutTask는 제어권이 실행 중인 이벤트 루프로 돌아오자마자 종료됩니다.
사용 예:
using namespace std::chrono;
using namespace std::chrono_literals;
const auto onSetup = [](milliseconds &timeout) { timeout = 1000ms; }
const auto onDone = [] { qDebug() << "Timed out."; }
const Group root {
QTimeoutTask(onSetup, onDone)
};timeoutTask()도 참조하십시오 .
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
