Added an examples directory (Sandia-OpenSHMEM#983)

* Added an examples directory

The examples directory has a few simple OpenSHMEM programs, a
simple Makefile, a LICENSE file, and a README with build
instructions.

examples/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2020 Intel Corporation. All rights reserved.
+This software is available to you under the BSD license below:
+
+    Redistribution and use in source and binary forms, with or
+    without modification, are permitted provided that the following
+    conditions are met:
+
+    - Redistributions of source code must retain the above
+      copyright notice, this list of conditions and the following
+      disclaimer.
+
+    - Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This file is part of the Sandia OpenSHMEM software package. For license
+information, see the LICENSE file in the top level directory of the
+distribution.

examples/Makefile

@@ -0,0 +1,20 @@
+CC = oshcc
+
+.PHONY: all
+all:
+	${CC} hello.c -o hello
+	${CC} pi.c -o pi
+	${CC} pi_reduce.c -o pi_reduce
+
+hello: hello.c
+	${CC} hello.c -o $@
+
+pi: pi.c
+	${CC} pi.c -o $@
+
+pi_reduce: pi_reduce.c
+	${CC} pi_reduce.c -o $@
+
+.PHONY: clean
+clean:
+	${RM} *.o hello pi pi_reduce

examples/README

@@ -0,0 +1,23 @@
+Build all examples using "make" or "make all"
+
+To build examples individually, use "make" followed by the filename (omitting the
+file extension). For example, to build the hello world program, use "make hello"
+
+To remove all the executables, run "make clean"
+
+Requirments to build and run the examples:
+  * Have the SOS installation "bin" directory set in the environment PATH
+  * Have a compatible process launcher (e.g. Hydra version 3.2) set in the
+    environment PATH
+    * By invoking the run script, "oshrun", it will pick up the chosen process
+      launcher.
+  * An example of setting the environment PATH on bash:
+    $ export PATH=<path-to-SOS-install>/bin:<path-to-hydra-install>/bin:$PATH
+
+The hello world example can be run with 4 processes, as below: 
+  oshrun -n 4 ./hello
+
+For more detailed information visit the Getting Started Guide:
+  https://github.com/Sandia-OpenSHMEM/SOS/wiki/Getting-Started-Guide
+
+The Licensing information can be found in the "LICENSE" file

examples/hello.c

@@ -0,0 +1,27 @@
+#include <shmem.h>
+#include <stdio.h>
+
+int
+main(int argc, char* argv[], char *envp[])
+{
+    int me, myshmem_n_pes;
+    /*
+    ** Starts/Initializes SHMEM/OpenSHMEM
+    */
+    shmem_init();
+    /*
+    ** Fetch the number or processes
+    ** Some implementations use num_pes();
+    */
+    myshmem_n_pes = shmem_n_pes();
+    /*
+    ** Assign my process ID to me
+    */
+    me = shmem_my_pe();
+
+    printf("Hello World from %d of %d\n", me, myshmem_n_pes);
+
+    shmem_finalize();
+
+    return 0;
+}

examples/pi.c

@@ -0,0 +1,59 @@
+#include <shmem.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#define NUM_POINTS 10000
+
+long long inside = 0, total = 0;
+
+int
+main(int argc, char* argv[], char *envp[])
+{
+    int me, myshmem_n_pes;
+    /*
+    ** Starts/Initializes SHMEM/OpenSHMEM
+    */
+    shmem_init();
+    /*
+    ** Fetch the number or processes
+    ** Some implementations use num_pes();
+    */
+    myshmem_n_pes = shmem_n_pes();
+    /*
+    ** Assign my process ID to me
+    */
+    me = shmem_my_pe();
+
+    srand(1+me);
+
+    for(total = 0; total < NUM_POINTS; ++total) {
+        double x,y;
+        x = rand()/(double)RAND_MAX;
+        y = rand()/(double)RAND_MAX;
+
+        if(x*x + y*y < 1) {
+            ++inside;
+        }
+    }
+
+    shmem_barrier_all();
+
+    if(me == 0) {
+        int i;
+        for(i = 1; i < myshmem_n_pes; ++i) {
+            long long remoteInside,remoteTotal;
+            shmem_longlong_get(&remoteInside,&inside,1,i);
+            shmem_longlong_get(&remoteTotal,&total,1,i);
+            total += remoteTotal;
+            inside += remoteInside;
+        }
+
+        double approx_pi = 4.0*inside/(double)total;
+
+        printf("Pi from %llu points on %d PEs: %lf\n", total, myshmem_n_pes, approx_pi);
+    }
+
+    shmem_finalize();
+
+    return 0;
+}

examples/pi_reduce.c

@@ -0,0 +1,55 @@
+#include <shmem.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#define NUM_POINTS 10000
+
+long long inside = 0, total = 0;
+
+int
+main(int argc, char* argv[], char *envp[])
+{
+    int me, myshmem_n_pes;
+    /*
+    ** Starts/Initializes SHMEM/OpenSHMEM
+    */
+    shmem_init();
+    /*
+    ** Fetch the number or processes
+    ** Some implementations use num_pes();
+    */
+    myshmem_n_pes = shmem_n_pes();
+    /*
+    ** Assign my process ID to me
+    */
+    me = shmem_my_pe();
+
+    srand(1+me);
+
+    for(total = 0; total < NUM_POINTS; ++total) {
+        double x,y;
+        x = rand()/(double)RAND_MAX;
+        y = rand()/(double)RAND_MAX;
+
+        if(x*x + y*y < 1) {
+            ++inside;
+        }
+    }
+
+    shmem_barrier_all();
+
+    /*
+    ** Reduce each PE's inside & total value into the same symmetric address
+    */
+    shmem_sum_reduce(SHMEM_TEAM_WORLD, &inside, &inside, 1);
+    shmem_sum_reduce(SHMEM_TEAM_WORLD, &total, &total, 1);
+
+    if(me == 0) {
+        double approx_pi = 4.0*inside/(double)total;
+        printf("Pi from %llu points on %d PEs: %lf\n", total,myshmem_n_pes, approx_pi);
+    }
+
+    shmem_finalize();
+
+    return 0;
+}

test/unit/hello.c

@@ -52,7 +52,7 @@ main(int argc, char* argv[], char *envp[])
     me = shmem_my_pe();
 
     if (NULL == getenv("MAKELEVEL")) {
-        printf("Hello World from %d of %d\n",me,myshmem_n_pes);
+        printf("Hello World from %d of %d\n", me, myshmem_n_pes);
     }
 
     shmem_finalize();

test/unit/pi.c

@@ -87,7 +87,7 @@ main(int argc, char* argv[], char *envp[])
         }
 
         if (NULL == getenv("MAKELEVEL")) {
-            printf("Pi from %llu points on %d PEs: %lf\n",total,myshmem_n_pes,approx_pi);
+            printf("Pi from %llu points on %d PEs: %lf\n", total, myshmem_n_pes, approx_pi);
         }
     }