Improve example code

[nspark]

This PR (will):

• Adds example numbering with optional reference labels
• Ensures the C examples compile with -Wall -Wextra -pedantic -Werror
• Formats the C examples with clang-format
• Colorizes the syntax highlighting for C examples
• Manually update the C examples for better consistency

Tagging @jamesaross and @jdinan for review.

Closes #230

[nspark]

PDF draft as of 558da4f

[jdinan]

I think we need to reintroduce a statement to the effect: if [ $$? -ne 0 ]; then exit $$?; fi; Otherwise, Travis will not be able to flag failures.

[jdinan]

Oh, right, we aren't testing these with Travis during spec builds. This is because newly introduced APIs aren't yet supported and can't be tested. This is still useful to have, because I think we do run these tests (e.g. for a specific tagged version of the spec) as part of automated testing.

[nspark]

The reason for this change is that make run was failing on shmem_global_exit, which intentionally returns a nonzero status.

[jdinan]

Hmm .. we could introduce a TESTS_XFAIL list to handle cases like this. The atomics clarification proposal also introduces three examples with undefined behavior, which we would want to exclude from running. So, maybe TESTS_SKIP? Or, move to a proper testing harness.

[jdinan]

Does this change may cause make run to succeed even after one of the examples fails? I remember doing a bit of tinkering around that || $$?.

[jdinan]

Maybe instead we could print PASS or FAIL (and the exit code)?

[nspark]

Here are some screenshots of the revised/reformatted examples (left) vs. the original/master examples (right). For the most part, page numbering and overall spacing is very similar, as expected.

(removed outdated screenshots)

[nspark]

@manjugv @jdinan This PR is ready for review; I'd like to have an informal review at the F2F

[jamesaross]

This isn't quite ready. Some things I've noticed:

• There are a number of codes which still have my_pe or rank instead of the new mype.
• Some codes are inconsistent and declare the variables upfront rather than the more compact form.
• Some codes use mype and npes with the shmem_team_my_pe and shmem_team_n_pes while others use t_mype and t_npes. This should be consistent.
• Some examples include argc/argv in main interface when they are not used.

Regarding the pshmem_example.c, I prefer this more compact form which doesn't increment time for floating point casting and arithmetic. This should improve the timing accuracy. Not sure if this can be considered a doc edit.

#include <pshmem.h>
#include <stdio.h>
#include <sys/time.h>

static double total_put_time = 0.0;
static double avg_put_time = 0.0;
static long put_count = 0;

void shmem_long_put(long *dest, const long *source, size_t nelems, int pe) {
  struct timeval t0, t1;
  gettimeofday(&t0, 0);                      /* start timer */
  pshmem_long_put(dest, source, nelems, pe); /* name shifted call to put */
  gettimeofday(&t1, 0);                      /* end timer */
  /* increment statistical values */
  total_put_time += t1.tv_sec - t0.tv_sec + 1e-6*(t1.tv_usec - t0.tv_usec);
  put_count++;
  avg_put_time = total_put_time / (double)put_count;
}

[nspark]

@jamesaross I went through all the examples individually, and I think I've addressed all the items you noted.

[jamesaross]

@nspark Thank you. The examples look improved. They'll never be perfect, so we'll probably periodically come back around to these.

Some things to address at some point in the future:

• Remove legacy Fortran from Makefile
• Remove unnecessary header includes
• Possibly error checking and return codes for failures (enabling automated testing)
• Use of newer C11 Generics when reasonable
• Filename consistency
• Simplify, if possible (I'm looking at shmem_team_context.c)

[jamesaross]

@nspark This request is more about document usability...

When you open the generated PDF and use a cursor to select/highlight the embedded example codes in order to copy the text, the line numbers on the left and right of the pages are also copied. This makes it difficult for a reader to copy/paste the example code into a text editor and use it without removing all the line numbers. This doesn't happen with the regular paragraph blocks. Is there a way to avoid this? I'm using the evince PDF reader on Linux.

Maybe an alternative solution is to exclude line numbers on the final drafts? These were added in the 1.1 document in 2014 and I wasn't around then for the discussion. I don't find the PDF line numbers useful beyond collaborating on the draft documents. It's just clutter otherwise.

[nspark]

@jamesaross 👍 on removing the page-level line numbers entirely. I don't find them helpful, and they don't even align to any particular line of text.

[jdinan]

Does this change may cause make run to succeed even after one of the examples fails? I remember doing a bit of tinkering around that || $$?.

[jamesaross]

Within utils/defs.tex, I believe these keywords should be moved from the language keywords to the type keywords otherwise the code highlighting looks off to me.
static, const, volatile, restrict, typedef, struct, union, enum

And also FILE should be added to types, I suppose.

These should be added to the C keywords for future code:
break, case, continue, default, do, else, for, goto, if, return, sizeof, switch, while

In, writing_shmem_example.c, there is a #define SIZE 16, which should be changed to #define N 16 because the six instances of the SIZE keyword get highlighted in the document. Using #define N would be consistent with other examples.

[nspark]

@jdinan Good to go!