mirror of
https://github.com/OpenMP/Examples.git
synced 2025-04-04 05:41:33 +01:00
114 lines
4.5 KiB
TeX
114 lines
4.5 KiB
TeX
\pagebreak
|
|
\section{Utilities}
|
|
\label{sec:utilities}
|
|
This section contains examples of utility routines and features.
|
|
|
|
%---------------------------
|
|
\subsection{Timing Routines}
|
|
\label{subsec:get_wtime}
|
|
\index{routines!omp_get_wtime@\kcode{omp_get_wtime}}
|
|
\index{omp_get_wtime routine@\kcode{omp_get_wtime} routine}
|
|
\index{routines!omp_get_wtick@\kcode{omp_get_wtick}}
|
|
\index{omp_get_wtick routine@\kcode{omp_get_wtick} routine}
|
|
|
|
The \kcode{omp_get_wtime} routine can be used to measure the elapsed wall
|
|
clock time (in seconds) of code execution in a program.
|
|
The routine is thread safe and can be executed by multiple threads concurrently.
|
|
The precision of the timer can be obtained by a call to
|
|
the \kcode{omp_get_wtick} routine. The following example shows a use case.
|
|
|
|
\cexample{get_wtime}{1}
|
|
|
|
\ffreeexample{get_wtime}{1}
|
|
|
|
|
|
%---------------------------
|
|
\subsection{Environment Display}
|
|
\label{subsec:display_env}
|
|
\index{environment display!OMP_DISPLAY_ENV@\kcode{OMP_DISPLAY_ENV}}
|
|
\index{environment variables!OMP_DISPLAY_ENV@\kcode{OMP_DISPLAY_ENV}}
|
|
\index{OMP_DISPLAY_ENV@\kcode{OMP_DISPLAY_ENV}}
|
|
\index{environment display!omp_display_env routine@\kcode{omp_display_env} routine}
|
|
\index{routines!omp_display_env@\kcode{omp_display_env}}
|
|
\index{omp_display_env routine@\kcode{omp_display_env} routine}
|
|
|
|
The OpenMP version number and the values of ICVs associated with the relevant
|
|
environment variables can be displayed at runtime by setting
|
|
the \kcode{OMP_DISPLAY_ENV} environment variable to either
|
|
\vcode{TRUE} or \vcode{VERBOSE}.
|
|
The information is displayed once by the runtime.
|
|
|
|
A more flexible or controllable approach is to call
|
|
the \kcode{omp_display_env} API routine at any desired
|
|
point of a code to display the same information.
|
|
This OpenMP 5.1 API routine takes a single \ucode{verbose} argument.
|
|
A value of 0 or \bcode{.false.} (for C/C++ or Fortran) indicates
|
|
the required OpenMP ICVs associated with environment variables be displayed,
|
|
and a value of 1 or \bcode{.true.} (for C/C++ or Fortran) will include
|
|
vendor-specific ICVs that can be modified by environment variables.
|
|
|
|
The following example illustrates the conditional execution of the API
|
|
\kcode{omp_display_env} routine. Typically it would be invoked in
|
|
various debug modes of an application.
|
|
An important use case is to have a single MPI process (e.g., rank = 0)
|
|
of a hybrid (MPI+OpenMP) code execute the routine,
|
|
instead of all MPI processes, as would be done by
|
|
setting the \kcode{OMP_DISPLAY_ENV} to \vcode{TRUE} or \vcode{VERBOSE}.
|
|
|
|
\cexample[5.1]{display_env}{1}
|
|
|
|
\ffreeexample[5.1]{display_env}{1}
|
|
\clearpage
|
|
|
|
A sample output from the execution of the code might look like:
|
|
{\small\begin{verbatim}
|
|
OPENMP DISPLAY ENVIRONMENT BEGIN
|
|
_OPENMP='202011'
|
|
[host] OMP_AFFINITY_FORMAT='(null)'
|
|
[host] OMP_ALLOCATOR='omp_default_mem_alloc'
|
|
[host] OMP_CANCELLATION='FALSE'
|
|
[host] OMP_DEFAULT_DEVICE='0'
|
|
[host] OMP_DISPLAY_AFFINITY='FALSE'
|
|
[host] OMP_DISPLAY_ENV='FALSE'
|
|
[host] OMP_DYNAMIC='FALSE'
|
|
[host] OMP_MAX_ACTIVE_LEVELS='1'
|
|
[host] OMP_MAX_TASK_PRIORITY='0'
|
|
[host] OMP_NESTED: deprecated; max-active-levels-var=1
|
|
[host] OMP_NUM_THREADS: value is not defined
|
|
[host] OMP_PLACES: value is not defined
|
|
[host] OMP_PROC_BIND: value is not defined
|
|
[host] OMP_SCHEDULE='static'
|
|
[host] OMP_STACKSIZE='4M'
|
|
[host] OMP_TARGET_OFFLOAD=DEFAULT
|
|
[host] OMP_THREAD_LIMIT='0'
|
|
[host] OMP_TOOL='enabled'
|
|
[host] OMP_TOOL_LIBRARIES: value is not defined
|
|
OPENMP DISPLAY ENVIRONMENT END
|
|
\end{verbatim}}
|
|
|
|
|
|
%---------------------------
|
|
\subsection{\kcode{error} Directive}
|
|
\label{subsec:error}
|
|
\index{directives!error@\kcode{error}}
|
|
\index{error directive@\kcode{error} directive}
|
|
\index{error directive@\kcode{error} directive!at clause@\kcode{at} clause}
|
|
\index{clauses!at@\kcode{at}}
|
|
\index{at clause@\kcode{at} clause}
|
|
\index{error directive@\kcode{error} directive!severity clause@\kcode{severity} clause}
|
|
\index{clauses!severity@\kcode{severity}}
|
|
\index{severity clause@\kcode{severity} clause}
|
|
|
|
The \kcode{error} directive provides a consistent method for C, C++, and Fortran to emit a \kcode{fatal} or
|
|
\kcode{warning} message at \kcode{compilation} or \kcode{execution} time, as determined by a \kcode{severity}
|
|
or an \kcode{at} clause, respectively. When \kcode{severity(fatal)} is present, the compilation
|
|
or execution is aborted. Without any clauses the default behavior is as if \kcode{at(compilation)}
|
|
and \kcode{severity(fatal)} were specified.
|
|
|
|
The C, C++, and Fortran examples below show all the cases for reporting messages.
|
|
|
|
\cexample[5.2]{error}{1}
|
|
\ffreeexample[5.2]{error}{1}
|
|
|
|
|