To monitor the execution of an OpenMP program on the host device, a tool initializer must register to receive notification of events that occur as an OpenMP program executes. A tool can use the ompt_set_callback runtime entry point to register callbacks for OpenMP events. The return codes for ompt_set_callback use the ompt_set_result_t enumeration type. If the ompt_set_callback runtime entry point is called outside a tool initializer, registration of supported callbacks may fail with a return value of ompt_set_error.
All callbacks registered with ompt_set_callback or returned by ompt_get_callback use the dummy type signature ompt_callback_t.
Table 4.2 shows the valid registration return codes of the ompt_set_callback runtime entry point with specific values of its event argument. For callbacks for which ompt_set_always is the only registration return code that is allowed, an OpenMP implementation must guarantee that the callback will be invoked every time that a runtime event that is associated with it occurs. Support for such callbacks is required in a minimal implementation of the OMPT interface. For callbacks for which the ompt_set_callback runtime entry may return values other than ompt_set_always, whether an OpenMP implementation invokes a registered callback never, sometimes, or always is implementation-defined. If registration for a callback allows a return code of omp_set_never, support for invoking such a callback may not be present in a minimal implementation of the OMPT interface. The return code from registering a callback indicates the implementation-defined level of support for the callback.
| Table 4.2: | Valid Return Codes of ompt_set_callback |
| Return code abbreviation | N | S/P | A | |
| ompt_callback_thread_begin |
|
| * |
|
| ompt_callback_thread_end |
|
| * |
|
| ompt_callback_parallel_begin |
|
| * |
|
| ompt_callback_parallel_end |
|
| * |
|
| ompt_callback_task_create |
|
| * |
|
| ompt_callback_task_schedule |
|
| * |
|
| ompt_callback_implicit_task |
|
| * |
|
| ompt_callback_target |
|
| * |
|
| ompt_callback_target_data_op |
|
| * |
|
| ompt_callback_target_submit |
|
| * |
|
| ompt_callback_control_tool |
|
| * |
|
| ompt_callback_device_initialize |
|
| * |
|
| ompt_callback_device_finalize |
|
| * |
|
| ompt_callback_device_load |
|
| * |
|
| ompt_callback_device_unload |
|
| * |
|
| ompt_callback_sync_region_wait | * | * | * |
|
| ompt_callback_mutex_released | * | * | * |
|
| ompt_callback_dependences | * | * | * |
|
| ompt_callback_task_dependence | * | * | * |
|
| ompt_callback_work | * | * | * |
|
| ompt_callback_master | * | * | * |
|
| ompt_callback_target_map | * | * | * |
|
| ompt_callback_sync_region | * | * | * |
|
| ompt_callback_reduction | * | * | * |
|
| ompt_callback_lock_init | * | * | * |
|
| ompt_callback_lock_destroy | * | * | * |
|
| ompt_callback_mutex_acquire | * | * | * |
|
| ompt_callback_mutex_acquired | * | * | * |
|
| ompt_callback_nest_lock | * | * | * |
|
| ompt_callback_flush | * | * | * |
|
| ompt_callback_cancel | * | * | * |
|
| ompt_callback_dispatch | * | * | * |
|
| N = ompt_set_never | S = ompt_set_sometimes
| |||
| P = ompt_set_sometimes_paired | A = ompt_set_always
| |||
Two techniques reduce the size of the OMPT interface. First, in cases where events are naturally paired, for example, the beginning and end of a region, and the arguments needed by the callback at each endpoint are identical, a tool registers a single callback for the pair of events, with ompt_scope_begin or ompt_scope_end provided as an argument to identify for which endpoint the callback is invoked. Second, when a class of events is amenable to uniform treatment, OMPT provides a single callback for that class of events, for example, an ompt_callback_sync_region_wait callback is used for multiple kinds of synchronization regions, such as barrier, taskwait, and taskgroup regions. Some events, for example, ompt_callback_sync_region_wait, use both techniques.