Skip to content

Commit 3346a30

Browse files
author
Henry Jin
committed
v6.0 release
1 parent 11f2efc commit 3346a30

File tree

138 files changed

+3011
-341
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

138 files changed

+3011
-341
lines changed

Chap_data_environment.tex

+1
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@
8686
\input{data_environment/lastprivate}
8787
\input{data_environment/reduction}
8888
\input{data_environment/udr}
89+
\input{data_environment/induction}
8990
\input{data_environment/scan}
9091
\input{data_environment/copyin}
9192
\input{data_environment/copyprivate}

Chap_devices.tex

+2
Original file line numberDiff line numberDiff line change
@@ -73,5 +73,7 @@
7373
\input{devices/async_target_with_tasks}
7474
\input{devices/async_target_nowait}
7575
\input{devices/async_target_nowait_depend}
76+
\input{devices/async_target_nowait_arg}
7677
\input{devices/device}
78+
\input{devices/device_env_traits}
7779

Chap_directives.tex

+16-7
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
\index{directive syntax}
44

55
OpenMP \plc{directives} use base-language mechanisms to specify OpenMP program behavior.
6-
In C code, the directives are formed exclusively with pragmas, whereas in C++
7-
code, directives are formed from either pragmas or attributes.
6+
In C/C++ code, the directives are formed with
7+
either pragmas or attributes.
88
Fortran directives are formed with comments in free form and fixed form sources (codes).
99
All of these mechanisms allow the compilation to ignore the OpenMP directives if
1010
OpenMP is not supported or enabled.
@@ -20,18 +20,27 @@
2020

2121
C/C++ pragmas
2222
\begin{indentedcodelist}
23-
\kcode{\#pragma omp} \plc{directive-specification}
23+
#pragma omp \plc{directive-specification}
2424
\end{indentedcodelist}
2525

26-
C++ attributes
26+
C/C++ attribute specifiers
2727
\begin{indentedcodelist}
28-
\kcode{[[omp :: directive( \plc{directive-specification} )]]}
29-
\kcode{[[using omp : directive( \plc{directive-specification} )]]}
28+
[[omp :: directive( \plc{directive-specification} )]]
29+
[[omp :: decl( \plc{directive-specification} )]]
3030
\end{indentedcodelist}
3131

32+
C++ attribute specifiers
33+
\begin{indentedcodelist}
34+
[[using omp : directive( \plc{directive-specification} )]]
35+
[[using omp : decl( \plc{directive-specification} )]]
36+
\end{indentedcodelist}
37+
38+
where the \kcode{decl} attribute may be used for declarative
39+
directives alternatively.
40+
3241
Fortran comments
3342
\begin{indentedcodelist}
34-
\scode{!$omp} \plc{directive-specification}
43+
!$omp \plc{directive-specification}
3544
\end{indentedcodelist}
3645
3746
where \scode{c$omp} and \scode{*$omp} may be used in Fortran fixed form sources.

Chap_loop_transformations.tex

+2-1
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121

2222
%===== Examples Sections =====
2323
\input{loop_transformations/tile}
24-
\input{loop_transformations/unroll}
2524
\input{loop_transformations/partial_tile}
25+
\input{loop_transformations/unroll}
26+
\input{loop_transformations/apply}
2627

Chap_program_control.tex

+1
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,7 @@
105105
\input{program_control/cancellation}
106106
\input{program_control/requires}
107107
\input{program_control/context_based_variants}
108+
\input{program_control/dispatch}
108109
\input{program_control/nested_loop}
109110
\input{program_control/nesting_restrict}
110111
\input{program_control/target_offload}

Chap_tasking.tex

+1
Original file line numberDiff line numberDiff line change
@@ -59,4 +59,5 @@
5959
\input{tasking/taskyield}
6060
\input{tasking/taskloop}
6161
\input{tasking/parallel_masked_taskloop}
62+
\input{tasking/taskloop_dep}
6263

Contributions.md

+10
Original file line numberDiff line numberDiff line change
@@ -158,9 +158,19 @@ The following describes LaTeX macros defined specifically for examples.
158158
\cppspecificstart, \cppspecificend
159159
\ccppspecificstart, \ccppspecificend
160160
\fortranspecificstart, \fortranspecificend
161+
\begin{cspecific}[s] ... \end{cspecific}
162+
\begin{cppspecific}[s] ... \end{cppspecific}
163+
\begin{ccppspecific}[s] ... \end{ccppspecific}
164+
\begin{fortranspecific}[s] ... \end{fortranspecific}
161165
\topmarker{Lang}
162166
```
163167
168+
Use of the structured `\begin{} .. \end{}` environments is the preferred
169+
way of specifying language-dependent text over the unstructured approach
170+
of using `\*specificstart` and `\*specificend`.
171+
The option `[s]` to each of the environments can specify a vertical shift
172+
for the beginning rule, such as when followed by a section header.
173+
164174
The macro `\topmarker` puts a dashed blue line floater at top of a page for
165175
"Lang (cont.)" where `Lang` can be `C/C++`, `C++`, `Fortran`.
166176

Deprecated_Features.tex

+30
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,9 @@
5858
\tablelasttail{\hline\\[-2ex]}
5959
\tablecaption{Deprecated Features and Their Replacements\label{tab:Deprecated Features}}
6060
\begin{supertabular}{p{0.4in} p{2.3in} p{2.2in}}
61+
6.0 & \kcode{declare reduction(}\plc{reduction-id}: \plc{typename-list}: \plc{combiner}\kcode{)}
62+
& \kcode{declare reduction(}\plc{reduction-id}: \plc{typename-list}\kcode{)} \kcode{combiner(\plc{combiner-exp})} \\
63+
\hline
6164
5.2 & \kcode{default} clause on metadirectives
6265
& \kcode{otherwise} clause \\
6366
5.2 & delimited \kcode{declare target} directive for C/C++
@@ -98,6 +101,32 @@ \section{Updated Examples for Different Versions}
98101
the prior name of an example when it has been renamed.
99102

100103

104+
Table~\ref{tab:Updated Examples 6.0} lists the updated examples for
105+
features deprecated in OpenMP 6.0
106+
in the Examples Document Version
107+
\href{https://github.com/OpenMP/Examples/tree/v6.0}{6.0}.
108+
The \emph{Earlier Version} column of the table lists the earlier version
109+
tags of the examples that can be found in
110+
the Examples Document Version
111+
\href{https://github.com/OpenMP/Examples/tree/v5.2}{5.2}.
112+
113+
\index{clauses!combiner@\kcode{combiner}}
114+
\index{combiner clause@\kcode{combiner} clause}
115+
116+
\nolinenumbers
117+
\dpftable{6.0}
118+
\begin{supertabular}{p{1.7in} p{1.1in} p{2.2in}}
119+
\hexentry{udr.1}[f90]{4.0} &
120+
\plc{combiner} expression in \kcode{declare} \\
121+
\hexentry{udr.2}[f90]{4.0} &
122+
\kcode{reduction} directive changed to use \\
123+
\hexentry{udr.3}[f90]{4.0} & \kcode{combiner} clause \\
124+
\hexentry[f90]{udr.4}{4.0} & \\
125+
\hexentry[cpp]{udr.5}{4.0} & \\
126+
\hexentry[cpp]{udr.6}{4.0} & \\[2pt]
127+
\end{supertabular}
128+
129+
\linenumbers
101130
Table~\ref{tab:Updated Examples 5.2} lists the updated examples for
102131
features deprecated in OpenMP 5.2
103132
in the Examples Document Version \examplesref{5.2}.
@@ -195,6 +224,7 @@ \section{Updated Examples for Different Versions}
195224
\end{supertabular}
196225

197226
\linenumbers
227+
\newpage
198228
Table~\ref{tab:Updated Examples 5.1} lists the updated examples for
199229
features deprecated in OpenMP 5.1
200230
in the Examples Document Version \examplesref{5.1}.

Foreword_Chapt.tex

+18-11
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,27 @@ \chapter*{Foreword}
22
\label{chap:foreword}
33

44
The OpenMP Examples document has been updated with new features
5-
found in the OpenMP \PVER\ Specification. The additional examples and updates
6-
are referenced in the Document Revision History of the Appendix on page~\pageref{chap:history}.
7-
8-
Text describing an example with a \PVER\ feature specifically states
9-
that the feature support begins in the OpenMP \PVER\ Specification. Also,
10-
an \kcode{\small{}omp_\PVER} keyword is included in the metadata of the source code.
11-
12-
These distinctions are presented to remind readers that a \PVER\ compliant
5+
found in the OpenMP \SVER\ Specification.
6+
In order to provide users with new feature examples concurrently
7+
with the release of the OpenMP 6.0 Specification,
8+
the 6.0 Examples document is being released early
9+
with a caveat that some of the 6.0 features
10+
(such as \kcode{workdistribute} construct, \kcode{taskgraph} construct,
11+
\kcode{threadset} clause and free-agent threads) will be covered
12+
in the next release of the document.
13+
For a list of the new examples and updates in this release,
14+
please refer to the Document Revision History of the Appendix on page~\pageref{chap:history}.
15+
16+
Text describing an example with a \SVER\ feature specifically states
17+
that the feature support begins in the OpenMP \SVER\ Specification. Also,
18+
an \kcode{\small{}omp_\SVER} keyword is included in the metadata of the source code.
19+
These distinctions are presented to remind readers that a \SVER\ compliant
1320
OpenMP implementation is necessary to use these features in codes.
1421

15-
Examples for most of the \PVER\ features are included in this document,
16-
and incremental releases will become available as more feature examples
22+
%Examples for most of the \SVER\ features are included in this document,
23+
%and
24+
Incremental releases will become available as more feature examples
1725
and updates are submitted and approved by the OpenMP Examples Subcommittee.
18-
1926
Examples are accepted for this document after discussions, revisions and reviews
2027
in the Examples Subcommittee, and two reviews/discussions and two votes
2128
in the OpenMP Language Committee.

History.tex

+68
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,74 @@
11
\cchapter{Document Revision History}{history}
22
\label{chap:history}
33

4+
%=====================================
5+
\section{Changes from 5.2.2 to 6.0}
6+
\label{sec:history_522_to_60}
7+
8+
\begin{itemize}
9+
\item General changes:
10+
\begin{itemize}
11+
\item Added a set of structured LaTeX environments for specifying
12+
language-dependent text. This allows extracting language-specific
13+
content of the Examples document. Refer to the content of
14+
\examplesblob{v6.0/Contributions.md} for details.
15+
\end{itemize}
16+
17+
\item Added the following examples for the 6.0 features:
18+
\begin{itemize}
19+
\item \kcode{omp::decl} attribute for declarative directives in C/C++
20+
(\specref{sec:attributes})
21+
\item \kcode{transparent} clause on the \kcode{task} construct to enable dependences
22+
between non-sibling tasks (\specref{subsec:depend_trans_task})
23+
\item Task dependences for \kcode{taskloop} construct
24+
(\specref{sec:taskloop_depend})
25+
\item \kcode{num_threads} clause that appears inside \kcode{target} region
26+
(\specref{subsec:target_teams_num_teams})
27+
\item \kcode{nowait} clause with argument on the \kcode{target} construct to control deferment
28+
of target task (\specref{subsec:async_target_nowait_arg})
29+
\item Traits for specifying devices (\specref{sec:device_env_traits})
30+
\item \kcode{apply} clause with modifier argument to
31+
support selective loop transformations
32+
(\specref{sec:apply_clause})
33+
\item Reduction on private variables in a \kcode{parallel} region
34+
(\specref{subsec:priv_reduction})
35+
\item \kcode{induction} clause (\specref{subsec:induction})
36+
and user-defined induction (\specref{subsec:user-defined-induction})
37+
\item \kcode{init_complete} clause for \kcode{scan} directive to
38+
support initialization phase in scan operation
39+
(\specref{sec:scan})
40+
\item \kcode{assume} construct with \kcode{no_openmp} and \kcode{no_parallelism} clauses (\specref{sec:assumption})
41+
\item \kcode{num_threads} clause with a list
42+
(\specref{subsec:icv_nthreads})
43+
\item \kcode{dispatch} construct to control variant substitution
44+
for a procedure call (\specref{sec:dispatch})
45+
\end{itemize}
46+
47+
\item Other changes:
48+
\begin{itemize}
49+
\item Changed attribute specifier as a directive form from C++ only to C/C++
50+
(\specref{chap:directive_syntax})
51+
\item Added missing \bcode{include <omp.h>} in Example \example{atomic.4.c}
52+
and \bcode{use omp_lib} in Example \example{atomic.4.f90}
53+
(\specref{sec:atomic_hint})
54+
\item Fixed the function declaration order for variant functions in
55+
Examples \example{selector_scoring.[12].c} and Fortran pointer
56+
initialization in Example \example{selector_scoring.2.f90}
57+
(\specref{subsec:context_selector_scoring})
58+
\item Replaced the deprecated use of \plc{combiner-exp}
59+
in \kcode{declare reduction} directive with \kcode{combiner} clause
60+
(\specref{subsec:UDR} and \specref{sec:Updated Examples})
61+
\item Fixed the initialization of Fortran pointers
62+
in Example \example{cancellation.2.f90} and changed to
63+
use \kcode{atomic write} for performing atomic writes
64+
(\specref{sec:cancellation})
65+
\item Added missing \kcode{declare target} directive for external procedure
66+
called inside \kcode{target} region in Example
67+
\example{requires.1.f90} (\specref{sec:requires})
68+
\end{itemize}
69+
70+
\end{itemize}
71+
472
%=====================================
573
\section{Changes from 5.2.1 to 5.2.2}
674
\label{sec:history_521_to_522}

Makefile

+19-10
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,21 @@
44
include versioninfo
55

66
default: openmp-examples.pdf
7-
diff: openmp-diff-abridged.pdf
7+
diff: clean openmp-diff-abridged.pdf
88

9-
book: BOOK_BUILD="\\\\def\\\\bookbuild{1}"
10-
book: VERSIONSTR="$(version_date)"
11-
book: clean openmp-examples.pdf
12-
mv openmp-examples-${version}.pdf openmp-examples-${version}-book.pdf
139
release: VERSIONSTR="$(version_date)"
1410
release: clean openmp-examples.pdf
1511

12+
book: BOOK_BUILD="\\\\def\\\\bookbuild{1}"
13+
book: clean release
14+
mv openmp-examples-${version}.pdf openmp-examples-${version}-book.pdf
15+
16+
ccpp-only: LANG_OPT="\\\\ccpptrue\\\\fortranfalse"
17+
ccpp-only: clean release
18+
19+
fortran-only: LANG_OPT="\\\\ccppfalse\\\\fortrantrue"
20+
fortran-only: clean release
21+
1622
CHAPTERS=Title_Page.tex \
1723
Foreword_Chapt.tex \
1824
Chap_*.tex \
@@ -41,8 +47,9 @@ LATEXDCMD=$(LATEXCMD) -draftmode
4147

4248
# check for branches names with "name_XXX"
4349
DIFF_TICKET_ID=$(shell git rev-parse --abbrev-ref HEAD)
44-
GITREV=$(shell git rev-parse --short HEAD)
50+
GITREV=$(shell git rev-parse --short HEAD || echo "??")
4551
VERSIONSTR="GIT rev $(GITREV)"
52+
LANG_OPT="\\\\ccpptrue\\\\fortrantrue"
4653

4754
openmp-examples.pdf: $(CHAPTERS) $(SOURCES) openmp.sty openmp-examples.tex openmp-logo.png generated-include.tex
4855
rm -f $(INTERMEDIATE_FILES)
@@ -75,15 +82,15 @@ endif
7582
ifdef DIFF_FROM
7683
VC_DIFF_FROM := -r ${DIFF_FROM}
7784
else
78-
VC_DIFF_FROM := -r main
85+
VC_DIFF_FROM := -r work_6.0
7986
endif
8087

8188
DIFF_TO:=HEAD
82-
DIFF_FROM:=main
89+
DIFF_FROM:=work_6.0
8390
DIFF_TYPE:=UNDERLINE
8491

8592
COMMON_DIFF_OPTS:=--math-markup=whole \
86-
--append-safecmd=plc,code,hcode,scode,pcode,splc \
93+
--append-safecmd=plc,code,kcode,scode,ucode,vcode,splc,bcode,pvar,pout,example \
8794
--append-textcmd=subsubsubsection
8895

8996
VC_DIFF_OPTS:=${COMMON_DIFF_OPTS} --force -c latexdiff.cfg --flatten --type="${DIFF_TYPE}" --git --pdf ${VC_DIFF_FROM} ${VC_DIFF_TO} --subtype=ZLABEL --graphics-markup=none
@@ -94,8 +101,10 @@ generated-include.tex:
94101
echo "$(BOOK_BUILD)"
95102
echo "$(BOOK_BUILD)" > $@
96103
echo "\def\VER{${version}}" >> $@
97-
echo "\def\PVER{${version_spec}}" >> $@
104+
echo "\def\SVER{${version_spec}}" >> $@
98105
echo "\def\VERDATE{${VERSIONSTR}}" >> $@
106+
echo "\\\\newif\ifccpp\\\\newif\iffortran" >> $@
107+
echo "$(LANG_OPT)" >> $@
99108
util/list_tags -vtag */sources/* >> $@
100109

101110
%.tmpdir: $(wildcard *.sty) $(wildcard *.png) $(wildcard *.aux) openmp-examples.pdf

STYLE_GUIDE.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
### OpenMP Examples Coding Style Guide
2+
3+
Must Dos:
4+
- Indents and Braces
5+
- Code: Follow common base language practices.
6+
- Where indents are normally used, use 2 spaces instead of tabs.
7+
- Comments: Follow the indent of the base language for which the comment applies.
8+
- OpenMP directives should be indented as if it's base language code where possible.
9+
- Braces `{}` around structured blocks following directives must be on a new line and must follow base language indent.
10+
- For C/C++ examples, for code blocks with multiple lines, the if-else statements must follow the following format:
11+
```
12+
if {
13+
} else {
14+
}
15+
```
16+
- All Section and sub-section headings must be in Title case. For example: " This is a Useful Example of X Directive ".
17+
18+
- Comments
19+
- Comments go on a new line before the relevant code/code block.
20+
- Expected results may go on the same line.
21+
- Keep comments terse; detailed explanations go in the text.
22+
23+
- Output
24+
- If there is a deterministic output, provide it.
25+
- It can be done in one of the following ways:
26+
- Specify the correct value in a comment.
27+
- Code prints out "expected" and "run" values.
28+
- Test for the correctness of a value in a conditional.
29+
- If the test is expected to execute, return values must be used to indicate success or failure.
30+
- For tests that produce incorrect results, use:
31+
- `return(1)` for C/C++
32+
- `stop 1` for Fortran (do not exit)
33+
- For tests that need to discontinue execution, use:
34+
- `exit(1)` for C/C++
35+
- `error stop` for Fortran
36+
- Validation messages such as "Pass" / "Fail" are not mandatory.
37+
- A single "pass" or "fail" is sufficient for a multi-case test.
38+
39+
- To Verify Metadata:
40+
- A tool in the repository at the top level, "make check", scans all sources for version tags and ensures line length is 75 characters max.
41+
- Inside `utils`, there is `chk_tags` (see different options) that can accept 1 file and scan for all specified values.
42+
43+
Don’ts:
44+
- Unless required by the feature, use free-format Fortran for new examples.
45+
- Do not use all-caps for emphasis in the document.
46+

Title_Page.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
\textsf{OpenMP\\Application Programming\\Interface}
1313

1414
% An optional subtitle can go here:
15-
\vspace{0.5in}\textsf{Examples}\vspace{-0.7in}
15+
\vspace{0.5in}\textsf{\langselect Examples}\vspace{-0.7in}
1616
\normalsize
1717

1818
\vspace{1.0in}

0 commit comments

Comments
 (0)