HOME
| OPENMP API Specification: Version 5.1 November 2020

4.2.4  Monitoring Activity on the Host with OMPT

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.

Cross References