13.1. OMPT Start

There are three steps an OpenMP implementation takes to activate a tool. This section explains how the tool and an OpenMP implementation interact to accomplish tool activation.

Step 1. Determine Whether to Initialize

A tool is activated by the OMPT interface when it returns a non-NULL pointer to an ompt_start_tool_result_t structure on a call to ompt_start_tool by the OpenMP implementation. There are three ways that a tool can provide a definition of ompt_start_tool to an OpenMP implementation: (1) Statically linking the tool’s definition of ompt_start_tool into an OpenMP application. (2) Introducing a dynamically linked library that includes the tool’s definition of ompt_start_tool into the application’s address space. (3) Providing the name of a dynamically linked library appropriate for the architecture and operating system used by the application in the tool-libraries-var ICV.

Step 2. Initializing a First-Party tool

If a tool-provided implementation of ompt_start_tool returns a non-NULL pointer to an ompt_start_tool_result_t structure, the OpenMP implementation will invoke the tool initializer specified in this structure prior to the occurrence of any OpenMP event.

Step 3. Monitoring Activity on the Host

To monitor execution of an OpenMP program on the host device, a tool’s initializer must register to receive notification of events that occur as an OpenMP program executes. A tool can register callbacks for OpenMP events using the runtime entry point known as ompt_set_callback, which has the following possible return codes: \hfill reak ompt_set_error, ompt_set_never, ompt_set_impossible, ompt_set_sometimes, ompt_set_sometimes_paired, ompt_set_always.

If the ompt_set_callback runtime entry point is called outside a tool’s initializer, registration of supported callbacks may fail with a return code 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. While this is a compromise, it is better than providing unique runtime entry points with precise type signatures to set and get the callback for each unique runtime entry point type signature.

---

To use the OMPT interface a tool must provide a globally-visible implementation of the ompt_start_tool function. The function returns a pointer to an ompt_start_tool_result_t structure that contains callback pointers for tool initialization and finalization as well as a data word, tool_data , that is to be passed by reference to these callbacks. A NULL return indicates the tool will not use the OMPT interface. The runtime execution of ompt_start_tool is triggered by the first OpenMP directive or OpenMP API routine call.

In the example below, the user-provided ompt_start_tool function performs a check to make sure the runtime OpenMP version that OMPT supports (provided by the omp_version argument) is identical to the OpenMP implementation (compile-time) version. Also, a NULL is returned to indicate that the OMPT interface is not used (no callbacks and tool data are specified).

Note: The omp-tools.h file is included.

//%compiler: clang
//%cflags: -fopenmp

/*
* name:       ompt_start.1
* type:       C
* version:    omp_5.0
*/
#include <stdio.h>
#include <omp.h>
#include <omp-tools.h>

ompt_start_tool_result_t *ompt_start_tool(
unsigned int omp_version,
const char *runtime_version
){
  if(omp_version != _OPENMP)
    printf("Warning: OpenMP runtime version (%i) "
           "does not match the compile time version (%i)"
           " for runtime identifying as %s\n",
           omp_version, _OPENMP, runtime_version);
  // Returning NULL will disable this as an OMPT tool,
  // allowing other tools to be loaded
  return NULL;
}

int main(void){
  printf("Running with %i threads\n", omp_get_max_threads());
  return 0;
}