v5.2 release

Author: Henry Jin

Chap_SIMD.tex

@@ -31,7 +31,7 @@
 directive.  Clauses provide argument specifications (\code{linear},
 \code{uniform}, and \code{aligned}), a requested vector length 
 (\code{simdlen}), and designate whether the function is always/never 
-called conditionally in a loop (\code{branch}/\code{inbranch}). 
+called conditionally in a loop (\code{notinbranch}/\code{inbranch}). 
 The latter is for optimizing performance.
 
 Also, the \code{simd} construct has been combined with the worksharing loop 

Chap_data_environment.tex

@@ -22,7 +22,7 @@
 Certain variables and objects have predetermined attributes.  
 A commonly found case is the loop iteration variable in associated loops 
 of a \code{for} or \code{do} construct. It has a private data-sharing attribute.
-Variables with predetermined data-sharing attributes can not be listed in a data-sharing clause; but there are some
+Variables with predetermined data-sharing attributes cannot be listed in a data-sharing clause; but there are some
 exceptions (mainly concerning loop iteration variables).
 
 Variables with explicitly determined data-sharing attributes are those that are
@@ -50,7 +50,7 @@
 structure elements (members). 
 
 Procedures and global variables have predetermined data mapping if they appear
-within the list or block of a \code{declare target} directive. Also, a C/C++ pointer
+within the list or block of a \code{declare}~\code{target} directive. Also, a C/C++ pointer
 is mapped as a zero-length array section, as is a C++ variable that is a reference to a pointer.
 % Waiting for response from Eric on this.
 

Chap_devices.tex

@@ -15,7 +15,7 @@
 
 The constructs that explicitly
 create storage, transfer data, and free storage on the device
-are catagorized as structured and unstructured. The
+are categorized as structured and unstructured. The
 \code{target} \code{data} construct is structured. It creates
 a data region around \code{target} constructs, and is
 convenient for providing persistent data throughout multiple
@@ -33,14 +33,14 @@
 There is an important change in the OpenMP 4.5 specification
 that alters the data model for scalar variables and C/C++ pointer variables.
 The default behavior for scalar variables and C/C++ pointer variables
-in an 4.5 compliant code is \code{firstprivate}. Example
+in a 4.5 compliant code is \code{firstprivate}. Example
 codes that have been updated to reflect this new behavior are
 annotated with a description that describes changes required
 for correct execution. Often it is a simple matter of mapping
 the variable as \code{tofrom} to obtain the intended 4.0 behavior.
 
 In OpenMP version 4.5 the mechanism for target
-execution is specified as occuring through a \plc{target task}. 
+execution is specified as occurring through a \plc{target task}. 
 When the \code{target} construct is encountered a new 
 \plc{target task} is generated. The \plc{target task} 
 completes after the \code{target} region has executed and all data 
@@ -59,13 +59,14 @@
 \input{devices/target_structure_mapping}
 \input{devices/target_fort_allocatable_array_mapping}
 \input{devices/array_sections}
+\input{devices/C++_virtual_functions}
 \input{devices/array_shaping}
 \input{devices/target_mapper}
 \input{devices/target_data}
 \input{devices/target_unstructured_data}
 \input{devices/target_update}
-\input{devices/target_associate_ptr}
 \input{devices/declare_target}
+\input{devices/lambda_expressions}
 \input{devices/teams}
 \input{devices/async_target_depend}
 \input{devices/async_target_with_tasks}

Chap_directives.tex

@@ -1,11 +1,12 @@
 \cchapter{OpenMP Directive Syntax}{directives}
 \label{chap:directive_syntax}
+\index{directive syntax}
 
 OpenMP \emph{directives} use base-language mechanisms to specify OpenMP program behavior.
 In C code, the directives are formed exclusively with pragmas, whereas in C++
 code, directives are formed from either pragmas or attributes.
 Fortran directives are formed with comments in free form and fixed form sources (codes).
-All of these mechanism allow the compilation to ignore the OpenMP directives if
+All of these mechanisms allow the compilation to ignore the OpenMP directives if
 OpenMP is not supported or enabled.
 
 
@@ -35,6 +36,18 @@
 
 where \code{c\$omp} and \code{*\$omp} may be used in Fortran fixed form sources.
 
+Most OpenMP directives accept clauses that alter the semantics of the directive in some way, 
+and some directives also accept parenthesized arguments that follow the directive name. 
+A clause may just be a keyword (e.g., \scode{untied}) or it may also accept argument lists 
+(e.g., \scode{shared(x,y,z)}) and/or optional modifiers (e.g., \scode{tofrom} in 
+\scode{map(tofrom:}~\scode{x,y,z)}).
+Clause modifiers may be "simple" or "complex" -- a complex modifier consists of a 
+keyword followed by one or more parameters, bracketed by parentheses, while a simple 
+modifier does not. An example of a complex modifier is the \scode{iterator} modifier, 
+as in \scode{map(iterator(i=0:n),}~\scode{tofrom:}~\scode{p[i])}, or the \scode{step} modifier, as in 
+\scode{linear(x:}~\scode{ref,}~\scode{step(4))}. 
+In the preceding examples, \scode{tofrom} and \scode{ref} are simple modifiers.
+
 
 %===== Examples Sections =====
 \input{directives/pragmas}

Chap_introduction.tex

@@ -0,0 +1,73 @@
+% This is the introduction for the OpenMP Examples document.
+% This is an included file. See the main file (openmp-examples.tex) for more information.
+%
+% When editing this file:
+%
+%    1. To change formatting, appearance, or style, please edit openmp.sty.
+%
+%    2. Custom commands and macros are defined in openmp.sty.
+%
+%    3. Be kind to other editors -- keep a consistent style by copying-and-pasting to
+%       create new content.
+%
+%    4. We use semantic markup, e.g. (see openmp.sty for a full list):
+%         \code{}     % for bold monospace keywords, code, operators, etc.
+%         \plc{}      % for italic placeholder names, grammar, etc.
+%
+%    5. Other recommendations:
+%         Use the convenience macros defined in openmp.sty for the minor headers
+%         such as Comments, Syntax, etc.
+%
+%         To keep items together on the same page, prefer the use of 
+%         \begin{samepage}.... Avoid \parbox for text blocks as it interrupts line numbering.
+%         When possible, avoid \filbreak, \pagebreak, \newpage, \clearpage unless that's
+%         what you mean. Use \needspace{} cautiously for troublesome paragraphs.
+%
+%         Avoid absolute lengths and measures in this file; use relative units when possible.
+%         Vertical space can be relative to \baselineskip or ex units. Horizontal space
+%         can be relative to \linewidth or em units.
+%
+%         Prefer \emph{} to italicize terminology, e.g.:
+%             This is a \emph{definition}, not a placeholder.
+%             This is a \plc{var-name}.
+%
+
+\cchapter{Introduction}{introduction}
+\label{chap:introduction}
+
+This collection of programming examples supplements the OpenMP API for Shared
+Memory Parallelization specifications, and is not part of the formal specifications. It
+assumes familiarity with the OpenMP specifications, and shares the typographical
+conventions used in that document.
+
+The OpenMP API specification provides a model for parallel programming that is
+portable across shared memory architectures from different vendors. Compilers from
+numerous vendors support the OpenMP API.
+
+The directives, library routines, and environment variables demonstrated in this
+document allow users to create and manage parallel programs while permitting
+portability. The directives extend the C, C++ and Fortran base languages with single
+program multiple data (SPMD) constructs, tasking constructs, device constructs,
+worksharing constructs, and synchronization constructs, and they provide support for
+sharing and privatizing data. The functionality to control the runtime environment is
+provided by library routines and environment variables. Compilers that support the
+OpenMP API often include a command line option to the compiler that activates and
+allows interpretation of all OpenMP directives.
+
+The documents and source codes for OpenMP Examples can be downloaded from
+\href{https://github.com/OpenMP/Examples}{https://github.com/OpenMP/Examples}.
+Each directory holds the contents of a chapter and has a \splc{sources} subdirectory of its codes. 
+The codes for this OpenMP \VER{} Examples document have the tag 
+\href{https://github.com/OpenMP/Examples/tree/v\VER}{\plc{v\PVER}}.
+
+Complete information about the OpenMP API and a list of the compilers that support
+the OpenMP API can be found at the OpenMP.org web site
+
+\code{https://www.openmp.org}
+
+\clearpage
+
+\input{introduction/Examples}
+
+% This is the end of introduction.tex of the OpenMP Examples document.
+

Chap_loop_transformations.tex

@@ -22,4 +22,5 @@
 %===== Examples Sections =====
 \input{loop_transformations/tile}
 \input{loop_transformations/unroll}
+\input{loop_transformations/partial_tile}
 

Chap_memory_model.tex

@@ -25,7 +25,7 @@
 flushes, a \emph{flush-set}. 
 
 A \emph{strong} flush will force consistency between the temporary view and the
-memory for all variables in its \emph{flush-set}.  Furthermore all strong flushes in a
+memory for all variables in its \emph{flush-set}.  Furthermore, all strong flushes in a
 program that have intersecting flush-sets will execute in some total order, and
 within a thread strong flushes may not be reordered with respect to other
 memory operations on variables in its flush-set. \emph{Release} and
@@ -53,7 +53,7 @@
 races in OpenMP programs result in undefined behavior, and so they should
 generally be avoided for programs to be correct.  The completion order of
 accesses to a shared variable is guaranteed in OpenMP through a set of memory
-consistency rules that are described in the \plc{OpenMP Memory Consitency}
+consistency rules that are described in the \plc{OpenMP Memory Consistency}
 section of the OpenMP Specifications document.
 
 %This chapter also includes examples that exhibit non-sequentially consistent

Chap_parallel_execution.tex

@@ -102,8 +102,8 @@
 executed only by the primary thread. There is no implicit barrier (and flush) 
 at the end of the \code{masked} region; hence the other threads of the team continue
 execution beyond code statements beyond the \code{masked} region.
-The \code{master} contruct, which has been deprecated in OpenMP 5.1, has identical semantics
-to the \code{masked} contruct with no \code{filter} clause.
+The \code{master} construct, which has been deprecated in OpenMP 5.1, has identical semantics
+to the \code{masked} construct with no \code{filter} clause.
 
 
 %===== Examples Sections =====

Chap_program_control.tex

@@ -108,6 +108,7 @@
 \input{program_control/nested_loop}
 \input{program_control/nesting_restrict}
 \input{program_control/target_offload}
+\input{program_control/reproducible}
 \input{program_control/interop}
 \input{program_control/utilities}
 

Chap_synchronization.tex

@@ -36,7 +36,7 @@
 
 Since OpenMP 4.5 the \code{ordered} construct can also be a stand-alone 
 directive that specifies cross-iteration dependences in a doacross loop nest.  
-The \code{depend} clause uses a \code{sink} \plc{dependence-type}, along with a 
+The \code{depend} clause uses a \code{sink} \plc{dependence-type}, along with an 
 iteration vector argument (vec) to indicate the iteration that satisfies the 
 dependence.  The \code{depend} clause with a \code{source}
 \plc{dependence-type} specifies dependence satisfaction.

Contributions.md

@@ -54,25 +54,28 @@ For a brief revision history, see `Changes.log` in the repo.
    * Insert the code in the sources directory for each chapter, and include the following metadata:
    * Metadata Tags for example sources:
      ```
-       @@name:        <ename>.<seq-no>[c|cpp|f|f90]
+       @@name:        <ename>.<seq-no>
        @@type:        C|C++|F-fixed|F-free
+       @@requires:    preprocessing
        @@compilable:  yes|no|maybe
        @@linkable:    yes|no|maybe
-       @@expect:      success|failure|nothing|rt-error
+       @@expect:      success|compile-time-error|runtime-error|undefined-behavior
        @@version:     omp_<verno>
      ```
       * **name**
        is the name of an example
       * **type**
-       is the source code type, which can be translated into or from proper file extension (c,cpp,f,f90)
+       is the source code type, which can be translated into or from proper file extension (C:c,C++:cpp,F-fixed:f,F-free:f90)
+      * **requires**
+       any additional requirements, currently `preprocessing` for requiring preprocessing
       * **compilable**
        indicates whether the source code is compilable
       * **linkable**
        indicates whether the source code is linkable
       * **expect**
-       indicates some expected result for testing purpose "`success|failure|nothing`" applies 
-       to the result of code compilation "`rt-error`" is for a case where compilation may be
-       successful, but the code contains potential runtime issues (such as race condition).
+       indicates some expected result for testing purpose "`success|compile-time-error|ct-error`" applies 
+       to the result of code compilation; "`runtime-error|rt-error`" is for a case where compilation may be
+       successful, but the code contains potential runtime issues (such as race condition); `undefined-behavior` could result from a non-conforming code.
        Alternative would be to just use "`conforming`" or "`non-conforming`".
       * **version**
        indicates features for a specific OpenMP version, such as "`omp_5.0`"
@@ -94,23 +97,30 @@ For a brief revision history, see `Changes.log` in the repo.
 
 
 
-# LaTeX macros for examples
+## LaTeX macros for examples
 
+The following describes LaTeX macros defined specifically for examples.
 * Source code with language h-rules
+* Source code without language h-rules
+* Language h-rules
+* Other macros
+* See `openmp.sty` for more information
+
+### Source code with language h-rules
 ```
-   \cexample[<verno>]{<ename>}{<seq-no>}     % for C/C++ examples
-   \cppexample[<verno>]{<ename>}{<seq-no>}   % for C++ examples
-   \fexample[<verno>]{<ename>}{<seq-no>}     % for fixed-form Fortran examples
-   \ffreeexample[<verno>]{<ename>}{<seq-no>} % for free-form Fortran examples
+   \cexample[<verno>]{<ename>}{<seq-no>}[<s>]     % for C/C++ examples
+   \cppexample[<verno>]{<ename>}{<seq-no>}[<s>]   % for C++ examples
+   \fexample[<verno>]{<ename>}{<seq-no>}[<s>]     % for fixed-form Fortran examples
+   \ffreeexample[<verno>]{<ename>}{<seq-no>}[<s>] % for free-form Fortran examples
 ```
 
-* Source code without language h-rules
+### Source code without language h-rules
 ```
-   \cnexample[<verno>]{<ename>}{<seq-no>}
-   \cppnexample[<verno>]{<ename>}{<seq-no>}
-   \fnexample[<verno>]{<ename>}{<seq-no>}
-   \ffreenexample[<verno>]{<ename>}{<seq-no>}
-   \srcnexample[<verno>]{<ename>}{<seq-no>}{<ext>}
+   \cnexample[<verno>]{<ename>}{<seq-no>}[<s>]
+   \cppnexample[<verno>]{<ename>}{<seq-no>}[<s>]
+   \fnexample[<verno>]{<ename>}{<seq-no>}[<s>]
+   \ffreenexample[<verno>]{<ename>}{<seq-no>}[<s>]
+   \srcnexample[<verno>]{<ename>}{<seq-no>}{<ext>}[<s>]
 ```
 
    Optional `<verno>` can be supplied in a macro to include a specific OpenMP
@@ -123,17 +133,23 @@ For a brief revision history, see `Changes.log` in the repo.
    source code should not contain any `@@` metadata tags. The `ext` argument
    to this macro is the file extension (such as `h`, `hpp`, `inc`).
 
-* Language h-rules
+   The `<s>` option to each macro allows finer-control of any additional lines
+   to be skipped due to addition of new `@@` tags, such as `@@requires`.
+   The default value for `<s>` is 0.
+
+### Language h-rules
 ```
    \cspecificstart, \cspecificend
    \cppspecificstart, \cppspecificend
    \ccppspecificstart, \ccppspecificend
    \fortranspecificstart, \fortranspecificend
 ```
 
-* Chapter and section macros
+### Other macros
 ```
    \cchapter{<Chapter Name>}{<chap_directory>}
+   \hexentry[ext1]{<example_name>}[ext2]{<earlier_tag>}
+   \hexmentry[ext1]{<example_name>}[ext2]{<earlier_tag>}{<prior_name>}
 ```
 
 The `\cchapter` macro is used for starting a chapter with proper page spacing.
@@ -146,8 +162,15 @@ A previously-defined macro `\sinput{<section_file>}` to import a section
 file from `<chap_directory>` is no longer supported.  Please use
 `\input{<chap_directory>/<section_file>}` explicitly.
 
-* See `openmp.sty` for more information
+The two macros `\hexentry` and `\hexmentry` are defined for simplifying
+entries in the feature deprecation and update tables. Option `[ext1]` is
+the file extension with a default value of `c` and option `[ext2]` is 
+the file extension for the associated second file if present.
+`<earlier_tag>` is the version tag of the corresponding example
+in the earlier version. `\hexentry` assumes no name change for an example
+in different versions; `\hexmentry` can be used to specify a prior name
+if it is different.
 
-### License
+## License
 
 For copyright information, please see `omp_copyright.txt`.