Merge pull request openshmem-org#237 from nspark/improve-examples

Improve example code

.clang-format

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

Makefile

@@ -15,5 +15,5 @@ ${TARGET}.pdf: ${SOURCES} ${FIGURES} ${EXAMPLES}
 
 .PHONY: clean
 clean:
-	rm -f ${TARGET}.{log,aux,ps,dvi,bbl,blg,log,idx,out,toc,pdf,out} chappage.txt
+	rm -f ${TARGET}.{log,aux,ps,dvi,bbl,blg,log,idx,ind,ilg,out,toc,pdf,out} chappage.txt
 

content/backmatter.tex

@@ -31,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}}.
@@ -60,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
@@ -85,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
@@ -98,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
@@ -111,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/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/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_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;
 }

example_code/amo_scenario_3.c

@@ -1,21 +1,20 @@
 #include <shmem.h>
 
 int main(void) {
-    static long psync[SHMEM_REDUCE_SYNC_SIZE];
-    static int pwrk[SHMEM_REDUCE_MIN_WRKDATA_SIZE];
-    static int x = 0, y = 0;
+  static long psync[SHMEM_REDUCE_SYNC_SIZE];
+  static int pwrk[SHMEM_REDUCE_MIN_WRKDATA_SIZE];
+  static int x = 0, y = 0;
 
-    for (int i = 0; i < SHMEM_REDUCE_SYNC_SIZE; i++)
-        psync[i] = SHMEM_SYNC_VALUE;
+  for (int i = 0; i < SHMEM_REDUCE_SYNC_SIZE; i++)
+    psync[i] = SHMEM_SYNC_VALUE;
 
-    shmem_init();
-    shmem_int_atomic_inc(&x, (shmem_my_pe()+1) % shmem_n_pes());
-    /* Undefined behavior: The following reduction operation performs accesses to symmetric
-     * variable 'x' that are concurrent with previously issued atomic increment operations
-     * on the same variable. */
-    shmem_int_sum_to_all(&y, &x, 1, 0, 0, shmem_n_pes(), pwrk, psync);
+  shmem_init();
+  shmem_int_atomic_inc(&x, (shmem_my_pe() + 1) % shmem_n_pes());
+  /* Undefined behavior: The following reduction operation performs accesses to
+   * symmetric variable 'x' that are concurrent with previously issued atomic
+   * increment operations on the same variable. */
+  shmem_int_sum_to_all(&y, &x, 1, 0, 0, shmem_n_pes(), pwrk, psync);
 
-    shmem_finalize();
-    return 0;
+  shmem_finalize();
+  return 0;
 }
-

example_code/amo_scenario_4.c

@@ -1,16 +1,16 @@
 #include <shmem.h>
 
 int main(void) {
-    static int x = 0;
+  static int x = 0;
 
-    shmem_init();
-    /* Undefined behavior: OpenSHMEM atomic increment operations are concurrent with the local
-     * increment of symmetric variable 'x'. */
-    if (shmem_my_pe() > 0)
-      shmem_int_atomic_inc(&x, 0);
-    else
-      x++;
+  shmem_init();
+  /* Undefined behavior: OpenSHMEM atomic increment operations are concurrent
+   * with the local increment of symmetric variable 'x'. */
+  if (shmem_my_pe() > 0)
+    shmem_int_atomic_inc(&x, 0);
+  else
+    x++;
 
-    shmem_finalize();
-    return 0;
+  shmem_finalize();
+  return 0;
 }

example_code/hello-openshmem.c

@@ -1,12 +1,11 @@
-#include <stdio.h>
 #include <shmem.h> /* The OpenSHMEM header file */
+#include <stdio.h>
 
-int main (void)
-{
-   shmem_init();
-   int me = shmem_my_pe();
-   int npes = shmem_n_pes();
-   printf("Hello from %d of %d\n", me, npes);
-   shmem_finalize();
-   return 0;
+int main(void) {
+  shmem_init();
+  int mype = shmem_my_pe();
+  int npes = shmem_n_pes();
+  printf("Hello from %d of %d\n", mype, npes);
+  shmem_finalize();
+  return 0;
 }