release 5.2.1

Author: Henry Jin

Chap_affinity.tex

@@ -2,7 +2,7 @@
 \label{chap:openmp_affinity}
 
 OpenMP Affinity consists of a \code{proc\_bind} policy (thread affinity policy) and a specification of
-places (\texttt{"}location units\texttt{"} or \plc{processors} that may be cores, hardware
+places (``location units'' or \plc{processors} that may be cores, hardware
 threads, sockets, etc.).  
 OpenMP Affinity enables users to bind computations on specific places.
 The placement will hold for the duration of the parallel region. 
@@ -26,7 +26,7 @@
 usual case; but actually, the execution unit is implementation defined.) Processor
 numbers are numbered sequentially from 0 to the number of cores less one (without SMT), or
 0 to the number HW-threads less one (with SMT). OpenMP places use the processor number to designate
-binding locations (unless an \texttt{"}abstract name\texttt{"} is used.) 
+binding locations (unless an ``abstract name'' is used.) 
 
 
 The processors available to a process may be a subset of the system's

Chap_devices.tex

@@ -21,7 +21,7 @@
 convenient for providing persistent data throughout multiple
 \code{target} regions. The \code{target} \code{enter} \code{data} and 
 \code{target} \code{exit} \code{data} constructs are unstructured, because 
-they can occur anywhere and do not support a "structure" 
+they can occur anywhere and do not support a ``structure''
 (a region) for enclosing \code{target} constructs, as does the
 \code{target} \code{data} construct. 
 

Chap_directives.tex

@@ -41,13 +41,17 @@
 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 
+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.
 
+For Fortran, a declarative directive (such as \code{declare}~\code{reduction})
+must appear after any \code{USE}, \code{IMPORT}, and \code{IMPLICIT} statements
+in the specification part.
+
 
 %===== Examples Sections =====
 \input{directives/pragmas}

Chap_introduction.tex

@@ -57,8 +57,8 @@
 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}}.
+This OpenMP Examples \VER{} document and its codes are tagged as  
+\href{https://github.com/OpenMP/Examples/tree/v\VER}{\plc{v\VER}}.
 
 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

Chap_parallel_execution.tex

@@ -49,8 +49,10 @@
 A worksharing construct distributes the execution of the associated region
 among the members of the team that encounter it.  There is an
 implied barrier at the end of the worksharing region
-(there is no barrier at the beginning). The worksharing
-constructs are:
+(there is no barrier at the beginning). 
+
+\newpage
+The worksharing constructs are:
 
 \begin{compactitem}
 
@@ -66,10 +68,10 @@
 an \plc{associated} loop.  Nested loops can form a single region when the 
 \code{collapse} clause (with an integer argument) designates the number of 
 \plc{associated} loops to be executed in parallel, by forming a 
-"single iteration space" for the specified number of nested loops.  
+``single iteration space'' for the specified number of nested loops.
 The \code{ordered} clause can also control multiple associated loops.
 
-An associated loop must adhere to a "canonical form" (specified in the 
+An associated loop must adhere to a ``canonical form'' (specified in the
 \plc{Canonical Loop Form} of the OpenMP Specifications document) which allows the 
 iteration count (of all associated loops) to be computed before the 
 (outermost) loop is executed. %[58:27-29].  

Chap_program_control.tex

@@ -36,7 +36,7 @@
 The \code{cancel} construct is also a cancellation point for any other thread of the team 
 to also continue execution at the end of the named region.  
 
-Also, once the specified region has been activated for cancellation any thread that encounnters 
+Also, once the specified region has been activated for cancellation any thread that encounters
 a \code{cancellation}~\code{point} construct with the same named region (\plc{construct-type-clause}),
 continues execution at the end of the region.
 
@@ -80,7 +80,7 @@
 %construct with one of the loops constructs \code{do} or \code{for}.  The
 %\code{parallel do SIMD} and \code{parallel for SIMD} constructs are composite constructs (composed from
 %the parallel loop constructs and the \code{SIMD} construct), because the \code{collapse} clause must
-%explicitly address the ordering of loop chunking \plc{and} SIMD "combined" execution.
+%explicitly address the ordering of loop chunking \plc{and} SIMD ``combined'' execution.
 
 Certain nestings are forbidden, and often the reasoning is obvious.  For example, worksharing constructs cannot be nested, and
 the \code{barrier} construct cannot be nested inside a worksharing construct, or a \code{critical} construct. 
@@ -108,6 +108,7 @@
 \input{program_control/nested_loop}
 \input{program_control/nesting_restrict}
 \input{program_control/target_offload}
+\input{program_control/pause_resource}
 \input{program_control/reproducible}
 \input{program_control/interop}
 \input{program_control/utilities}

Chap_synchronization.tex

@@ -85,6 +85,7 @@
 \input{synchronization/worksharing_critical}
 \input{synchronization/barrier_regions}
 \input{synchronization/atomic}
+\input{synchronization/atomic_cas}
 \input{synchronization/atomic_restrict}
 \input{synchronization/flush_nolist}
 \input{synchronization/acquire_release}

Chap_tasking.tex

@@ -7,8 +7,8 @@
 but the work units are tightly controlled by an iteration limit and limited 
 scheduling, or a limited number of \code{sections} or \code{single} regions. 
 Worksharing was designed 
-with \texttt{"}data parallel\texttt{"} computing in mind.  Tasking was designed for 
-\texttt{"}task parallel\texttt{"} computing and often involves non-locality or irregularity 
+with ``data parallel'' computing in mind.  Tasking was designed for 
+``task parallel'' computing and often involves non-locality or irregularity 
 in memory access.
 
 The \code{task} construct can be used to execute work chunks: in a while loop; 

Contributions.md

@@ -26,27 +26,27 @@ For a brief revision history, see `Changes.log` in the repo.
  * Clone your fork locally
  * If you are working on generic or old-version updates, create a branch off master.
  * If you are working on an example for a release candidate for version #.#, create a branch off work_#.#.
-   1.) `git clone --branch <master|work_#.#> https://github.com/<my_account>/examples-internal`
-   2.) `git checkout  -b <branch_name>`
-   3.) ...  `add`, `commit`
-   4.) `git push -u origin <branch_name>`
-   5.) `make` or `make diff` will create a full-document pdf or just a pdf with differences (do this at any point).
+   1) `git clone --branch <master|work_#.#> https://github.com/<my_account>/examples-internal`
+   2) `git checkout  -b <branch_name>`
+   3) ...  `add`, `commit`
+   4) `git push -u origin <branch_name>`
+   5) `make` or `make diff` will create a full-document pdf or just a pdf with differences (do this at any point).
  * `git status` and `git branch -a` are your friends
  * Submit an issue for your work (usually with a diff pdf), and then you will be asked to submit a pull request
    * Create an issue by selecting the (issue tab)[https://github.com/openmp/examples-internal/issues] and clicking on `new issue`.
    * Use this MarkDown Cheatsheet for (issue formatting)[https://wordpress.com/support/markdown-quick-reference/]
    * More MarkDown details are available (here)[https://markdown-it.github.io]
    * You can cut and paste markdown formatted text in a (reader)[https://dillinger.io] to see formatting effects.
-   * Forced spaces are available in Markdown.  On a Mac is is "option+space".
+   * Forced spaces are available in Markdown.  On a Mac it is "option+space".
    * Polling is available.  Go to (gh-poll)[https://app.gh-polls.com/].  Type an option on each line, then click `copy markdown`, and paste the contents into the issue.  (Use preview to check your poll, and then submit it.)
  * Create a pull request
 
 
 ## Processing source code
 
    * Prepare source code (C/C++ and Fortran) and a text description (use similar styles found in recent examples)
-   * Determine the *example* name `<ename>`, *sequence* number `<seq-no>` and *compiler* suffix `<csuffix>` for the example
-      * The syntax is:   `<ename>.<seq-no>.<csuffix>`   (e.g. `affinity_display.1.f90`)
+   * Determine the *example* name `<ename>`, *sequence* identifier `<seq-id>` and *compiler* suffix `<csuffix>` for the example
+      * The syntax is:   `<ename>.<seq-id>.<csuffix>`   (e.g. `affinity_display.1.f90`)
       * The example name may be a Section name (e.g. affinity), or a Subsection name (affinity_display)
       * If you are creating a new Chapter, it may be the chapter name.
    * New examples are usually added at the end of a Section or Subsection. Number it as the next number in the sequence numbers for examples in that Section or Subsection.
@@ -56,29 +56,42 @@ For a brief revision history, see `Changes.log` in the repo.
      ```
        @@name:        <ename>.<seq-no>
        @@type:        C|C++|F-fixed|F-free
-       @@requires:    preprocessing
-       @@compilable:  yes|no|maybe
-       @@linkable:    yes|no|maybe
-       @@expect:      success|compile-time-error|runtime-error|undefined-behavior
-       @@version:     omp_<verno>
+       @@operation:   view|compile|link|run
+       @@expect:      success|ct-error|rt-error|unspecified
+       @@version:     [pre_]omp_<verno>
+       @@env:         <environment_variables>
+       @@depend:      <source_code_name>
      ```
       * **name**
        is the name of an example
       * **type**
        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
+      * **operation**
+       indicates how the source code is treated. Possible values are:
+   `view`     - code for illustration only, not compilable;
+   `compile`  - incomplete program, such as function or subroutine;
+   `link`     - complete program, but no verification value;
+   `run`      - complete program with verification value.
       * **expect**
-       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`".
+       indicates some expected result for testing purpose. 
+   `success` means no issue;
+   `ct-error` 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 (including race condition); 
+   `unspecified` could result from a non-conforming code or is for code
+       that is viewable only.
       * **version**
-       indicates features for a specific OpenMP version, such as "`omp_5.0`"
+       indicates that the example uses features in a specific OpenMP version, such as "`omp_5.0`"  
+       The prefix `pre_` indicates that the example uses features prior to a specific version, such as "`pre_omp_3.0`".
+      * **env**
+       specifies any environment variables needed to run the code.
+       This tag is optional and can be repeated.
+      * **depend**
+       specifies a source code file on which the current code depends.
+       This tag is optional and can be repeated.
+      * For **env** and **depend**, make sure to specify
+       a proper skipping number `<s>` in the LaTeX macros described below
+       to match with the number of `env` and `depend` tags.
 
 
 ## Process for text
@@ -134,7 +147,7 @@ The following describes LaTeX macros defined specifically for examples.
    to this macro is the file extension (such as `h`, `hpp`, `inc`).
 
    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`.
+   to be skipped due to addition of new `@@` tags, such as `@@env`.
    The default value for `<s>` is 0.
 
 ### Language h-rules
@@ -173,4 +186,4 @@ if it is different.
 
 ## License
 
-For copyright information, please see `omp_copyright.txt`.
+For copyright information, please see [omp_copyright.txt](omp_copyright.txt).