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.
For callbacks listed in Table 4.2, 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 listed in Table 4.3, the ompt_set_callback runtime entry may return any non-error code. 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: | Callbacks for which ompt_set_callback Must Return ompt_set_always |
| Callback name |
| 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_emi |
| ompt_callback_target_data_op |
| ompt_callback_target_data_op_emi |
| ompt_callback_target_submit |
| ompt_callback_target_submit_emi |
| ompt_callback_control_tool |
| ompt_callback_device_initialize |
| ompt_callback_device_finalize |
| ompt_callback_device_load |
| ompt_callback_device_unload |
| Table 4.3: | Callbacks for which ompt_set_callback May Return Any Non-Error Code |
| Callback name |
| ompt_callback_sync_region_wait |
| ompt_callback_mutex_released |
| ompt_callback_dependences |
| ompt_callback_task_dependence |
| ompt_callback_work |
| ompt_callback_master // (deprecated) |
| ompt_callback_masked |
| ompt_callback_target_map |
| ompt_callback_target_map_emi |
| 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 |
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.