Task API
一个
task(任务)
是一个特定线程执行的工作的一个逻辑单元。任务可以嵌套:因此,任务通常对应于函数、范围或 switch 语句中的一个 case 块。可使用 Task API(任务 API)将任务指派给线程。Task API(任务 API)并不启用一个线程来挂起当前任务并切换到另一个任务(任务切换),或者将一个任务移到另一个线程(任务窃取)。
一个任务实例代表一个特定线程在一段时间内执行的工作的一部分。在同一线程上,任务由
__itt_task_begin()
和 __itt_task_end()
加括弧定义。对 __itt_task_begin()
的调用会创建一个任务实例。这将成为该线程的当前任务实例。在同一线程上对 __itt_task_end()
的调用会结束当前任务实例。任务可有两种类型:简单型和重叠型。
简单任务隐式支持嵌入执行概念。也就是说,对
__itt_task_end()
的调用会结束最近对 __itt_task_begin()
的调用。例如,下述元代码是一个有效序列,“a”任务的执行时间包含“b”任务的执行时间:__itt_task_begin(a)
__itt_task_begin(b)
__itt_task_end(b)
__itt_task_end(a)
重叠任务的执行区域可能会重叠。例如,下述元代码是一个有效序列,“b”任务在“a”任务之后开始,可以在“a”任务完成后完成:
__itt_task_begin_overlapped(a)
__itt_task_begin_overlapped(b)
__itt_task_end_overlapped(a)
__itt_task_end_overlapped(b)
Task API 函数
要在线程上创建一个简单型任务实例,请使用以下函数:
void ITTAPI __itt_task_begin (const __itt_domain *domain,__itt_id taskid, __itt_id parentid, __itt_string_handle *name)
void ITTAPI __itt_task_begin_fn (const __itt_domain *domain,__itt_id taskid, __itt_id parentid, void* address)
void ITTAPI __itt_task_end (const __itt_domain *domain)
要在不同时钟域内创建一个简单型任务实例,请使用以下函数:
void ITTAPI __itt_task_begin_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name)
void ITTAPI __itt_task_begin_fn_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, void* fn)
void ITTAPI _itt_task_end_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp)
要在一个线程上创建重叠型任务实例,请使用以下函数:
void ITTAPI __itt_task_begin_overlapped(const __itt_domain* domain, __itt_id taskid, __itt_id parentid, __itt_string_handle* name)
void ITTAPI __itt_task_end_overlapped(const __itt_domain *domain, __itt_id taskid)
对于这些函数来说,变量
taskid
是必需的。要在不同时钟域中创建一个重叠型任务实例,请使用以下函数:
void ITTAPI __itt_task_begin_overlapped_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name)
void ITTAPI __itt_task_end_overlapped_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid)
对于这些函数来说,变量
taskid
是必需的。ITTAPI__itt_task_*
函数参数下表定义 Task API 基元中使用的参数。
类型
|
参数
|
描述
|
---|---|---|
[in] |
|
任务的域
|
[in] |
| 用户定义的 ID 对于所有任务实例是可选的,重叠型任务实例除外。 __itt_null 可用作未定义任务实例的默认值。任务 ID 用于定义任务实例之间的关系。备注 拥有不同域的任务不能使用同一 ID。 |
[in] |
| 可选参数。父实例 ID(任务所属的 ID),或者 __itt_null。 备注 拥有不同域的父实例不能使用同一 ID。 |
[in] |
|
任务名称
|
[in] |
|
可用来代替名称的函数地址。例如,利用调试符号信息,函数地址可以解析为函数名称。
|
[in] |
|
用户定义的时钟域
|
[in] |
|
针对相应时钟域的用户定义的时间戳
|
使用示例
以下代码片段创建一个域以及全域范围内的几个任务。
#include "ittnotify.h" void do_foo(double seconds); __itt_domain* domain = __itt_domain_create(__TEXT("MyTraces.MyDomain")); __itt_string_handle* shMyTask = __itt_string_handle_create(__TEXT("My Task")); __itt_string_handle* shMySubtask = __itt_string_handle_create(__TEXT("My SubTask")); void BeginFrame() { __itt_task_begin(domain, __itt_null, __itt_null, shMyTask); do_foo(1); } void DoWork() { __itt_task_begin(domain, __itt_null, __itt_null, shMySubtask); do_foo(1); __itt_task_end(domain); } void EndFrame() { do_foo(1); __itt_task_end(domain); } int main() { BeginFrame(); DoWork(); EndFrame(); return 0; }