diff --git a/Chap_Examples.tex b/Chap_Examples.tex deleted file mode 100644 index a84c6f04..00000000 --- a/Chap_Examples.tex +++ /dev/null @@ -1,58 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% Chapter: Examples -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\chapter{Examples} -\label{chap:examples} - -This chapter contains various code examples that \ac{PMIx} users may find helpful. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Playing Around} - -Example block of C code -\begin{pmixCodeC} -int main() { - printf("Hello World!\n"); - return 0; -} -\end{pmixCodeC} - -The inline code \pmixCodeInlineC{printf("Hello World");} prints ``Hello World''. - -Example of a selection of a file: -\pmixCodeImportC[firstline=72, lastline=84]{sources/hello.c}% - -Example with highlighting: -\pmixCodeImportC[firstline=72, lastline=84, highlightlines={2-5,7}]{sources/hello.c}% - -Putting a couple of examples together - -\pmixCodeJoinStart{}% -\pmixCodeImportC[firstline=41, lastline=42]{sources/hello.c}% -\pmixCodeJoin{}% -\pmixCodeImportC[firstline=49, lastline=55, firstnumber=last]{sources/hello.c}% -\pmixCodeJoinEnd{}% - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Playing Around with Preprocessor} - -Example of a selection of a file: -\pmixCodeImportC{sources/_autogen_/hello-alt.c_main}% - -Example with highlighting: -\pmixCodeImportC[highlightlines={4,7,14-15}]{sources/_autogen_/hello-alt.c_get1}% - -Another example -\pmixCodeImportC{sources/_autogen_/hello-alt.c_init}% - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Synchronizing Fence} -\label{chap:examples:syncfence} - -This example shows how to call a synchronizing \refapi{PMIx_Fence} operation across the entire namespace. -To signify the entire namespace we are using the \refconst{PMIX_RANK_WILDCARD} constant. - -\pmixCodeImportC[firstline=72, lastline=84, highlightlines={2-5,7}]{sources/hello.c}% - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/Makefile b/Makefile index e50e4658..f2c5d849 100644 --- a/Makefile +++ b/Makefile @@ -29,7 +29,8 @@ CHAPTERS= \ App_Python.tex \ Acknowledgements.tex -SOURCES=sources/*.c +SOURCES=sources/*.c \ + sources/*.py \ INTERMEDIATE_FILES=pmix-standard.pdf \ pmix-standard.toc \ diff --git a/bin/process-example.py b/bin/process-example.py index a276eda4..4d527051 100755 --- a/bin/process-example.py +++ b/bin/process-example.py @@ -7,7 +7,7 @@ # Rules: # - The tag strings, regardless of ID, are removed from the final output # - If multiple blocks with the same ID exist then they are concatinated together -# - ID can contain alphabetic and numberic characters and the following symbols: . +# - ID can contain alphabetic and numberic characters and the following symbols: . _ # - Quote marks are stripped out # import sys diff --git a/pmix-standard.tex b/pmix-standard.tex index b707079a..6eed4452 100644 --- a/pmix-standard.tex +++ b/pmix-standard.tex @@ -216,9 +216,6 @@ % PMIx Tools and Debugger Support \input{Chap_API_Tools.tex} - % Examples - \input{Chap_Examples} - % % Appendix % diff --git a/pmix.sty b/pmix.sty index 51d90236..8fbbcd6b 100644 --- a/pmix.sty +++ b/pmix.sty @@ -811,14 +811,40 @@ numbersep=3pt, firstnumber=1} -% Putting a few code blocks together with a little space between the sections. -% \pmixCodeJoinStart{}% -% \pmixCodeImportC[firstline=41, lastline=42]{sources/hello.c}% -% \pmixCodeJoin{}% -% \pmixCodeImportC[firstline=49, lastline=55, firstnumber=last]{sources/hello.c}% -% \pmixCodeJoinEnd{}% -\newcommand{\pmixCodeJoinStart}{\nolinenumbers} -\newcommand{\pmixCodeJoin}{\vspace{-3.15em}} -\newcommand{\pmixCodeJoinEnd}{\linenumbers} +% Python Code block +% \begin{pmixCodePy} +% print("Hello") +% \end{pmixCodePy} +\newminted[pmixCodepPy]{python}{fontsize=\small, + bgcolor=pmixbg, + highlightcolor=pmixhl, + breaklines, + autogobble, + linenos, + numbersep=3pt, + firstnumber=1} +% Inline C code +% The code \pmixCodeInlinePy{print("Hello World")} prints ``Hello World''. +\newmintinline[pmixCodeInlinePy]{python}{bgcolor=pmixbg, + highlightcolor=pmixhl, + breaklines, + autogobble, + linenos, + firstnumber=1} +% Import C code from a file: +% - Whole file: \pmixCodeImportPy{sources/hello.py} +% - Selection of a file: \pmixCodeImportPy[firstline=73, lastline=84]{sources/hello.py} +% - Highlight selection of a file: \pmixCodeImportPy[firstline=73, lastline=84, highlightlines={2-4,6}]{sources/hello.py} +\newmintedfile[pmixCodeImportPy]{python}{fontsize=\small, + bgcolor=pmixbg, + highlightcolor=pmixhl, + breaklines, + autogobble, + linenos, + numbersep=3pt, + firstnumber=1} + + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/sources/README.md b/sources/README.md new file mode 100644 index 00000000..c0223dd7 --- /dev/null +++ b/sources/README.md @@ -0,0 +1,119 @@ +# Source Code Examples + +## General Rules + + * All examples should be buildable + * All examples should contain a comment in the header with: + - How to run the example + - Example output from a run + +## Preprocessor Syntax + +The preprocessor will automatically extract code snippets from the source files. + +The code snippets will be in the `sources/_autogen_` directory which is deleted and recreated on every build. +The code snippets will be named `sources/_autogen_/FILENAME_TAG` where `FILENAME` is the source file and `TAG` is the tag used inside the code snippet to identify the snippet. +Code snippets can span multiple sections which are concatinated, in order of appearance, into the output file. +Code snippets cannot span multiple files. + + * Start a snippet tagged `myexample` : `` + * End a snippet tagged `myexample` : `` + * Tags may only contain alphabetic and numberic characters and the following symbols: `.` `_` + - Quote marks are stripped out of the string + * Lines containing the snippet syntax as stripped out of the generated examples. + +### Example + +Given the following example program called `hello-alt.c` + +``` +#include + +int main(int argc, char **argv) +{ + // + // + pmix_status_t rc = PMIX_SUCCESS; + pmix_proc_t myproc; + // + pmix_value_t *val; + uint16_t localrank; + // + + // + rc = PMIx_Init(&myproc, NULL, 0); + if (PMIX_SUCCESS != rc) { + return 1; + } + // + + // + /* Get our rank local to this node */ + rc = PMIx_Get(&myproc, PMIX_LOCAL_RANK, NULL, 0, &val); + if (PMIX_SUCCESS != rc) { + return 2; + } + localrank = val->data.uint16; + PMIX_VALUE_RELEASE(val); + // + + rc = PMIx_Finalize(NULL, 0); + return rc; +} +``` + +Produces two snippet files + +``` +Processing File: sources/hello-alt.c + Example: in_fname=[sources/hello-alt.c] id=["pmix_get"] -- Stored in sources/_autogen_/hello-alt.c_pmix_get + Example: in_fname=[sources/hello-alt.c] id=["pmix_init"] -- Stored in sources/_autogen_/hello-alt.c_pmix_init +``` + +``` +shell$ cat sources/_autogen_/hello-alt.c_pmix_init +pmix_status_t rc = PMIX_SUCCESS; +pmix_proc_t myproc; + +rc = PMIx_Init(&myproc, NULL, 0); +if (PMIX_SUCCESS != rc) { + return 1; +} +``` + +``` +shell$ cat sources/_autogen_/hello-alt.c_pmix_get +pmix_status_t rc = PMIX_SUCCESS; +pmix_proc_t myproc; +pmix_value_t *val; +uint16_t localrank; + +/* Get our rank local to this node */ +rc = PMIx_Get(&myproc, PMIX_LOCAL_RANK, NULL, 0, &val); +if (PMIX_SUCCESS != rc) { + return 2; +} +localrank = val->data.uint16; +PMIX_VALUE_RELEASE(val); +``` + +## Including Code Snippets in Latex + +Import C code with and without highlighting (line numbers from generated source) +``` +Example without highlighting +\pmixCodeImportC{sources/_autogen_/hello-alt.c_pmix_init}% + +Example with highlighting: +\pmixCodeImportC[highlightlines={2-3,7,11-13}]{sources/_autogen_/hello-alt.c_pmix_get}% + +\pmixCodeInlineC{printf("Hello World");} prints ``Hello World''. +``` + +Import Python code + +``` +The inline code \pmixCodeInlinePy{print("Hello World")} prints ``Hello World''. + +\pmixCodeImportPy{sources/_autogen_/hello.py_pmix_py}% +``` \ No newline at end of file diff --git a/sources/hello-alt.c b/sources/hello-alt.c deleted file mode 100644 index a4a19132..00000000 --- a/sources/hello-alt.c +++ /dev/null @@ -1,110 +0,0 @@ -/* - * Copyright (c) 2004-2010 The Trustees of Indiana University and Indiana - * University Research and Technology - * Corporation. All rights reserved. - * Copyright (c) 2004-2011 The University of Tennessee and The University - * of Tennessee Research Foundation. All rights - * reserved. - * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, - * University of Stuttgart. All rights reserved. - * Copyright (c) 2004-2005 The Regents of the University of California. - * All rights reserved. - * Copyright (c) 2006-2013 Los Alamos National Security, LLC. - * All rights reserved. - * Copyright (c) 2009-2012 Cisco Systems, Inc. All rights reserved. - * Copyright (c) 2011 Oak Ridge National Labs. All rights reserved. - * Copyright (c) 2013-2018 Intel, Inc. All rights reserved. - * Copyright (c) 2015 Mellanox Technologies, Inc. All rights reserved. - * Copyright (c) 2020 IBM Corporation. All rights reserved. - * $COPYRIGHT$ - * - * Additional copyrights may follow - * - * $HEADER$ - * - */ - -#define _GNU_SOURCE -#include -#include -#include -#include -#include -#include - -// -#include - -int main(int argc, char **argv) -{ - // - // - pmix_status_t rc = PMIX_SUCCESS; - // - pmix_proc_t myproc; - // - pmix_value_t *val; - uint16_t localrank; - // - pid_t pid; - char hostname[1024]; - - pid = getpid(); - gethostname(hostname, 1024); - - // - /* Initialize PMIx - client role */ - rc = PMIx_Init(&myproc, NULL, 0); - if (PMIX_SUCCESS != rc) { - fprintf(stderr, "Client ns %s rank %d: PMIx_Init failed: %s\n", - myproc.nspace, myproc.rank, PMIx_Error_string(rc)); - return 1; - } - // - - // - /* Get our rank local to this node */ - rc = PMIx_Get(&myproc, PMIX_LOCAL_RANK, NULL, 0, &val); - if (PMIX_SUCCESS != rc) { - fprintf(stderr, - "Client ns %s rank %d: PMIx_Get local rank failed: %s\n", - myproc.nspace, myproc.rank, PMIx_Error_string(rc)); - goto done; - } - localrank = val->data.uint16; - PMIX_VALUE_RELEASE(val); - // - - printf("Client ns %s rank %d pid %lu: Running on host %s localrank %d\n", - myproc.nspace, myproc.rank, (unsigned long)pid, hostname , - (int)localrank); - - /* Fence to hold all processes in this namespace */ - pmix_proc_t wildproc; - PMIX_PROC_CONSTRUCT(&wildproc); - (void)strncpy(wildproc.nspace, myproc.nspace, PMIX_MAX_NSLEN); - wildproc.rank = PMIX_RANK_WILDCARD; - - rc = PMIx_Fence(&wildproc, 1, NULL, 0); - if (PMIX_SUCCESS != rc) { - fprintf(stderr, - "Client ns %s rank %d: PMIx_Fence failed: %s\n", - myproc.nspace, myproc.rank, PMIx_Error_string(rc)); - goto done; - } - - done: - /* Finalize the PMIx library */ - printf("Client ns %s rank %d: Finalizing\n", myproc.nspace, myproc.rank); - rc = PMIx_Finalize(NULL, 0); - if (PMIX_SUCCESS != rc) { - fprintf(stderr, "Client ns %s rank %d:PMIx_Finalize failed: %s\n", - myproc.nspace, myproc.rank, PMIx_Error_string(rc)); - } else { - printf("Client ns %s rank %d:PMIx_Finalize successfully completed\n", - myproc.nspace, myproc.rank); - } - - return rc; -} - diff --git a/sources/hello.py b/sources/hello.py new file mode 100644 index 00000000..f582255b --- /dev/null +++ b/sources/hello.py @@ -0,0 +1,3 @@ +# +print("Hello World") +#