typedef int (*ompt_enumerate_states_t) (
int current_state,
int *next_state,
const char **next_state_name
);
Entry points in the OMPT callback interface enable a tool to register callbacks for OpenMP events and to inspect the state of an OpenMP thread while executing in a tool callback or a signal handler. Pointers to these runtime entry points are obtained through the lookup function that is provided through the OMPT initializer.
SummaryThe ompt_enumerate_states_t type is the type signature of the ompt_enumerate_states runtime entry point, which enumerates the thread states that an OpenMP implementation supports.
DescriptionAn OpenMP implementation may support only a subset of the states defined by the ompt_state_t enumeration type. An OpenMP implementation may also support implementation-specific states. The ompt_enumerate_states runtime entry point, which has type signature ompt_enumerate_states_t, enables a tool to enumerate the supported thread states. When a supported thread state is passed as current_state, the runtime entry point assigns the next thread state in the enumeration to the variable passed by reference in next_state and assigns the name associated with that state to the character pointer passed by reference in next_state_name.
Whenever one or more states are left in the enumeration, the ompt_enumerate_states runtime entry point returns 1. When the last state in the enumeration is passed as current_state, ompt_enumerate_states returns 0, which indicates that the enumeration is complete.
Description of ArgumentsThe current_state argument must be a thread state that the OpenMP implementation supports. To begin enumerating the supported states, a tool should pass ompt_state_undefined as current_state. Subsequent invocations of ompt_enumerate_states should pass the value assigned to the variable passed by reference in next_state to the previous call. The value ompt_state_undefined is reserved to indicate an invalid thread state. ompt_state_undefined is defined as an integer with the value 0.
The next_state argument is a pointer to an integer in which ompt_enumerate_states returns the value of the next state in the enumeration.
The next_state_name argument is a pointer to a character string pointer through which ompt_enumerate_states returns a string that describes the next state.
Constraints on ArgumentsAny string returned through the next_state_name argument must be immutable and defined for the lifetime of a program execution.
SummaryThe ompt_enumerate_mutex_impls_t type is the type signature of the ompt_enumerate_mutex_impls runtime entry point, which enumerates the kinds of mutual exclusion implementations that an OpenMP implementation employs.
DescriptionMutual exclusion for locks, critical sections, and atomic regions may be implemented in several ways. The ompt_enumerate_mutex_impls runtime entry point, which has type signature ompt_enumerate_mutex_impls_t, enables a tool to enumerate the supported mutual exclusion implementations. When a supported mutex implementation is passed as current_impl, the runtime entry point assigns the next mutex implementation in the enumeration to the variable passed by reference in next_impl and assigns the name associated with that mutex implementation to the character pointer passed by reference in next_impl_name.
Whenever one or more mutex implementations are left in the enumeration, the ompt_enumerate_mutex_impls runtime entry point returns 1. When the last mutex implementation in the enumeration is passed as current_impl, the runtime entry point returns 0, which indicates that the enumeration is complete.
Description of ArgumentsThe current_impl argument must be a mutex implementation that an OpenMP implementation supports. To begin enumerating the supported mutex implementations, a tool should pass ompt_mutex_impl_none as current_impl. Subsequent invocations of ompt_enumerate_mutex_impls should pass the value assigned to the variable passed in next_impl to the previous call. The value ompt_mutex_impl_none is reserved to indicate an invalid mutex implementation. ompt_mutex_impl_none is defined as an integer with the value 0.
The next_impl argument is a pointer to an integer in which ompt_enumerate_mutex_impls returns the value of the next mutex implementation in the enumeration.
The next_impl_name argument is a pointer to a character string pointer in which ompt_enumerate_mutex_impls returns a string that describes the next mutex implementation.
Constraints on ArgumentsAny string returned through the next_impl_name argument must be immutable and defined for the lifetime of a program execution.
SummaryThe ompt_set_callback_t type is the type signature of the ompt_set_callback runtime entry point, which registers a pointer to a tool callback that an OpenMP implementation invokes when a host OpenMP event occurs.
DescriptionOpenMP implementations can use callbacks to indicate the occurrence of events during the execution of an OpenMP program. The ompt_set_callback runtime entry point, which has type signature ompt_set_callback_t, registers a callback for an OpenMP event on the current device, The return value of ompt_set_callback indicates the outcome of registering the callback.
Description of ArgumentsThe event argument indicates the event for which the callback is being registered. The callback argument is a tool callback function. If callback is NULL then callbacks associated with event are disabled. If callbacks are successfully disabled then ompt_set_always is returned.
Constraints on ArgumentsWhen a tool registers a callback for an event, the type signature for the callback must match the type signature appropriate for the event.
RestrictionsThe ompt_set_callback runtime entry point has the following restriction:
SummaryThe ompt_get_callback_t type is the type signature of the ompt_get_callback runtime entry point, which retrieves a pointer to a registered tool callback routine (if any) that an OpenMP implementation invokes when a host OpenMP event occurs.
DescriptionThe ompt_get_callback runtime entry point, which has type signature ompt_get_callback_t, retrieves a pointer to the tool callback that an OpenMP implementation may invoke when a host OpenMP event occurs. If a non-null tool callback is registered for the specified event, the pointer to the tool callback is assigned to the variable passed by reference in callback and ompt_get_callback returns 1; otherwise, it returns 0. If ompt_get_callback returns 0, the value of the variable passed by reference as callback is undefined.
Description of ArgumentsThe event argument indicates the event for which the callback would be invoked. The callback argument returns a pointer to the callback associated with event.
Constraints on ArgumentsThe callback argument must be a reference to a variable of specified type.
SummaryThe ompt_get_thread_data_t type is the type signature of the ompt_get_thread_data runtime entry point, which returns the address of the thread data object for the current thread.
BindingThe binding thread for the ompt_get_thread_data runtime entry point is the current thread.
DescriptionEach OpenMP thread can have an associated thread data object of type ompt_data_t. The ompt_get_thread_data runtime entry point, which has type signature ompt_get_thread_data_t, retrieves a pointer to the thread data object, if any, that is associated with the current thread. A tool may use a pointer to an OpenMP thread’s data object that ompt_get_thread_data retrieves to inspect or to modify the value of the data object. When an OpenMP thread is created, its data object is initialized with value ompt_data_none. This runtime entry point is async signal safe.
SummaryThe ompt_get_num_procs_t type is the type signature of the ompt_get_num_procs runtime entry point, which returns the number of processors currently available to the execution environment on the host device.
BindingThe binding thread set for the ompt_get_num_procs runtime entry point is all threads on the host device.
DescriptionThe ompt_get_num_procs runtime entry point, which has type signature ompt_get_num_procs_t, returns the number of processors that are available on the host device at the time the routine is called. This value may change between the time that it is determined and the time that it is read in the calling context due to system actions outside the control of the OpenMP implementation. This runtime entry point is async signal safe.
SummaryThe ompt_get_num_places_t type is the type signature of the ompt_get_num_places runtime entry point, which returns the number of places currently available to the execution environment in the place list.
BindingThe binding thread set for the ompt_get_num_places runtime entry point is all threads on a device.
DescriptionThe ompt_get_num_places runtime entry point, which has type signature ompt_get_num_places_t, returns the number of places in the place list. This value is equivalent to the number of places in the place-partition-var ICV in the execution environment of the initial task. This runtime entry point is async signal safe.
SummaryThe ompt_get_place_procs_ids_t type is the type signature of the ompt_get_num_place_procs_ids runtime entry point, which returns the numerical identifiers of the processors that are available to the execution environment in the specified place.
BindingThe binding thread set for the ompt_get_place_proc_ids runtime entry point is all threads on a device.
DescriptionThe ompt_get_place_proc_ids runtime entry point, which has type signature ompt_get_place_proc_ids_t, returns the numerical identifiers of each processor that is associated with the specified place. These numerical identifiers are non-negative and their meaning is implementation defined.
Description of ArgumentsThe place_num argument specifies the place that is being queried. The ids argument is an array in which the routine can return a vector of processor identifiers in the specified place.
The ids_size argument indicates the size of the result array that is specified by ids.
EffectIf the ids array of size ids_size is large enough to contain all identifiers then they are returned in ids and their order in the array is implementation defined. Otherwise, if the ids array is too small the values in ids when the function returns are unspecified. The routine always returns the number of numerical identifiers of the processors that are available to the execution environment in the specified place.
SummaryThe ompt_get_place_num_t type is the type signature of the ompt_get_place_num runtime entry point, which returns the place number of the place to which the current thread is bound.
BindingThe binding thread set of the ompt_get_place_num runtime entry point is the current thread.
DescriptionWhen the current thread is bound to a place, ompt_get_place_num returns the place number associated with the thread. The returned value is between 0 and one less than the value returned by ompt_get_num_places, inclusive. When the current thread is not bound to a place, the routine returns -1. This runtime entry point is async signal safe.
SummaryThe ompt_get_partition_place_nums_t type is the type signature of the ompt_get_partition_place_nums runtime entry point, which returns a list of place numbers that correspond to the places in the place-partition-var ICV of the innermost implicit task.
BindingThe binding task set for the ompt_get_partition_place_nums runtime entry point is the current implicit task.
DescriptionThe ompt_get_partition_place_nums runtime entry point, which has type signature ompt_get_partition_place_nums_t, returns a list of place numbers that correspond to the places in the place-partition-var ICV of the innermost implicit task. This runtime entry point is async signal safe.
Description of ArgumentsThe place_nums argument is an array in which the routine can return a vector of place identifiers. The place_nums_size argument indicates the size of the result array that the place_nums argument specifies.
EffectIf the place_nums array of size place_nums_size is large enough to contain all identifiers then they are returned in place_nums and their order in the array is implementation defined. Otherwise, if the place_nums array is too small, the values in place_nums when the function returns are unspecified. The routine always returns the number of places in the place-partition-var ICV of the innermost implicit task.
SummaryThe ompt_get_proc_id_t type is the type signature of the ompt_get_proc_id runtime entry point, which returns the numerical identifier of the processor of the current thread.
BindingThe binding thread set for the ompt_get_proc_id runtime entry point is the current thread.
DescriptionThe ompt_get_proc_id runtime entry point, which has type signature ompt_get_proc_id_t, returns the numerical identifier of the processor of the current thread. A defined numerical identifier is non-negative and its meaning is implementation defined. A negative number indicates a failure to retrieve the numerical identifier. This runtime entry point is async signal safe.
SummaryThe ompt_get_state_t type is the type signature of the ompt_get_state runtime entry point, which returns the state and the wait identifier of the current thread.
BindingThe binding thread for the ompt_get_state runtime entry point is the current thread.
DescriptionEach OpenMP thread has an associated state and a wait identifier. If a thread’s state indicates that the thread is waiting for mutual exclusion then its wait identifier contains an opaque handle that indicates the data object upon which the thread is waiting. The ompt_get_state runtime entry point, which has type signature ompt_get_state_t, retrieves the state and wait identifier of the current thread. The returned value may be any one of the states predefined by ompt_state_t or a value that represents any implementation specific state. The tool may obtain a string representation for each state with the ompt_enumerate_states function. If the returned state indicates that the thread is waiting for a lock, nest lock, critical section, atomic region, or ordered region then the value of the thread’s wait identifier is assigned to a non-null wait identifier passed as the wait_id argument.
This runtime entry point is async signal safe.
Description of ArgumentsThe wait_id argument is a pointer to an opaque handle that is available to receive the value of the thread’s wait identifier. If wait_id is not NULL then the entry point assigns the value of the thread’s wait identifier to the object to which wait_id points. If the returned state is not one of the specified wait states then the value of opaque object to which wait_id points is undefined after the call.
Constraints on ArgumentsThe argument passed to the entry point must be a reference to a variable of the specified type or NULL.
SummaryThe ompt_get_parallel_info_t type is the type signature of the ompt_get_parallel_info runtime entry point, which returns information about the parallel region, if any, at the specified ancestor level for the current execution context.
DescriptionDuring execution, an OpenMP program may employ nested parallel regions. The ompt_get_parallel_info runtime entry point known, which has type signature ompt_get_parallel_info_t, retrieves information, about the current parallel region and any enclosing parallel regions for the current execution context. The entry point returns 2 if there is a parallel region at the specified ancestor level and the information is available, 1 if there is a parallel region at the specified ancestor level but the information is currently unavailable, and 0 otherwise. A tool may use the pointer to a parallel region’s data object that it obtains from this runtime entry point to inspect or to modify the value of the data object. When a parallel region is created, its data object will be initialized with the value ompt_data_none.
This runtime entry point is async signal safe.
Between a parallel-begin event and an implicit-task-begin event, a call to ompt_get_parallel_info(0,...) may return information about the outer parallel team, the new parallel team or an inconsistent state.
If a thread is in the state ompt_state_wait_barrier_implicit_parallel then a call to ompt_get_parallel_info may return a pointer to a copy of the specified parallel region’s parallel_data rather than a pointer to the data word for the region itself. This convention enables the master thread for a parallel region to free storage for the region immediately after the region ends, yet avoid having some other thread in the region’s team potentially reference the region’s parallel_data object after it has been freed.
Description of ArgumentsThe ancestor_level argument specifies the parallel region of interest by its ancestor level. Ancestor level 0 refers to the innermost parallel region; information about enclosing parallel regions may be obtained using larger values for ancestor_level. The parallel_data argument returns the parallel data if the argument is not NULL.
The team_size argument returns the team size if the argument is not NULL.
EffectIf the runtime entry point returns 0 or 1, no argument is modified. Otherwise, ompt_get_parallel_info has the following effects:
Constraints on ArgumentsWhile argument ancestor_level is passed by value, all other arguments to the entry point must be pointers to variables of the specified types or NULL.
SummaryThe ompt_get_task_info_t type is the type signature of the ompt_get_task_info runtime entry point, which returns information about the task, if any, at the specified ancestor level in the current execution context.
DescriptionDuring execution, an OpenMP thread may be executing an OpenMP task. Additionally, the thread’s stack may contain procedure frames that are associated with suspended OpenMP tasks or OpenMP runtime system routines. To obtain information about any task on the current thread’s stack, a tool uses the ompt_get_task_info runtime entry point, which has type signature ompt_get_task_info_t. Ancestor level 0 refers to the active task; information about other tasks with associated frames present on the stack in the current execution context may be queried at higher ancestor levels.
The ompt_get_task_info runtime entry point returns 2 if there is a task region at the specified ancestor level and the information is available, 1 if there is a task region at the specified ancestor level but the information is currently unavailable, and 0 otherwise.
If a task exists at the specified ancestor level and the information is available then information is returned in the variables passed by reference to the entry point. If no task region exists at the specified ancestor level or the information is unavailable then the values of variables passed by reference to the entry point are undefined when ompt_get_task_info returns.
A tool may use a pointer to a data object for a task or parallel region that it obtains from ompt_get_task_info to inspect or to modify the value of the data object. When either a parallel region or a task region is created, its data object will be initialized with the value ompt_data_none.
This runtime entry point is async signal safe.
Description of ArgumentsThe ancestor_level argument specifies the task region of interest by its ancestor level. Ancestor level 0 refers to the active task; information about ancestor tasks found in the current execution context may be queried at higher ancestor levels. The flags argument returns the task type if the argument is not NULL.
The task_data argument returns the task data if the argument is not NULL.
The task_frame argument returns the task frame pointer if the argument is not NULL.
The parallel_data argument returns the parallel data if the argument is not NULL.
The thread_num argument returns the thread number if the argument is not NULL.
EffectIf the runtime entry point returns 0 or 1, no argument is modified. Otherwise, ompt_get_task_info has the following effects:
Constraints on ArgumentsWhile argument ancestor_level is passed by value, all other arguments to ompt_get_task_info must be pointers to variables of the specified types or NULL.
SummaryThe ompt_get_task_memory_t type is the type signature of the ompt_get_task_memory runtime entry point, which returns information about memory ranges that are associated with the task.
DescriptionDuring execution, an OpenMP thread may be executing an OpenMP task. The OpenMP implementation must preserve the data environment from the creation of the task for the execution of the task. The ompt_get_task_memory runtime entry point, which has type signature ompt_get_task_memory_t, provides information about the memory ranges used to store the data environment for the current task. Multiple memory ranges may be used to store these data. The block argument supports iteration over these memory ranges.
The ompt_get_task_memory runtime entry point returns 1 if there are more memory ranges available, and 0 otherwise. If no memory is used for a task, size is set to 0. In this case, addr is unspecified.
This runtime entry point is async signal safe.
Description of ArgumentsThe addr argument is a pointer to a void pointer return value to provide the start address of a memory block. The size argument is a pointer to a size type return value to provide the size of the memory block.
The block argument is an integer value to specify the memory block of interest.
SummaryThe ompt_get_target_info_t type is the type signature of the ompt_get_target_info runtime entry point, which returns identifiers that specify a thread’s current target region and target operation ID, if any.
DescriptionThe ompt_get_target_info entry point, which has type signature ompt_get_target_info_t, returns 1 if the current thread is in a target region and 0 otherwise. If the entry point returns 0 then the values of the variables passed by reference as its arguments are undefined. If the current thread is in a target region then ompt_get_target_info returns information about the current device, active target region, and active host operation, if any.
This runtime entry point is async signal safe.
Description of ArgumentsThe device_num argument returns the device number if the current thread is in a target region. Th target_id argument returns the target region identifier if the current thread is in a target region.
If the current thread is in the process of initiating an operation on a target device (for example, copying data to or from an accelerator or launching a kernel) then host_op_id returns the identifier for the operation; otherwise, host_op_id returns ompt_id_none.
Constraints on ArgumentsArguments passed to the entry point must be valid references to variables of the specified types.
SummaryThe ompt_get_num_devices_t type is the type signature of the ompt_get_num_devices runtime entry point, which returns the number of available devices.
DescriptionThe ompt_get_num_devices runtime entry point, which has type signature ompt_get_num_devices_t, returns the number of devices available to an OpenMP program. This runtime entry point is async signal safe.
SummaryThe ompt_get_unique_id_t type is the type signature of the ompt_get_unique_id runtime entry point, which returns a unique number.
DescriptionThe ompt_get_unique_id runtime entry point, which has type signature ompt_get_unique_id_t, returns a number that is unique for the duration of an OpenMP program. Successive invocations may not result in consecutive or even increasing numbers. This runtime entry point is async signal safe.
SummaryThe ompt_finalize_tool_t type is the type signature of the ompt_finalize_tool runtime entry point, which enables a tool to finalize itself.
DescriptionA tool may detect that the execution of an OpenMP program is ending before the OpenMP implementation does. To facilitate clean termination of the tool, the tool may invoke the ompt_finalize_tool runtime entry point, which has type signature ompt_finalize_tool_t. Upon completion of ompt_finalize_tool, no OMPT callbacks are dispatched.
EffectThe ompt_finalize_tool routine detaches the tool from the runtime, unregisters all callbacks and invalidates all OMPT entry points passed to the tool in the lookup-function. Upon completion of ompt_finalize_tool, no further callbacks will be issued on any thread. Before the callbacks are unregistered, the OpenMP runtime should attempt to dispatch all outstanding registered callbacks as well as the callbacks that would be encountered during shutdown of the runtime, if possible in the current execution context.