---

3.14.1 omp_control_tool – pass commands to a tool ¶

Description:

The omp_control_tool routine can be used to pass commands to a tool. The values for modifier and arg are specific for the particular tool; for Fortran, arg is NULL. The following predefined values for command are supported by all tools:

• omp_control_tool_start: Request that monitoring is started or resumed; it has no effect if monitoring is already on or was turned off permanently.
• omp_control_tool_pause: Request that monitoring is temporarily paused; it has no effect if monitoring is already paused or stopped.
• omp_control_tool_flush: Request flushing of any buffered data, independently whether monitoring is currently active.
• omp_control_tool_end: Request that monitoring is turned off permanently, flushing all output and terminating the tool.

For the listed standard commands, the modifier and arg arguments are ignored by the tool.

Negative return values indicate that the tool has not processed the command; in particular, the return value is omp_control_tool_notool if OMPT is inactive and no tool is active; if it is active but no callback is registered for the tool-control event, omp_control_tool_nocallback is returned. On success, omp_control_tool_success is returned and omp_control_tool_ignored indicates that the tool received the command but ignored it. Positive return values greater than 64 are tool specific.

GCC implements the OpenMP 6.0 version of this function for C and C++, which is not compatible with its type signature in previous versions of the OpenMP specification. In older versions, the type int was used for the command argument in place of the enumerated type omp_control_tool_t; the return type likewise changed from int to omp_control_tool_result_t.

C/C++:

Prototype:	omp_control_tool_result_t omp_control_tool(
	omp_control_tool_t command, int modifier, void *arg)

Fortran:

Interface:	integer (kind=omp_control_tool_result_kind) &
	function omp_control_tool(command, modifier)
	integer (kind=omp_control_tool_kind) command
	integer :: modifier

Note:

In Fortran code, an argument can passed to the tool by creating a C wrapper function in the user code; however, as in GCC—and likely in most implementations—the C/C++ and Fortran use compatible integer kinds/types, it is simpler to add an INTERFACE block such as the following one.

interface
  ! Or to permit using 'omp_control_tool' for both the two and
  ! three argument version, use a generic interface; the two-
  ! argument version comes from the 'omp_lib' module.
!interface omp_control_tool

  integer(omp_control_tool_result_kind) &
  function omp_control_tool_arg (command, modifier, arg) &
      bind(C, name="omp_control_tool")
    use omp_lib
    use iso_c_binding
    integer(kind=omp_control_tool_kind), VALUE :: command
    integer(c_int) :: modifier

    ! Either
    type(c_ptr), VALUE :: arg
    ! or
    !type(*), dimension(*) :: arg ! Note:
    ! Avoid type(*) for 'type(c_ptr)' actual arguments as this will pass a
    ! reference to the C pointer and not the C pointer itself.
  end
end interface

Reference:

OpenMP specification v6.0, Section 31.1