Merge pull request #12 from openshmem-org/master

Updating OpenSHMEM-1.5 RC Branch for Sync/Lock from openshmem-org:master

.clang-format

@@ -0,0 +1,5 @@
+BasedOnStyle:  LLVM
+BreakBeforeBraces: Custom
+BraceWrapping:
+  BeforeElse: true
+ColumnLimit: 93

.gitignore

@@ -1,4 +1,3 @@
-chappage.txt
 main_spec.aux
 main_spec.idx
 main_spec.ilg
@@ -7,5 +6,4 @@ main_spec.log
 main_spec.out
 main_spec.pdf
 main_spec.toc
-*.log
-*~
+*~

Makefile

@@ -13,7 +13,8 @@ ${TARGET}.pdf: ${SOURCES} ${FIGURES} ${EXAMPLES}
 	makeindex ${TARGET}
 	pdflatex $(LATEXOPT) ${TARGET}
 
+RM ?= rm -f
+CLEAN_EXTENSIONS = aux idx ilg ind log out pdf toc
 .PHONY: clean
 clean:
-	rm -f ${TARGET}.{log,aux,ps,dvi,bbl,blg,log,idx,out,toc,pdf,out} chappage.txt
-
+	for e in ${CLEAN_EXTENSIONS}; do $(RM) ${TARGET}.$$e; done

content/backmatter.tex

@@ -3,8 +3,7 @@
 \appendix
 
 %defining pagestyle for annex
-%\pagestyle{plain} \withlinenumbers
-\pagestyle{fancy} \withlinenumbers
+\pagestyle{fancy}
 \fancyhf{}
 \fancyhead[RE, LO]{\leftmark}
 \fancyhead[RO, LE]{\thepage}
@@ -32,18 +31,19 @@ \section*{Incorporating OpenSHMEM into Programs}\label{sec:writing_programs}
 In \openshmem, the order in which lines appear in the output is not
 deterministic because \acp{PE} execute asynchronously in parallel.
 
-\begin{minipage}{\linewidth}
-\vspace{0.1in}
-\numberedlisting{caption={``Hello World'' example program in \Cstd},label=openshmem-hello,language=OSH2+C}
-                {example_code/hello-openshmem.c}
-\outputlisting{language=bash,caption={Possible ordering of expected output with 4 \acp{PE} from the program in Listing~\ref{openshmem-hello}}}
-                {example_code/hello-openshmem-c.output}
-\vspace{0.1in}
-\end{minipage}
+\SourceExample{example_code/hello-openshmem.c}{
+  \label{openshmem-hello}
+  ``Hello World'' example program in \Cstd
+}
+
+\ProgramOutput{example_code/hello-openshmem-c.output}{
+  Possible ordering of expected output with 4 \acp{PE} from the
+  program in Example~\ref{openshmem-hello}
+}
 
 \clearpage %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-The example in Listing~\ref{openshmem-hello-symmetric} shows a more complex
+Example~\ref{openshmem-hello-symmetric} shows a more complex
 \openshmem program that illustrates the use of symmetric data objects.
 Note the declaration of the \VAR{static short dest} array and its use as the
 remote destination in \hyperref[subsec:shmem_put]{\FUNC{shmem\_put}}.
@@ -61,17 +61,15 @@ \section*{Incorporating OpenSHMEM into Programs}\label{sec:writing_programs}
 The \source{} object does not need to be symmetric because \PUT{} handles the
 references to the \VAR{source} array only on the active (local) side.
 
-\begin{minipage}{\linewidth}
-\vspace{0.1in}
-\numberedlisting{caption={Example program with symmetric data objects},label=openshmem-hello-symmetric,language=OSH2+C}
-                {example_code/writing_shmem_example.c}
-\outputlisting{language=bash,caption={Possible ordering of expected output with 4 \acp{PE} from the program in Listing~\ref{openshmem-hello-symmetric}}}
-                {example_code/writing_shmem_example.output}
-\vspace{0.1in}
-\end{minipage}
-
-
+\SourceExample{example_code/writing_shmem_example.c}{
+  \label{openshmem-hello-symmetric}
+  Example program with symmetric data objects
+}
 
+\ProgramOutput{example_code/writing_shmem_example.output}{
+  Possible ordering of expected output with 4~\acp{PE} from the
+  program in Example~\ref{openshmem-hello-symmetric}
+}
 
 \chapter{Compiling and Running Programs}\label{sec:compiling}
 The \openshmem Specification does not specify how
@@ -86,7 +84,7 @@ \subsection*{Programs written in \Cstd}
 \textbf{oshcc}, to aid in the compilation of \Cstd programs.
 The wrapper may be called as follows:
 
-\begin{lstlisting}[language=bash]
+\begin{lstlisting}[]
 oshcc <compiler options> -o myprogram myprogram.c
 \end{lstlisting}
 Where the $\langle\mbox{compiler options}\rangle$ are options understood by the
@@ -99,7 +97,7 @@ \subsection*{Programs written in \Cpp}
 \textbf{oshc++}, to aid in the compilation of \Cpp programs.
 The wrapper may be called as follows:
 
-\begin{lstlisting}[language=bash]
+\begin{lstlisting}[]
 oshc++ <compiler options> -o myprogram myprogram.cpp
 \end{lstlisting}
 Where the $\langle\mbox{compiler options}\rangle$ are options understood by the
@@ -112,7 +110,7 @@ \section{Running Programs}
 \textbf{oshrun}, to launch \openshmem programs.
 The wrapper may be called as follows:
 
-\begin{lstlisting}[language=bash]
+\begin{lstlisting}[]
 oshrun <runner options> -np <#> <program> <program arguments>
 \end{lstlisting}
 The arguments for \textbf{oshrun} are:

content/frontmatter.tex

@@ -23,7 +23,6 @@
 
 % Set header/footer for main content
 \pagestyle{fancy}   %replacing {headings} with {fancy} for customization 
-\withlinenumbers    %adds line numbers to edges of normal pages
 \fancyhf{}
 \fancyhead[RE, LO]{\rightmark}
 \fancyhead[RO, LE]{\thepage}

content/interoperability.tex

@@ -126,23 +126,22 @@ \subsection{Mapping Process Identification Numbers}
 
 \subsubsection*{Examples}
 \label{subsubsec:interoperability:id:example}
-The following example demonstrates how to manage the mapping between \openshmem
-\ac{PE} numbers and \ac{MPI} ranks in \VAR{MPI\_COMM\_WORLD} in a hybrid \openshmem
-and \ac{MPI} program.
-
-\lstinputlisting[language={C}, tabsize=2,
-      basicstyle=\ttfamily\footnotesize]
-      {example_code/hybrid_mpi_mapping_id.c}
-
-The following example demonstrates an alternative approach for managing the mapping
-of process identification numbers in a hybrid program. The program creates a
-new MPI communicator, named \VAR{shmem\_comm}, that contains all
-processes in \VAR{MPI\_COMM\_WORLD} and each process has the same \ac{MPI} rank
-number as its \openshmem \ac{PE} number.
-
-\lstinputlisting[language={C}, tabsize=2,
-      basicstyle=\ttfamily\footnotesize]
-      {example_code/hybrid_mpi_mapping_id_shmem_comm.c}
+
+\SourceExample{example_code/hybrid_mpi_mapping_id.c}{
+  The following example demonstrates how to manage the mapping between
+  \openshmem \ac{PE} numbers and \ac{MPI} ranks in
+  \VAR{MPI\_COMM\_WORLD} in a hybrid \openshmem and \ac{MPI} program.
+}
+
+
+\SourceExample{example_code/hybrid_mpi_mapping_id_shmem_comm.c}{
+  The following example demonstrates an alternative approach for
+  managing the mapping of process identification numbers in a hybrid
+  program. The program creates a new MPI communicator, named
+  \VAR{shmem\_comm}, that contains all processes in
+  \VAR{MPI\_COMM\_WORLD} and each process has the same \ac{MPI} rank
+  number as its \openshmem \ac{PE} number.
+}
 
 \subsection{RMA Programming Models}
 \label{subsec:interoperability:rma}

content/library_handles.tex

@@ -23,10 +23,12 @@
 %%
 \LibHandleDecl{SHMEM\_TEAM\_SHARED} &
 Handle of type \CTYPE{shmem\_team\_t} that corresponds to a team of \acp{PE}
-that share a memory domain. When this handle is used by some \ac{PE},
-it will refer to the team of all \acp{PE} that would return a non-null
-pointer from \FUNC{shmem\_ptr} for symmetric objects on that \ac{PE},
-and vice versa. This means that symmetric objects on each \ac{PE} are
+that share a memory domain.  \LibHandleRef{SHMEM\_TEAM\_SHARED} refers to
+the team of all PEs that would mutually return a non-null address from a
+call to \FUNC{shmem\_ptr} for all symmetric heap objects.  That is,
+\FUNC{shmem\_ptr} must return a non-null pointer to the local PE for all
+symmetric heap objects on all target \acp{PE} in the team.  This means that
+symmetric heap objects on each \ac{PE} are
 directly load/store accessible by all \acp{PE} in the team.
 See Section~\ref{subsec:team} for more detail about its use.
 \tabularnewline \hline

content/memory_model.tex

@@ -129,37 +129,37 @@ \subsection{Atomicity Guarantees}\label{subsec:amo_guarantees}
 with non-atomic operations, such as one-sided \OPR{put} or \OPR{get} operations,
 will invalidate the atomicity guarantees.
 
-\cexample
-    {
-      The following \CorCpp example illustrates scenario 1.
-      In this example, different atomicity domains are used to access
-      the same location, resulting in undefined behavior.
-      The undefined behavior can be resolved by using communication
-      contexts in the same atomicity domain in all concurrent operations.
-    } {./example_code/amo_scenario_1.c}
+\SourceExample{./example_code/amo_scenario_1.c}{
+  The following \CorCpp example illustrates scenario 1.
+  In this example, different atomicity domains are used to access
+  the same location, resulting in undefined behavior.
+  The undefined behavior can be resolved by using communication
+  contexts in the same atomicity domain in all concurrent operations.
+}
 
-\cexample
-    {The following \CorCpp example illustrates scenario 2.  In this example,
-    different datatypes are used to access the same location concurrently,
-    resulting in undefined behavior.  The undefined behavior can be resolved by
-    using the same datatype in all concurrent operations.  For example, the
-    32-bit value can be left-shifted and a 64-bit atomic OR operation can be
-    used.}
-    {./example_code/amo_scenario_2.c}
+\SourceExample{./example_code/amo_scenario_2.c}{
+  The following \CorCpp example illustrates scenario 2.  In this example,
+  different datatypes are used to access the same location concurrently,
+  resulting in undefined behavior.  The undefined behavior can be resolved by
+  using the same datatype in all concurrent operations.  For example, the
+  32-bit value can be left-shifted and a 64-bit atomic OR operation can be
+  used.
+}
 
-\cexample
-    {The following \CorCpp example illustrates scenario 3.  In this example,
-    atomic increment operations are concurrent with a non-atomic reduction
-    operation, resulting in undefined behavior.  The undefined behavior can be
-    resolved by inserting a barrier operation before the reduction.  The
-    barrier ensures that all local and remote AMOs have completed before the
-    reduction operation accesses $x$.}
-    {./example_code/amo_scenario_3.c}
+\SourceExample{./example_code/amo_scenario_3.c}{
+  The following \CorCpp example illustrates scenario 3.  In this example,
+  atomic increment operations are concurrent with a non-atomic reduction
+  operation, resulting in undefined behavior.  The undefined behavior can be
+  resolved by inserting a barrier operation before the reduction.  The
+  barrier ensures that all local and remote AMOs have completed before the
+  reduction operation accesses $x$.
+}
+
+\SourceExample{./example_code/amo_scenario_4.c}{
+  The following \CorCpp example illustrates scenario 4.  In this example, an
+  \openshmem atomic increment operation is concurrent with a local increment
+  operation, resulting in undefined behavior.  The undefined behavior can be
+  resolved by replacing the local increment operation with an \openshmem
+  atomic increment.
+}
 
-\cexample
-    {The following \CorCpp example illustrates scenario 4.  In this example, an
-    \openshmem atomic increment operation is concurrent with a local increment
-    operation, resulting in undefined behavior.  The undefined behavior can be
-    resolved by replacing the local increment operation with an \openshmem
-    atomic increment.}
-    {./example_code/amo_scenario_4.c}

content/shmem_get.tex

@@ -18,7 +18,7 @@
 
 \begin{CsynopsisCol}
 void @\FuncDecl{shmem\_get\FuncParam{SIZE}}@(void *dest, const void *source, size_t  nelems, int pe);
-void @\FuncDecl{shmem\_ctx\_get\FuncParam{SIZE}}@(shmem_ctx_t ctx, void *dest, const void *source, size_t  nelems, int pe);
+void @\FuncDecl{shmem\_ctx\_get\FuncParam{SIZE}}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, int pe);
 \end{CsynopsisCol}
 where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}.
 

content/shmem_malloc_hints.tex

@@ -86,4 +86,3 @@
     load/store operations from the origin \ac{PE} or vice versa.
 }
 \end{apidefinition}
-\newpage

content/shmem_reductions.tex

@@ -315,7 +315,7 @@
 \begin{apiexamples}
 
 \apicexample
-    {This \CorCpp reduction example gets integers from an external
+    {This \Cstd[11] reduction example gets integers from an external
     source (random generator in this example), tests to see if the \ac{PE} got a valid
     value, and outputs the sum of values for which all \acp{PE} got a valid
     value.}

content/shmem_signal_wait_until.tex

@@ -33,15 +33,18 @@
     blocks until the value of \VAR{sig\_addr} at the calling \ac{PE} satisfies
     the wait condition specified by the comparison operator, \VAR{cmp}, and
     comparison value, \VAR{cmp\_value}.
-
-    Implementations must ensure that \FUNC{shmem\_signal\_wait\_until} do not
-    return before the update of the memory indicated by \VAR{sig\_addr} is
-    fully complete.
 }
 
 \apireturnvalues{
     Return the contents of the signal data object, \VAR{sig\_addr}, at the
     calling \ac{PE} that satisfies the wait condition.
 }
 
+\apiimpnotes{
+    Implementations must ensure that \FUNC{shmem\_signal\_wait\_until} do not
+    return before the update of the memory indicated by \VAR{sig\_addr} is fully
+    complete. Partial updates to the memory must not cause
+    \FUNC{shmem\_signal\_wait\_until} to return.
+}
+
 \end{apidefinition}

content/shmem_test_some.tex

@@ -89,7 +89,7 @@
 \begin{apiexamples}
   \apicexample
       {The following \Cstd[11] example demonstrates the use of
-      \FUNC{shmem\_test\_some} to process a simple all-to-all transfer of N
+      \FUNC{shmem\_test\_some} to process a simple all-to-all transfer of $N$
       data elements via a sum reduction, while potentially overlapping
       communication with computation.  This pattern is similar to the
       \FUNC{shmem\_test\_any} example above, but each while loop iteration may

example_code/.gitignore

@@ -0,0 +1 @@
+*.[cf]x

example_code/Makefile

@@ -1,5 +1,5 @@
 CC       = oshcc
-CFLAGS  ?= -Wall -Wextra
+CFLAGS  ?= -Wall -Wextra -pedantic -Werror
 
 FC       = oshfort
 FFLAGS  ?= -Wall -Wextra
@@ -13,6 +13,8 @@ C_BINS   = $(C_TESTS:.c=.cx)
 F_TESTS  = $(wildcard *.f90)
 F_BINS   = $(F_TESTS:.f90=.fx)
 
+shmem_ctx.cx:	CFLAGS += -fopenmp
+
 .PHONY: all run clean
 
 all: $(C_BINS) $(F_BINS)
@@ -24,9 +26,10 @@ all: $(C_BINS) $(F_BINS)
 	$(FC) $(FFLAGS) -o $@ $+
 
 run: $(C_BINS)
-	@for bin in $+; do				\
-	    echo --$$bin------------------------------;	\
-	    $(RUNCMD) $(RUNOPT) ./$$bin || exit $$?;	\
+	@for bin in $+; do					\
+	    echo -- $$bin ------------------------------;	\
+	    $(RUNCMD) $(RUNOPT) ./$$bin;			\
+	    echo -- exit status: $$?;				\
 	done
 
 clean:

example_code/amo_scenario_2.c

@@ -1,16 +1,16 @@
 #include <shmem.h>
 
 int main(void) {
-    static uint64_t x = 0;
+  static uint64_t x = 0;
 
-    shmem_init();
-    /* Undefined behavior: The following AMOs access the same location concurrently using
-     * different types. */
-    if (shmem_my_pe() > 0)
-      shmem_uint32_atomic_or((uint32_t*)&x, shmem_my_pe()+1, 0);
-    else
-      shmem_uint64_atomic_or(&x, shmem_my_pe()+1, 0);
+  shmem_init();
+  /* Undefined behavior: The following AMOs access the same location
+   * concurrently using different types. */
+  if (shmem_my_pe() > 0)
+    shmem_uint32_atomic_or((uint32_t *)&x, shmem_my_pe() + 1, 0);
+  else
+    shmem_uint64_atomic_or(&x, shmem_my_pe() + 1, 0);
 
-    shmem_finalize();
-    return 0;
+  shmem_finalize();
+  return 0;
 }