Add nonblocking collectives examples

Author: ferrol aderholdt

content/execution_model.tex

@@ -40,9 +40,9 @@ \subsection{Progress of OpenSHMEM Operations}\label{subsec:progress}
 without that \ac{PE} issuing any explicit \openshmem calls. One-sided \openshmem
 communication calls involving that \ac{PE} should progress regardless of when
 that \ac{PE} next engages in an \openshmem call. Similarly,
-for non-blocking collectives, consider the \acp{PE} that are part of a team
-issuing a non-blocking collective and overlapping collective completion with
-computation. Once a non-blocking collective operation is initiated by
+for nonblocking collectives, consider the \acp{PE} that are part of a team
+issuing a nonblocking collective and overlapping collective completion with
+computation. Once a nonblocking collective operation is initiated by
 all of the \acp{PE} in the team of the collective, any \ac{PE} in the team must
 eventually observe completion through a call to \FUNC{shmem\_req\_test} or a
 call to \FUNC{shmem\_req\_wait}.

content/shmem_alltoall_nb.tex

@@ -119,5 +119,13 @@
     Zero on successful local completion. Nonzero otherwise.
 }
 
-\end{apidefinition}
+\begin{apiexamples}
+
+\apicexample
+    {This \CorCpp{} example shows overlapping nonblocking \FUNC{shmem\_int64\_alltoall\_nb} on two 64-bit integers among all \acp{PE}.}
+    {./example_code/shmem_alltoall_nb_example.c}
+    {}
 
+\end{apiexamples}
+
+\end{apidefinition}

content/shmem_broadcast_nb.tex

@@ -100,4 +100,14 @@
     \LibConstRef{SHMEM\_TEAM\_INVALID}.
 }
 
+\begin{apiexamples}
+
+\apicexample
+    {In the following \Cstd[11] example, the call to multiple \FUNC{shmem\_broadcast\_nb} copies the \source{}
+    params on \ac{PE} $0$ to the \dest{} params on \acp{PE} $0\dots npes-1$.}
+    {./example_code/shmem_broadcast_nb_example.c}
+    {}
+
+\end{apiexamples}
+
 \end{apidefinition}

example_code/shmem_alltoall_nb_example.c

@@ -0,0 +1,77 @@
+#include <inttypes.h>
+#include <shmem.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int main(void) {
+  int          status = 0;
+  const int    count  = 2;
+  const int    nr_a2a = 2;
+  int64_t    **source;
+  int64_t    **dest;
+  shmem_req_h *requests;
+
+  shmem_init();
+  int mype = shmem_my_pe();
+  int npes = shmem_n_pes();
+
+  source   = (int64_t **)shmem_malloc(nr_a2a * sizeof(int64_t *));
+  dest     = (int64_t **)shmem_malloc(nr_a2a * sizeof(int64_t *));
+  requests = (shmem_req_h *) malloc(npes * sizeof(shmem_req_h));
+  for (int i = 0; i < npes; i++) {
+    requests[i] = SHMEM_REQ_INVALID;
+  }
+
+  for (int nr = 0; nr < nr_a2a; nr++) {
+    dest[nr]   = (int64_t *)shmem_malloc(count * npes * sizeof(int64_t));
+    source[nr] = (int64_t *)shmem_malloc(count * npes * sizeof(int64_t));
+    for (int pe = 0; pe < npes; pe++) {
+      for (int i = 0; i < count; i++) {
+        source[nr][(pe * count) + i] = mype + pe;
+        dest[nr][(pe * count) + i]   = 9999;
+      }
+    }
+  }
+
+  /* wait for all PEs to update sources/dests */ 
+  shmem_team_sync(SHMEM_TEAM_WORLD);
+
+  /* overlap alltoall operations on all PEs */
+  for (int i = 0; i < nr_a2a; i++) {
+    status = shmem_int64_alltoall_nb(SHMEM_TEAM_WORLD, dest[i], source[i], count, &requests[i]);
+    if (0 != status) {
+      fprintf(stderr, "shmem alltoall nb failed with status %d\n", status);
+      goto out;
+    }
+  }
+
+  for (int i = 0; i < npes; i++) {
+    status = shmem_req_wait(&requests[i]);
+    if (0 != status) {
+      fprintf(stderr, "shmem req wait failed on request %d\n", i);
+      goto out;
+    }
+  }
+
+  for (int nr = 0; nr < nr_a2a; nr++) {
+    for (int pe = 0; pe < npes; pe++) {
+      for (int i = 0; i < count; i++) {
+        if (dest[nr][(pe * count) + i] != pe + mype) {
+          printf("[%d] ERROR: dest[%d]=%" PRId64 ", should be %d\n",
+            mype, (pe * count) + i, dest[nr][(pe * count) + i], pe + mype);
+        }
+      }
+    }
+  }
+
+out:
+  for (int nr = 0; nr < nr_a2a; nr++) {
+    shmem_free(source[nr]);
+    shmem_free(dest[nr]);
+  }
+  shmem_free(source);
+  shmem_free(dest);
+  free(requests);
+  shmem_finalize();
+  return status;
+}

example_code/shmem_broadcast_nb_example.c

@@ -0,0 +1,53 @@
+#include <shmem.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int main(void) {
+  int          status = 0; 
+  static long  source;
+  long        *dest;
+  shmem_req_h *requests;
+
+  shmem_init();
+  int mype = shmem_my_pe();
+  int npes = shmem_n_pes();
+
+  dest     = (long *)shmem_malloc(npes * sizeof(long));
+  requests = (shmem_req_h *) malloc(npes * sizeof(shmem_req_h));
+  for (int i = 0; i < npes; i++) {
+    requests[i] = SHMEM_REQ_INVALID;
+  }
+
+  source = mype;
+  for (int i = 0; i < npes; i++) {
+    status = shmem_broadcast_nb(SHMEM_TEAM_WORLD, &dest[i], source,
+                                1, i, &requests[i]);
+    if (0 != status) {
+      fprintf(stderr, "shmem broadcast nb failed with root %d and status %d\n",
+                       i, status);
+      goto out;
+    }
+  }
+
+  for (int i = 0; i < npes; i++) {
+    status = shmem_req_wait(&requests[i]);
+    if (0 != status) {
+      fprintf(stderr, "shmem req wait failed on request %d\n", i);
+      goto out;
+    }
+  }
+
+  if (mype == 0) {
+    for (int i = 0; i < npes; i++) {
+      if (i > 0 && !(i % 8)) {
+        printf("\n");
+      }
+      printf("%8d", dest[i]);
+    }
+  }
+out:
+  shmem_free(dest);
+  free(requests);
+  shmem_finalize();
+  return status;
+}