├── .clang-format ├── .github ├── issue_template.md ├── pull_request_template.md └── workflows │ └── main.yml ├── .gitignore ├── .travis.yml ├── Makefile ├── README.md ├── content ├── atomics_intro.tex ├── backmatter.tex ├── collective_intro.tex ├── context_intro.tex ├── coverpage.tex ├── environment_variables.tex ├── execution_model.tex ├── frontmatter.tex ├── glossary.tex ├── interoperability.tex ├── language_bindings_and_conformance.tex ├── library_constants.tex ├── library_handles.tex ├── memmgmt_intro.tex ├── memory_model.tex ├── p2p_sync_intro.tex ├── profiling_interface.tex ├── programming_model_overview.tex ├── rma_intro.tex ├── sessions_intro.tex ├── shmem_addr_accessible.tex ├── shmem_align.tex ├── shmem_alltoall.tex ├── shmem_alltoalls.tex ├── shmem_atomic_add.tex ├── shmem_atomic_and.tex ├── shmem_atomic_compare_swap.tex ├── shmem_atomic_compare_swap_nbi.tex ├── shmem_atomic_fetch.tex ├── shmem_atomic_fetch_add.tex ├── shmem_atomic_fetch_add_nbi.tex ├── shmem_atomic_fetch_and.tex ├── shmem_atomic_fetch_and_nbi.tex ├── shmem_atomic_fetch_inc.tex ├── shmem_atomic_fetch_inc_nbi.tex ├── shmem_atomic_fetch_nbi.tex ├── shmem_atomic_fetch_or.tex ├── shmem_atomic_fetch_or_nbi.tex ├── shmem_atomic_fetch_xor.tex ├── shmem_atomic_fetch_xor_nbi.tex ├── shmem_atomic_inc.tex ├── shmem_atomic_or.tex ├── shmem_atomic_set.tex ├── shmem_atomic_swap.tex ├── shmem_atomic_swap_nbi.tex ├── shmem_atomic_xor.tex ├── shmem_barrier.tex ├── shmem_barrier_all.tex ├── shmem_broadcast.tex ├── shmem_calloc.tex ├── shmem_collect.tex ├── shmem_ctx_create.tex ├── shmem_ctx_destroy.tex ├── shmem_ctx_get_team.tex ├── shmem_ctx_session_config_t.tex ├── shmem_ctx_session_start.tex ├── shmem_ctx_session_stop.tex ├── shmem_fence.tex ├── shmem_finalize.tex ├── shmem_free.tex ├── shmem_g.tex ├── shmem_get.tex ├── shmem_get_nbi.tex ├── shmem_global_exit.tex ├── shmem_ibget.tex ├── shmem_ibput.tex ├── shmem_iget.tex ├── shmem_info_get_name.tex ├── shmem_info_get_version.tex ├── shmem_init.tex ├── shmem_init_thread.tex ├── shmem_iput.tex ├── shmem_lock.tex ├── shmem_malloc.tex ├── shmem_malloc_hints.tex ├── shmem_my_pe.tex ├── shmem_n_pes.tex ├── shmem_p.tex ├── shmem_pcontrol.tex ├── shmem_pe_accessible.tex ├── shmem_pe_quiet.tex ├── shmem_ptr.tex ├── shmem_put.tex ├── shmem_put_nbi.tex ├── shmem_put_signal.tex ├── shmem_put_signal_nbi.tex ├── shmem_query_initialized.tex ├── shmem_query_thread.tex ├── shmem_quiet.tex ├── shmem_realloc.tex ├── shmem_reductions.tex ├── shmem_scan.tex ├── shmem_signal_add.tex ├── shmem_signal_fetch.tex ├── shmem_signal_set.tex ├── shmem_signal_wait_until.tex ├── shmem_sync.tex ├── shmem_sync_all.tex ├── shmem_team_config_t.tex ├── shmem_team_create_ctx.tex ├── shmem_team_destroy.tex ├── shmem_team_get_config.tex ├── shmem_team_my_pe.tex ├── shmem_team_n_pes.tex ├── shmem_team_ptr.tex ├── shmem_team_split_2d.tex ├── shmem_team_split_strided.tex ├── shmem_team_translate_pe.tex ├── shmem_test.tex ├── shmem_test_all.tex ├── shmem_test_all_vector.tex ├── shmem_test_any.tex ├── shmem_test_any_vector.tex ├── shmem_test_some.tex ├── shmem_test_some_vector.tex ├── shmem_wait_until.tex ├── shmem_wait_until_all.tex ├── shmem_wait_until_all_vector.tex ├── shmem_wait_until_any.tex ├── shmem_wait_until_any_vector.tex ├── shmem_wait_until_some.tex ├── shmem_wait_until_some_vector.tex ├── signaling.tex ├── start_pes.tex ├── synchronization_model.tex ├── teams_intro.tex ├── the_openshmem_effort.tex └── threads_intro.tex ├── example_code ├── .gitignore ├── Makefile ├── amo_scenario_1.c ├── amo_scenario_2.c ├── amo_scenario_3.c ├── amo_scenario_4.c ├── hello-openshmem-c.output ├── hello-openshmem.c ├── hybrid_mpi_mapping_id.c ├── hybrid_mpi_mapping_id_shmem_comm.c ├── pshmem_example.c ├── pshmem_no_weak_symbol.c ├── pshmem_weak_symbol_1.c ├── pshmem_weak_symbol_2.c ├── shmem_alltoall_example.c ├── shmem_alltoalls_example.c ├── shmem_atomic_add_example.c ├── shmem_atomic_compare_swap_example.c ├── shmem_atomic_fetch_add_example.c ├── shmem_atomic_fetch_inc_example.c ├── shmem_atomic_inc_example.c ├── shmem_atomic_swap_example.c ├── shmem_barrier_example.c ├── shmem_barrierall_example.c ├── shmem_broadcast_example.c ├── shmem_collect_example.c ├── shmem_ctx.c ├── shmem_ctx_invalid.c ├── shmem_ctx_pipelined_reduce.c ├── shmem_ctx_session_example.c ├── shmem_fence_example.c ├── shmem_finalize_example.c ├── shmem_g_example.c ├── shmem_global_exit_example.c ├── shmem_init_example.c ├── shmem_iput_example.c ├── shmem_lock_example.c ├── shmem_npes_example.c ├── shmem_p_example.c ├── shmem_ptr_example.c ├── shmem_put_example.c ├── shmem_put_signal_example.c ├── shmem_quiet_example.c ├── shmem_reduce_example.c ├── shmem_scan_example.c ├── shmem_sync_example.c ├── shmem_team_context.c ├── shmem_team_split_2D.c ├── shmem_team_split_strided.c ├── shmem_team_translate_pe.c ├── shmem_test_any_example.c ├── shmem_test_example1.c ├── shmem_test_some_example.c ├── shmem_wait_until_all.c ├── shmem_wait_until_any_all2all_sum.c ├── shmem_wait_until_any_vector.c ├── shmem_wait_until_some_all2all_sum.c ├── writing_shmem_example.c └── writing_shmem_example.output ├── figures ├── OpenSHMEM_Pound.png ├── barrier.graffle ├── barrier.pdf ├── barrier.svg ├── barrierall.graffle ├── barrierall.pdf ├── barrierall.svg ├── fence.graffle ├── fence.pdf ├── fence.svg ├── mem_model.graffle ├── mem_model.pdf ├── mem_model.svg ├── quiet.graffle ├── quiet.pdf ├── quiet.svg ├── sync.pdf ├── sync.svg ├── wait.graffle ├── wait.pdf ├── wait.svg ├── wait_v1_4.graffle ├── wait_v1_4.pdf └── wait_v1_4.svg ├── main_spec.tex └── utils ├── defs.tex └── packages.tex /.clang-format: -------------------------------------------------------------------------------- 1 | BasedOnStyle: LLVM 2 | BreakBeforeBraces: Custom 3 | BraceWrapping: 4 | BeforeElse: true 5 | ColumnLimit: 93 6 | -------------------------------------------------------------------------------- /.github/issue_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Issue Template 3 | about: Template for OpenSHMEM Issues 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | # Problem Statement 11 | 12 | 13 | 14 | # Proposed Changes 15 | 16 | 17 | 18 | # Impact on Implementations 19 | 20 | 21 | 22 | # Impact on Users 23 | 24 | 25 | 26 | # References and Pull Requests 27 | 28 | 29 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | # Summary of changes 2 | 3 | # Proposal Checklist 4 | - [ ] Link to issue(s) 5 | - [ ] Changelog entry 6 | - [ ] Reviewed for changes to front matter 7 | - [ ] Reviewed for changes to back matter 8 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: [pull_request] 4 | 5 | jobs: 6 | build: 7 | 8 | runs-on: ubuntu-latest 9 | 10 | steps: 11 | - uses: actions/checkout@v1 12 | - name: Install dependencies 13 | run: | 14 | sudo apt-get update 15 | sudo apt-get install texlive-latex-base texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra 16 | - name: Build PDF 17 | run: make LATEXOPT="-interaction nonstopmode -halt-on-error" 18 | - name: Rename PDF 19 | run: mv main_spec.pdf openshmem-draft-${{ github.event.pull_request.head.sha }}.pdf 20 | - name: Upload PDF artifact 21 | uses: actions/upload-artifact@v4 22 | with: 23 | name: openshmem-draft-${{ github.event.pull_request.head.sha }} 24 | path: openshmem-draft-${{ github.event.pull_request.head.sha }}.pdf 25 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | main_spec.aux 2 | main_spec.idx 3 | main_spec.ilg 4 | main_spec.ind 5 | main_spec.log 6 | main_spec.out 7 | main_spec.pdf 8 | main_spec.toc 9 | *~ 10 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: required 2 | dist: trusty 3 | 4 | addons: 5 | apt: 6 | packages: 7 | - texlive-latex-base 8 | - texlive-latex-recommended 9 | - texlive-latex-extra 10 | - texlive-generic-recommended 11 | - latex-xcolor 12 | - texlive-fonts-recommended 13 | - texlive-fonts-extra 14 | 15 | before_install: 16 | install: 17 | script: 18 | - make LATEXOPT=-halt-on-error 19 | - make clean 20 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | TARGET = main_spec 2 | SOURCES = $(shell find . -name '*.tex' -print) 3 | FIGURES = $(shell find figures -name '*.pdf' -print) 4 | EXAMPLES = $(shell find example_code -name '*.[c,f]*' -print) 5 | 6 | .PHONY: all 7 | all: ${TARGET}.pdf 8 | 9 | ${TARGET}.pdf: ${SOURCES} ${FIGURES} ${EXAMPLES} 10 | pdflatex $(LATEXOPT) ${TARGET} 11 | makeindex ${TARGET} 12 | pdflatex $(LATEXOPT) ${TARGET} 13 | makeindex ${TARGET} 14 | pdflatex $(LATEXOPT) ${TARGET} 15 | 16 | RM ?= rm -f 17 | CLEAN_EXTENSIONS = aux idx ilg ind log out pdf toc 18 | .PHONY: clean 19 | clean: 20 | for e in ${CLEAN_EXTENSIONS}; do $(RM) ${TARGET}.$$e; done 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OpenSHMEM Application Programming Interface 2 | 3 | This repository contains the LaTeX source for the OpenSHMEM specification. 4 | 5 | ## Organization of the Repository 6 | 7 | The in-progress development work of the next version of the OpenSHMEM specification is maintained in the ```master``` branch. Each published version of the specification is marked with a tag of the format ```vX.Y``` where X and Y are the major and minor version numbers. 8 | 9 | ## Proposing Changes to the Specification 10 | 11 | Changes should be proposed as pull requests against the ```master``` branch. Text changes must be ratified through the OpenSHMEM specification committee. 12 | -------------------------------------------------------------------------------- /content/environment_variables.tex: -------------------------------------------------------------------------------- 1 | \TableIndex{Environment Variables} 2 | 3 | The \openshmem specification provides a set of environment variables that allows 4 | users to configure the \openshmem implementation and receive information about 5 | the implementation. The implementations of the specification are free to define 6 | additional variables. Currently, the specification defines four environment 7 | variables. All environment variables that start with \VAR{SMA\_*} are 8 | deprecated, but currently supported for backwards compatibility. 9 | If both \VAR{SHMEM\_}- and \VAR{SMA\_}-prefixed environment variables 10 | are set, then the value in the \VAR{SHMEM\_}-prefixed environment variable 11 | establishes the controlling value. 12 | Refer to the \ENVVAR{SMA\_*} environment variables deprecation rationale, 13 | \cref{dep:envvar_sma}, for more details. 14 | 15 | \medskip{} 16 | 17 | \begin{longtable}{|p{0.260\textwidth}|p{0.145\textwidth}|p{0.50\textwidth}|} 18 | \hline 19 | \textbf{Variable} & \textbf{Value} & \textbf{Description} 20 | \tabularnewline\hline 21 | %% 22 | \EnvVarDecl{SHMEM\_VERSION} 23 | & Any 24 | & Print the library version at start-up 25 | \tabularnewline\hline 26 | %% 27 | \EnvVarDecl{SHMEM\_INFO} 28 | & Any 29 | & Print helpful text about all these environment variables 30 | \tabularnewline\hline 31 | %% 32 | \EnvVarDecl{SHMEM\_SYMMETRIC\_SIZE} 33 | & Non-negative integer or floating point value with an optional character 34 | suffix 35 | & Specifies the size (in bytes) of the symmetric heap memory per \ac{PE}. 36 | The resulting size is implementation-defined and must be at least as large as 37 | the integer ceiling of the product of the numeric prefix and the scaling 38 | factor. The allowed character suffixes for the scaling factor are as 39 | follows: 40 | \begin{itemize} 41 | \item k or K multiplies by \(2^{10}\) (kibibytes) 42 | \item m or M multiplies by \(2^{20}\) (mebibytes) 43 | \item g or G multiplies by \(2^{30}\) (gibibytes) 44 | \item t or T multiplies by \(2^{40}\) (tebibytes) 45 | \end{itemize} 46 | For example, string \enquote{20m} is equivalent to the integer value 47 | 20971520, or 20 mebibytes. Similarly the string \enquote{3.1M} is 48 | equivalent to the integer value 3250586. 49 | Only one multiplier is recognized and any characters following the 50 | multiplier are ignored, so \enquote{20kk} will not produce the same 51 | result as \enquote{20m}. Usage of string \enquote{.5m} will yield the 52 | same result as the string \enquote{0.5m}. 53 | 54 | An invalid value for \ENVVAR{SHMEM\_SYMMETRIC\_SIZE} is an error, which the 55 | \openshmem library shall report by either returning a nonzero value from 56 | \FUNC{shmem\_init\_thread} or causing program termination. 57 | \tabularnewline\hline 58 | %% 59 | \EnvVarDecl{SHMEM\_DEBUG} 60 | & Any 61 | & Enable debugging messages 62 | \tabularnewline\hline 63 | \end{longtable} 64 | 65 | \medskip{} 66 | -------------------------------------------------------------------------------- /content/frontmatter.tex: -------------------------------------------------------------------------------- 1 | \hypersetup{pageanchor=true,citecolor=blue} 2 | 3 | % Set header/footer for opening content 4 | \pagestyle{fancy} 5 | \fancyhead{} 6 | \fancyhead[L]{\insertDocVersion} 7 | \fancyhead[C]{--- DRAFT ---} 8 | \SetWatermarkText{DRAFT} 9 | \SetWatermarkScale{1} 10 | \SetWatermarkLightness{.91} 11 | \fancyfoot[C]{\thepage} %affects page numbering for the first pages, 12 | %except the first ToC page 13 | 14 | \pagenumbering{roman} %sets coverpage and toc page numbers to roman numerals 15 | 16 | \input{content/coverpage} 17 | 18 | \setcounter{tocdepth}{4} 19 | \setcounter{secnumdepth}{4} 20 | \tableofcontents 21 | 22 | \mainmatter % included for use of documenttype 'book' 23 | 24 | % Set header/footer for main content 25 | \pagestyle{fancy} %replacing {headings} with {fancy} for customization 26 | \fancyhf{} 27 | \fancyhead[L]{\leftmark} 28 | \fancyhead[R]{\thepage} 29 | \renewcommand{\headrulewidth}{0pt} 30 | \let\thesectionOrig\thesection % Used by backmatter to restore Annex numbering. 31 | \renewcommand{\thesection}{\arabic{section}} 32 | 33 | { %using setlength to force standardized spacing, if needed 34 | % this command is ended in backmatter.tex 35 | %\setlength{\baselineskip}{3pt plus 3pt minus 3pt} 36 | 37 | \setlength{\parskip}{3pt} 38 | -------------------------------------------------------------------------------- /content/glossary.tex: -------------------------------------------------------------------------------- 1 | \begin{description} 2 | 3 | \item[Blocking] An \openshmem routine for which return from a call to 4 | that routine guarantees local completion for its associated local 5 | buffers. 6 | 7 | \item[Local completion] of an \openshmem operation indicates that all 8 | local objects involved in the operation are locally complete. 9 | 10 | For an \openshmem operation that reads a local object of 11 | memory---for example, the \source{} argument of \FUNC{shmem\_put} 12 | or, for only the root \ac{PE}, \FUNC{shmem\_team\_broadcast}---local 13 | completion of that object specifies the point (in time) after which 14 | a write (or update) to that object by the \ac{PE} initiating the 15 | operation would not affect the value(s) read by the \openshmem 16 | implementation in performing the operation. 17 | 18 | For an \openshmem operation that writes a local object of 19 | memory---for example, the \dest{} argument of \FUNC{shmem\_get} or 20 | \FUNC{shmem\_team\_broadcast}---local completion of that object 21 | specifies the point after which a read of that local object by the 22 | \ac{PE} initiating the operation will return the value(s) produced 23 | by the \openshmem implementation in performing the operation. 24 | 25 | \item[Nonblocking] An \openshmem routine for which return from a call 26 | to that routine guarantees neither local nor remote completion. 27 | 28 | \item[Remote completion] of an \openshmem operation indicates that all 29 | remote objects involved in the operation are remotely complete. 30 | 31 | For an \openshmem operation that reads a remote object of 32 | memory---for example, the \source{} argument of \FUNC{shmem\_get} or 33 | \FUNC{shmem\_team\_alltoall}---remote completion of that object 34 | specifies the point (in time) after which a write (or update) to 35 | that object by any \ac{PE} would not affect the value(s) read by the 36 | \openshmem implementation in performing the operation. 37 | 38 | For an \openshmem operation that writes a remote object of 39 | memory---for example, the \dest{} argument of \FUNC{shmem\_put} or 40 | \FUNC{shmem\_team\_alltoall}---remote completion of that object 41 | specifies the point after which a read of that remote object by the 42 | target \ac{PE} will return the value(s) produced by the \openshmem 43 | implementation in performing the operation. 44 | 45 | See \FUNC{shmem\_quiet} for mechanisms that ensure remote completion 46 | (Section~\ref{subsec:shmem_quiet}). 47 | 48 | \end{description} 49 | -------------------------------------------------------------------------------- /content/language_bindings_and_conformance.tex: -------------------------------------------------------------------------------- 1 | \openshmem provides ISO \Cstd language bindings. Any implementation that 2 | provides \Cstd bindings can claim conformance to the specification. The 3 | \openshmem header file \HEADER{shmem.h} for \Cstd must contain only the 4 | interfaces and constant names defined in this specification. 5 | 6 | \openshmem \acp{API} can be implemented as functions, inline functions, or 7 | macros. However, implementing the interfaces using inline functions or macros 8 | could limit the use of external profiling tools and high-level compiler 9 | optimizations. An \openshmem program should avoid defining routine names, 10 | variables, or other identifiers with the prefix ``shmem'' using any combination 11 | of uppercase letters, lowercase letters, and underscores. 12 | 13 | All extensions to the \openshmem \ac{API} that are not part of this 14 | specification must be defined in the \HEADER{shmemx.h} header file, with the 15 | following exceptions. 16 | 17 | \begin{enumerate} 18 | \item Extensions to the \openshmem interfaces that add support for 19 | additional datatypes. 20 | \item Implementation-specific constants, types, and macros that use a 21 | consistent, implementation-defined prefix. 22 | \item Extensions to the type-generic interfaces. 23 | \end{enumerate} 24 | 25 | The \HEADER{shmemx.h} 26 | header file must exist, even if no extensions are provided. Any extensions 27 | shall use the \FUNC{shmemx\_} prefix for all routine, variable, and constant 28 | names. 29 | -------------------------------------------------------------------------------- /content/library_handles.tex: -------------------------------------------------------------------------------- 1 | \TableIndex{Library Handles} 2 | \TableIndex{Handles} 3 | 4 | The \openshmem library provides a set of predefined named constant handles. 5 | All named constants can be used in initialization expressions or assignments, 6 | but not necessarily in array declarations or as labels in \Cstd switch statements. 7 | This implies named constants to be link-time but not necessarily compile-time 8 | constants. 9 | 10 | \begin{longtable}{|p{0.45\textwidth}|p{0.5\textwidth}|} 11 | \hline 12 | \textbf{Handle} & \textbf{Description} 13 | \tabularnewline \hline 14 | \endhead 15 | %% 16 | \LibHandleDecl{SHMEM\_TEAM\_WORLD} & 17 | Handle of type \CTYPE{shmem\_team\_t} that corresponds to the world 18 | team that contains all \acp{PE} in the \openshmem program. All point-to-point 19 | communication operations and collective synchronizations that do not specify a team 20 | are performed on the world team. 21 | See Section~\ref{subsec:team} for more detail about its use. 22 | \tabularnewline \hline 23 | %% 24 | \LibHandleDecl{SHMEM\_TEAM\_SHARED} & 25 | Handle of type \CTYPE{shmem\_team\_t} that corresponds to a team of \acp{PE} 26 | that share a memory domain. \LibHandleRef{SHMEM\_TEAM\_SHARED} refers to 27 | the team of all \acp{PE} that would mutually return a non-null address from a 28 | call to \FUNC{shmem\_ptr} or \FUNC{shmem\_team\_ptr} for all symmetric heap objects. That is, 29 | \FUNC{shmem\_ptr} and \FUNC{shmem\_team\_ptr} must return a non-null pointer to the local \ac{PE} for all 30 | symmetric heap objects on all target \acp{PE} in the team. This means that 31 | symmetric heap objects on each \ac{PE} are 32 | directly load/store accessible by all \acp{PE} in the team. 33 | See Section~\ref{subsec:team} for more detail about its use. 34 | \tabularnewline \hline 35 | %% 36 | \LibHandleDecl{SHMEM\_CTX\_DEFAULT} & 37 | Handle of type \CTYPE{shmem\_ctx\_t} that corresponds to the 38 | default communication context. All point-to-point communication operations 39 | and synchronizations that do not specify a context are performed on the 40 | default context. 41 | See Section~\ref{sec:ctx} for more detail about its use. 42 | \tabularnewline \hline 43 | %% 44 | \end{longtable} 45 | -------------------------------------------------------------------------------- /content/memmgmt_intro.tex: -------------------------------------------------------------------------------- 1 | \openshmem provides a set of \acp{API} for managing the symmetric heap. The 2 | \acp{API} allow one to dynamically allocate, deallocate, reallocate, and align 3 | symmetric data objects in the symmetric heap. 4 | 5 | The symmetric memory allocation routines differ from the private heap 6 | allocation routines in that they must be called by all \acp{PE} in 7 | the world team. When specified, each of these routines includes at 8 | least one call to a procedure that is semantically equivalent to 9 | \FUNC{shmem\_barrier\_all}. This ensures that all \acp{PE} 10 | participate in the memory management, and that the memory on other 11 | \acp{PE} can be used as soon as the local \ac{PE} returns. The 12 | implicit barriers performed by these routines quiet the default 13 | context. It is the user's responsibility to ensure that no 14 | communication operations involving the given memory block are pending 15 | on other contexts prior to calling the \FUNC{shmem\_free} and 16 | \FUNC{shmem\_realloc} routines. 17 | 18 | The total size of the symmetric heap is determined at job startup. One can 19 | specify the size of the heap using the \ENVVAR{SHMEM\_SYMMETRIC\_SIZE} environment 20 | variable (where available). 21 | 22 | \begin{DeprecateBlock} 23 | As of \openshmem[1.2] the use of \FUNC{shmalloc}, \FUNC{shmemalign}, 24 | \FUNC{shfree}, and \FUNC{shrealloc} has been deprecated. Although \openshmem 25 | libraries are required to support the calls, users are encouraged to use 26 | \FUNC{shmem\_malloc}, \FUNC{shmem\_align}, \FUNC{shmem\_free}, and 27 | \FUNC{shmem\_realloc} instead. The behavior and signature of the routines 28 | remains unchanged from the deprecated versions. 29 | \end{DeprecateBlock} 30 | 31 | \parimpnotes{ 32 | The symmetric heap allocation routines always return the symmetric 33 | addresses of corresponding symmetric objects across all 34 | \acp{PE}. The \openshmem specification does not require that the 35 | virtual addresses are equal across all \acp{PE}. Nevertheless, the 36 | implementation must avoid costly address translation operations in 37 | the communication path, including $O(N)$ memory translation tables, 38 | where $N$ is the number of \acp{PE}. In order to avoid address 39 | translations, the implementation may re-map the allocated block of 40 | memory based on agreed virtual address. Additionally, some 41 | operating systems provide an option to disable virtual address 42 | randomization, which enables predictable allocation of virtual 43 | memory addresses. 44 | } 45 | 46 | -------------------------------------------------------------------------------- /content/sessions_intro.tex: -------------------------------------------------------------------------------- 1 | \openshmem \emph{sessions} provide a mechanism for applications to inform the 2 | \openshmem library of an upcoming sequence of communication routines that 3 | exhibit suitable patterns for runtime optimizations. 4 | A session is associated with a specific \openshmem communication context 5 | (Section~\ref{sec:ctx}), and it indicates the beginning and ending of 6 | communication phases on that context. 7 | The \FUNC{shmem\_ctx\_session\_start} routine indicates the beginning of a session, 8 | and the \FUNC{shmem\_ctx\_session\_stop} routine indicates the end of a session. 9 | The \LibConstRef{SHMEM\_CTX\_SESSION\_*} options (Table~\ref{session_opts}) indicate 10 | which patterns of \openshmem RMA and AMO routines will occur within a session. 11 | These options serve only as \textit{hints} to the library; it is up to the 12 | implementation whether or not to apply any optimizations within a session. 13 | A session may be provided a configuration argument that specifies attributes 14 | associated with the session. This configuration argument is of type 15 | \CTYPE{shmem\_ctx\_session\_config\_t}, which is detailed further in 16 | Section~\ref{subsec:shmem_team_config_t}. 17 | 18 | Usage of the \openshmem session APIs on a particular context must comply with 19 | the requirements of all options set on that context. 20 | Starting and stopping \openshmem sessions should not affect the completion or 21 | ordering semantics of any \openshmem routines in the program. 22 | For these reasons, multi-threaded \openshmem programs may require additional 23 | thread synchronization to ensure sessions hints are correctly applied to 24 | shareable contexts. 25 | Because sessions are associated with an \openshmem communication context, 26 | routines not performed on a communication context (like collective routines) 27 | are ineligible for session hints. 28 | 29 | The \FUNC{shmem\_ctx\_session\_config\_t} object requires the \CONST{SIZE\_MAX} 30 | macro defined in \HEADER{stdint.h} by \Cstd[99]~\S7.18.3 and 31 | \Cstd[11]~\S7.20.3. 32 | -------------------------------------------------------------------------------- /content/shmem_addr_accessible.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Determines whether an address is accessible via \openshmem data transfer 3 | routines from the specified remote \ac{PE}. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{Csynopsis} 9 | int @\FuncDecl{shmem\_addr\_accessible}@(const void *addr, int pe); 10 | \end{Csynopsis} 11 | 12 | \begin{apiarguments} 13 | \apiargument{IN}{addr}{Local address of data object to query.} 14 | \apiargument{IN}{pe}{Integer id of a remote \ac{PE}.} 15 | \end{apiarguments} 16 | 17 | \apidescription{ 18 | \FUNC{shmem\_addr\_accessible} is a query routine that indicates whether 19 | the address \VAR{addr} can be used to access the given data object on the 20 | specified \ac{PE} via \openshmem routines. 21 | 22 | This routine verifies that the data object is symmetric and accessible with 23 | respect to a remote \ac{PE} via \openshmem data transfer routines. The 24 | specified address \VAR{addr} is the local address of the data object on the 25 | local \ac{PE}. 26 | } 27 | 28 | \apireturnvalues{ 29 | The return value is \CONST{1} if the local address \VAR{addr} is also a symmetric 30 | address and the given data object is accessible via \openshmem routines on 31 | the specified remote \ac{PE}; otherwise, it is \CONST{0}. 32 | } 33 | 34 | \apinotes{ 35 | This routine may be particularly useful for hybrid programming with other 36 | communication libraries (such as \ac{MPI}) or parallel languages. For 37 | example, when an \ac{MPI} job uses \ac{MPMD} mode, multiple executable 38 | \ac{MPI} programs may use \openshmem routines. In such cases, static 39 | memory, such as a \Cstd global variable, is 40 | symmetric between processes running from the same executable file, but is 41 | not symmetric between processes running from different executable files. 42 | Data allocated from the symmetric heap (e.g., using \FUNC{shmem\_malloc}) 43 | is symmetric across the same or different executable files. 44 | } 45 | 46 | \end{apidefinition} 47 | -------------------------------------------------------------------------------- /content/shmem_align.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Collectively allocate symmetric memory with a specified alignment. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void *@\FuncDecl{shmem\_align}@(size_t alignment, size_t size); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{alignment}{Byte alignment of the block allocated from the 13 | symmetric heap.} 14 | \apiargument{IN}{size}{The size, in bytes, of a block to be 15 | allocated from the symmetric heap.} 16 | \end{apiarguments} 17 | 18 | 19 | \apidescription{ 20 | The \FUNC{shmem\_align} routine is a collective operation on the 21 | world team that allocates a block in the symmetric 22 | heap that has a byte alignment specified by the \VAR{alignment} 23 | argument. The value of \VAR{alignment} shall be a multiple of 24 | \CONST{sizeof(void *)} that is also a power of two; otherwise, the 25 | behavior is undefined. When \VAR{size} is zero, the 26 | \FUNC{shmem\_align} routine performs no action and returns a null 27 | pointer; otherwise, \FUNC{shmem\_align} calls a barrier on exit. 28 | 29 | The value of the \VAR{alignment} and \VAR{size} arguments must be 30 | identical on all \acp{PE}; otherwise, the behavior is undefined. 31 | } 32 | 33 | \apireturnvalues{ 34 | The \FUNC{shmem\_align} routine returns an aligned symmetric address 35 | whose value is a multiple of \VAR{alignment}; otherwise, it returns 36 | a null pointer. 37 | } 38 | 39 | \end{apidefinition} 40 | -------------------------------------------------------------------------------- /content/shmem_atomic_add.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Performs an atomic add operation on a remote symmetric data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | void @\FuncDecl{shmem\_atomic\_add}@(TYPE *dest, TYPE value, int pe); 9 | void @\FuncDecl{shmem\_atomic\_add}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the standard \ac{AMO} types specified by 12 | Table~\ref{stdamotypes}. 13 | 14 | \begin{Csynopsis} 15 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_add}@(TYPE *dest, TYPE value, int pe); 16 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_add}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the standard \ac{AMO} types and has a corresponding 19 | \TYPENAME{} specified by Table~\ref{stdamotypes}. 20 | 21 | \begin{DeprecateBlock} 22 | \begin{C11synopsis} 23 | void @\FuncDecl{shmem\_add}@(TYPE *dest, TYPE value, int pe); 24 | \end{C11synopsis} 25 | where \TYPE{} is one of \{\CTYPE{int}, \CTYPE{long}, \CTYPE{long long}\}. 26 | 27 | \begin{Csynopsis} 28 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_add}@(TYPE *dest, TYPE value, int pe); 29 | \end{Csynopsis} 30 | where \TYPE{} is one of \{\CTYPE{int}, \CTYPE{long}, \CTYPE{long long}\} 31 | and has a corresponding \TYPENAME{} specified by Table~\ref{stdamotypes}. 32 | \end{DeprecateBlock} 33 | 34 | \begin{apiarguments} 35 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 36 | When this argument is not provided, the operation is performed on 37 | the default context.} 38 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 39 | The type of \dest{} should match that implied in the SYNOPSIS section.} 40 | \apiargument{IN}{value}{The operand to the atomic add operation. 41 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 42 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 43 | with the given \VAR{ctx} when provided, or the default context otherwise.} 44 | \end{apiarguments} 45 | 46 | \apidescription{ 47 | The \FUNC{shmem\_atomic\_add} routine performs an atomic add operation. It adds 48 | \VAR{value} to \dest{} on \ac{PE} \VAR{pe} and atomically updates the \dest{} 49 | without returning the value. 50 | } 51 | 52 | \apireturnvalues{ 53 | None. 54 | } 55 | 56 | \begin{apiexamples} 57 | 58 | \apicexample 59 | {} 60 | {./example_code/shmem_atomic_add_example.c} 61 | {} 62 | 63 | \end{apiexamples} 64 | 65 | \end{apidefinition} 66 | -------------------------------------------------------------------------------- /content/shmem_atomic_and.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Atomically perform a non-fetching bitwise AND operation on a 3 | remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_and}@(TYPE *dest, TYPE value, int pe); 10 | void @\FuncDecl{shmem\_atomic\_and}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the bitwise \ac{AMO} types specified by 13 | Table~\ref{bitamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_and}@(TYPE *dest, TYPE value, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_and}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the bitwise \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{bitamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 25 | When this argument is not provided, the operation is performed on 26 | the default context.} 27 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 28 | The type of \dest{} should match that implied in the SYNOPSIS section.} 29 | \apiargument{IN}{value}{The operand to the bitwise AND operation. 30 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 32 | with the given \VAR{ctx} when provided, or the default context otherwise.} 33 | \end{apiarguments} 34 | 35 | \apidescription{ 36 | \FUNC{shmem\_atomic\_and} atomically performs a non-fetching bitwise AND 37 | on the remotely accessible data object pointed to by \VAR{dest} at PE 38 | \VAR{pe} with the operand \VAR{value}. 39 | } 40 | 41 | \apireturnvalues{ 42 | None. 43 | } 44 | 45 | \end{apidefinition} 46 | -------------------------------------------------------------------------------- /content/shmem_atomic_compare_swap_nbi.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | The nonblocking atomic routine provides a method for performing an atomic 3 | conditional swap on a remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_compare\_swap\_nbi}@(TYPE *fetch, TYPE *dest, TYPE cond, TYPE value, int pe); 10 | void @\FuncDecl{shmem\_atomic\_compare\_swap\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE cond, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the standard \ac{AMO} types specified by 13 | Table~\ref{stdamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_compare\_swap\_nbi}@(TYPE *fetch, TYPE *dest, TYPE cond, TYPE value, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_compare\_swap\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE cond, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the standard \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{stdamotypes}. 21 | 22 | \begin{apiarguments} 23 | \apiargument{IN}{ctx}{A context handle specifying the context on which to 24 | perform the operation. When this argument is not provided, the operation 25 | is performed on the default context.} 26 | \apiargument{OUT}{fetch}{Local address of data object to be updated. 27 | The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} 28 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 29 | The type of \dest{} should match that implied in the SYNOPSIS section.} 30 | \apiargument{IN}{cond}{\VAR{cond} is compared to the remote \VAR{dest} 31 | value. If \VAR{cond} and the remote \VAR{dest} are equal, then \VAR{value} 32 | is swapped into the remote \VAR{dest}; otherwise, the remote \VAR{dest} is 33 | unchanged. 34 | The type of \VAR{cond} should match that implied in the SYNOPSIS section.} 35 | \apiargument{IN}{value}{The value to be atomically written to the remote 36 | \ac{PE}. 37 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 38 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 39 | with the given \VAR{ctx} when provided, or the default context otherwise.} 40 | \end{apiarguments} 41 | 42 | \apidescription{ 43 | The nonblocking conditional swap routines conditionally update a \VAR{dest} 44 | data object on the specified \ac{PE} as an atomic operation and fetches the prior contents of the 45 | \VAR{dest} data object into the \VAR{fetch} local data object. 46 | This routine returns after initiating the operation. The operation 47 | is considered complete after a subsequent call to \FUNC{shmem\_quiet}. At the 48 | completion of \FUNC{shmem\_quiet}, prior contents of the \VAR{dest} data 49 | object have been fetched into \VAR{fetch} local data object and the 50 | contents of \VAR{value} have been conditionally updated into \VAR{dest} on the 51 | remote \ac{PE}. 52 | } 53 | 54 | \apireturnvalues{ 55 | None. 56 | } 57 | 58 | \end{apidefinition} 59 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Atomically fetches the value of a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | TYPE @\FuncDecl{shmem\_atomic\_fetch}@(const TYPE *source, int pe); 9 | TYPE @\FuncDecl{shmem\_atomic\_fetch}@(shmem_ctx_t ctx, const TYPE *source, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the extended \ac{AMO} types specified by 12 | Table~\ref{extamotypes}. 13 | 14 | \begin{Csynopsis} 15 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch}@(const TYPE *source, int pe); 16 | TYPE @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch}@(shmem_ctx_t ctx, const TYPE *source, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the extended \ac{AMO} types and has a corresponding 19 | \TYPENAME{} specified by Table~\ref{extamotypes}. 20 | 21 | \begin{DeprecateBlock} 22 | \begin{C11synopsis} 23 | TYPE @\FuncDecl{shmem\_fetch}@(const TYPE *source, int pe); 24 | \end{C11synopsis} 25 | where \TYPE{} is one of \{\CTYPE{float}, \CTYPE{double}, \CTYPE{int}, 26 | \CTYPE{long}, \CTYPE{long long}\}. 27 | 28 | \begin{Csynopsis} 29 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_fetch}@(const TYPE *source, int pe); 30 | \end{Csynopsis} 31 | where \TYPE{} is one of \{\CTYPE{float}, \CTYPE{double}, \CTYPE{int}, 32 | \CTYPE{long}, \CTYPE{long long}\} and has a corresponding 33 | \TYPENAME{} specified by Table~\ref{extamotypes}. 34 | \end{DeprecateBlock} 35 | 36 | \begin{apiarguments} 37 | 38 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 39 | When this argument is not provided, the operation is performed on 40 | the default context.} 41 | \apiargument{IN}{source}{Symmetric address of the source data object. 42 | The type of \source{} should match that implied in the SYNOPSIS section.} 43 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} on which \VAR{source} resides 44 | relative to the team associated with the given \VAR{ctx} when provided, or the 45 | default context otherwise.} 46 | \end{apiarguments} 47 | 48 | \apidescription{ 49 | \FUNC{shmem\_atomic\_fetch} performs an atomic fetch operation. 50 | It returns the contents of the \VAR{source} as an atomic operation. 51 | } 52 | 53 | \apireturnvalues{ 54 | The contents at the \VAR{source} address on the remote \ac{PE}. 55 | The data type of the return value is the same as the type of 56 | the remote data object. 57 | } 58 | 59 | \end{apidefinition} 60 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_add.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Performs an atomic fetch-and-add operation on a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_add}@(TYPE *dest, TYPE value, int pe); 9 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_add}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the standard \ac{AMO} types specified by 12 | Table~\ref{stdamotypes}. 13 | 14 | \begin{Csynopsis} 15 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_add}@(TYPE *dest, TYPE value, int pe); 16 | TYPE @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_add}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the standard \ac{AMO} types and has a corresponding 19 | \TYPENAME{} specified by Table~\ref{stdamotypes}. 20 | 21 | \begin{DeprecateBlock} 22 | \begin{C11synopsis} 23 | TYPE @\FuncDecl{shmem\_fadd}@(TYPE *dest, TYPE value, int pe); 24 | \end{C11synopsis} 25 | where \TYPE{} is one of \{\CTYPE{int}, \CTYPE{long}, \CTYPE{long long}\}. 26 | 27 | \begin{Csynopsis} 28 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_fadd}@(TYPE *dest, TYPE value, int pe); 29 | \end{Csynopsis} 30 | where \TYPE{} is one of \{\CTYPE{int}, \CTYPE{long}, \CTYPE{long long}\} 31 | and has a corresponding \TYPENAME{} specified by Table~\ref{stdamotypes}. 32 | \end{DeprecateBlock} 33 | 34 | \begin{apiarguments} 35 | 36 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 37 | When this argument is not provided, the operation is performed on 38 | the default context.} 39 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 40 | The type of \VAR{dest} should match that implied in the 41 | SYNOPSIS section.} 42 | \apiargument{IN}{value}{The operand to the atomic fetch-and-add operation. The 43 | type of \VAR{value} should match that implied in the SYNOPSIS section.} 44 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 45 | with the given \VAR{ctx} when provided, or the default context otherwise.} 46 | \end{apiarguments} 47 | 48 | \apidescription{ 49 | \FUNC{shmem\_atomic\_fetch\_add} routines perform an atomic fetch-and-add operation. An 50 | atomic fetch-and-add operation fetches the old \VAR{dest} and adds \VAR{value} 51 | to \VAR{dest} without the possibility of another atomic operation on the 52 | \VAR{dest} between the time of the fetch and the update. These routines add 53 | \VAR{value} to \VAR{dest} on \VAR{pe} and return the previous contents of 54 | \VAR{dest} as an atomic operation. 55 | } 56 | 57 | \apireturnvalues{ 58 | The contents that had been at the \VAR{dest} address on the remote \ac{PE} 59 | prior to the atomic addition operation. The data type of the return value is 60 | the same as the \VAR{dest}. 61 | } 62 | 63 | \begin{apiexamples} 64 | 65 | \apicexample 66 | {The following \FUNC{shmem\_atomic\_fetch\_add} example is for 67 | \Cstd[11] programs:} 68 | {./example_code/shmem_atomic_fetch_add_example.c} 69 | {} 70 | 71 | \end{apiexamples} 72 | 73 | \end{apidefinition} 74 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_add_nbi.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | The nonblocking atomic routine performs an atomic fetch-and-add operation on 3 | a remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_fetch\_add\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 10 | void @\FuncDecl{shmem\_atomic\_fetch\_add\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the standard \ac{AMO} types specified by 13 | Table~\ref{stdamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_add\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_add\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the standard \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{stdamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to 25 | perform the operation. When this argument is not provided, the operation 26 | is performed on the default context.} 27 | \apiargument{OUT}{fetch}{Local address of data object to be updated. 28 | The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} 29 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 30 | The type of \dest{} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{value}{The operand to the atomic fetch-and-add operation. 32 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 33 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 34 | with the given \VAR{ctx} when provided, or the default context otherwise.} 35 | \end{apiarguments} 36 | 37 | \apidescription{ 38 | The nonblocking \FUNC{shmem\_atomic\_fetch\_add\_nbi} routines perform an 39 | atomic fetch-and-add operation. An atomic fetch-and-add operation fetches 40 | the old \VAR{dest} and adds \VAR{value} to \VAR{dest} without the 41 | possibility of another atomic operation on the \VAR{dest} between the time 42 | of the fetch and the update. This routine returns after initiating the 43 | operation. The operation is considered complete after a subsequent call to 44 | \FUNC{shmem\_quiet}. At the completion of \FUNC{shmem\_quiet}, \VAR{value} 45 | has been added to \VAR{dest} on \VAR{pe} and the prior contents of \VAR{dest} 46 | fetched into the \VAR{fetch} local data object. 47 | } 48 | 49 | \apireturnvalues{ 50 | None. 51 | } 52 | 53 | \end{apidefinition} 54 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_and.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Atomically perform a fetching bitwise AND operation on a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_and}@(TYPE *dest, TYPE value, int pe); 9 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_and}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the bitwise \ac{AMO} types specified by 12 | Table~\ref{bitamotypes}. 13 | 14 | \begin{Csynopsis} 15 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_and}@(TYPE *dest, TYPE value, int pe); 16 | TYPE @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_and}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the bitwise \ac{AMO} types and has a corresponding 19 | \TYPENAME{} specified by Table~\ref{bitamotypes}. 20 | 21 | \begin{apiarguments} 22 | 23 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 24 | When this argument is not provided, the operation is performed on 25 | the default context.} 26 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 27 | The type of \dest{} should match that implied in the SYNOPSIS section.} 28 | \apiargument{IN}{value}{The operand to the bitwise AND operation. 29 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 30 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 31 | with the given \VAR{ctx} when provided, or the default context otherwise.} 32 | \end{apiarguments} 33 | 34 | \apidescription{ 35 | \FUNC{shmem\_atomic\_fetch\_and} atomically performs a fetching bitwise AND 36 | on the remotely accessible data object pointed to by \VAR{dest} at PE 37 | \VAR{pe} with the operand \VAR{value}. 38 | } 39 | 40 | \apireturnvalues{ 41 | The value pointed to by \VAR{dest} on \ac{PE} \VAR{pe} immediately before the 42 | operation is performed. 43 | } 44 | 45 | \end{apidefinition} 46 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_and_nbi.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | This nonblocking atomic operation performs an atomic fetching bitwise AND 3 | operation on a remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_fetch\_and\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 10 | void @\FuncDecl{shmem\_atomic\_fetch\_and\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the bitwise \ac{AMO} types specified by 13 | Table~\ref{bitamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_and\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_and\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the bitwise \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{bitamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to 25 | perform the operation. When this argument is not provided, the 26 | operation is performed on the default context.} 27 | \apiargument{OUT}{fetch}{Local address of data object to be updated. 28 | The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} 29 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 30 | The type of \dest{} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{value}{The operand to the bitwise AND operation. 32 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 33 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 34 | with the given \VAR{ctx} when provided, or the default context otherwise.} 35 | \end{apiarguments} 36 | 37 | \apidescription{ 38 | The nonblocking \FUNC{shmem\_atomic\_fetch\_and\_nbi} routines perform an 39 | atomic fetching bitwise AND on the remotely accessible data object pointed 40 | by \VAR{dest} at \ac{PE} \VAR{pe} with the operand \VAR{value}. This routine 41 | returns after initiating the operation. The operation is considered complete 42 | after a subsequent call to \FUNC{shmem\_quiet}. At the completion of 43 | \FUNC{shmem\_quiet}, these routines have performed a fetching bitwise AND on 44 | \VAR{dest} at \ac{PE} \VAR{pe} with the operand \VAR{value} and fetched the prior 45 | contents of \VAR{dest} into the \VAR{fetch} local data object. 46 | } 47 | 48 | \apireturnvalues{ 49 | None. 50 | } 51 | 52 | \end{apidefinition} 53 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_inc.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Performs an atomic fetch-and-increment operation on a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_inc}@(TYPE *dest, int pe); 9 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_inc}@(shmem_ctx_t ctx, TYPE *dest, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the standard \ac{AMO} types specified by 12 | Table~\ref{stdamotypes}. 13 | 14 | \begin{Csynopsis} 15 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_inc}@(TYPE *dest, int pe); 16 | TYPE @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_inc}@(shmem_ctx_t ctx, TYPE *dest, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the standard \ac{AMO} types and has a corresponding 19 | \TYPENAME{} specified by Table~\ref{stdamotypes}. 20 | 21 | \begin{DeprecateBlock} 22 | \begin{C11synopsis} 23 | TYPE @\FuncDecl{shmem\_finc}@(TYPE *dest, int pe); 24 | \end{C11synopsis} 25 | where \TYPE{} is one of \{\CTYPE{int}, \CTYPE{long}, \CTYPE{long long}\}. 26 | 27 | \begin{Csynopsis} 28 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_finc}@(TYPE *dest, int pe); 29 | \end{Csynopsis} 30 | where \TYPE{} is one of \{\CTYPE{int}, \CTYPE{long}, \CTYPE{long long}\} 31 | and has a corresponding \TYPENAME{} specified by Table~\ref{stdamotypes}. 32 | \end{DeprecateBlock} 33 | 34 | \begin{apiarguments} 35 | 36 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 37 | When this argument is not provided, the operation is performed on 38 | the default context.} 39 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 40 | The type of \dest{} should match that implied in the SYNOPSIS section.} 41 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 42 | with the given \VAR{ctx} when provided, or the default context otherwise.} 43 | \end{apiarguments} 44 | 45 | 46 | \apidescription{ 47 | These routines perform a fetch-and-increment operation. The \dest{} on 48 | \ac{PE} \VAR{pe} is increased by one and the routine returns the previous 49 | contents of \dest{} as an atomic operation. 50 | } 51 | 52 | \apireturnvalues{ 53 | The contents that had been at the \dest{} address on the remote \ac{PE} prior to 54 | the increment. The data type of the return value is the same as the \dest. 55 | } 56 | 57 | \begin{apiexamples} 58 | 59 | \apicexample 60 | {The following \FUNC{shmem\_atomic\_fetch\_inc} example is for 61 | \Cstd[11] programs:} 62 | {./example_code/shmem_atomic_fetch_inc_example.c} 63 | {} 64 | 65 | \end{apiexamples} 66 | 67 | \end{apidefinition} 68 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_inc_nbi.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | This nonblocking atomic routine performs an atomic fetch-and-increment 3 | operation on a remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_fetch\_inc\_nbi}@(TYPE *fetch, TYPE *dest, int pe); 10 | void @\FuncDecl{shmem\_atomic\_fetch\_inc\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the standard \ac{AMO} types specified by 13 | Table~\ref{stdamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_inc\_nbi}@(TYPE *fetch, TYPE *dest, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_inc\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the standard \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{stdamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to 25 | perform the operation. When this argument is not provided, the 26 | operation is performed on the default context.} 27 | \apiargument{OUT}{fetch}{Local address of data object to be updated. 28 | The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} 29 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 30 | The type of \dest{} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 32 | with the given \VAR{ctx} when provided, or the default context otherwise.} 33 | \end{apiarguments} 34 | 35 | 36 | \apidescription{ 37 | The nonblocking \FUNC{shmem\_atomic\_fetch\_inc\_nbi} routines perform an 38 | atomic fetch-and-increment operation. This routine returns after initiating the 39 | operation. The operation is considered complete after a subsequent call to 40 | \FUNC{shmem\_quiet}. At the completion of \FUNC{shmem\_quiet}, \dest{} on 41 | \ac{PE} \VAR{pe} has been increased by one and the previous contents of \dest{} 42 | fetched into the \VAR{fetch} local data object. 43 | } 44 | 45 | \apireturnvalues{ 46 | None. 47 | } 48 | 49 | \end{apidefinition} 50 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_nbi.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | The nonblocking atomic fetch routine provides a method for atomically 3 | fetching the value of a remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_fetch\_nbi}@(TYPE *fetch, const TYPE *source, int pe); 10 | void @\FuncDecl{shmem\_atomic\_fetch\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, const TYPE *source, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the extended \ac{AMO} types specified by 13 | Table~\ref{extamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_nbi}@(TYPE *fetch, const TYPE *source, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, const TYPE *source, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the extended \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{extamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to 25 | perform the operation. When this argument is not provided, the operation is 26 | performed on the default context.} 27 | \apiargument{OUT}{fetch}{Local address of data object to be updated. 28 | The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} 29 | \apiargument{OUT}{source}{Symmetric address of the source data object. 30 | The type of \source{} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 32 | with the given \VAR{ctx} when provided, or the default context otherwise.} 33 | \end{apiarguments} 34 | 35 | \apidescription{ 36 | The nonblocking atomic fetch routines perform a nonblocking fetch of a 37 | value atomically from a remote data object. This routine returns after 38 | initiating the operation. The operation is considered complete after a 39 | subsequent call to \FUNC{shmem\_quiet}. At the completion of 40 | \FUNC{shmem\_quiet}, contents of the \source{} data object from \ac{PE} has been 41 | fetched into \VAR{fetch} local data object. 42 | } 43 | 44 | \apireturnvalues{ 45 | None. 46 | } 47 | 48 | \end{apidefinition} 49 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_or.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Atomically perform a fetching bitwise OR operation on a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_or}@(TYPE *dest, TYPE value, int pe); 9 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_or}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the bitwise \ac{AMO} types specified by 12 | Table~\ref{bitamotypes}. 13 | 14 | \begin{Csynopsis} 15 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_or}@(TYPE *dest, TYPE value, int pe); 16 | TYPE @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_or}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the bitwise \ac{AMO} types and has a corresponding 19 | \TYPENAME{} specified by Table~\ref{bitamotypes}. 20 | 21 | \begin{apiarguments} 22 | 23 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 24 | When this argument is not provided, the operation is performed on 25 | the default context.} 26 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 27 | The type of \dest{} should match that implied in the SYNOPSIS section.} 28 | \apiargument{IN}{value}{The operand to the bitwise OR operation. 29 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 30 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 31 | with the given \VAR{ctx} when provided, or the default context otherwise.} 32 | \end{apiarguments} 33 | 34 | \apidescription{ 35 | \FUNC{shmem\_atomic\_fetch\_or} atomically performs a fetching bitwise OR 36 | on the remotely accessible data object pointed to by \VAR{dest} at PE 37 | \VAR{pe} with the operand \VAR{value}. 38 | } 39 | 40 | \apireturnvalues{ 41 | The value pointed to by \VAR{dest} on \ac{PE} \VAR{pe} immediately before the 42 | operation is performed. 43 | } 44 | 45 | \end{apidefinition} 46 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_or_nbi.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | This nonblocking atomic operation performs an atomic fetching bitwise OR 3 | operation on a remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_fetch\_or\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 10 | void @\FuncDecl{shmem\_atomic\_fetch\_or\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the bitwise \ac{AMO} types specified by 13 | Table~\ref{bitamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_or\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_or\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the bitwise \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{bitamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to 25 | perform the operation. When this argument is not provided, the 26 | operation is performed on the default context.} 27 | \apiargument{OUT}{fetch}{Local address of data object to be updated. 28 | The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} 29 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 30 | The type of \dest{} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{value}{The operand to the bitwise OR operation. 32 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 33 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 34 | with the given \VAR{ctx} when provided, or the default context otherwise.} 35 | \end{apiarguments} 36 | 37 | \apidescription{ 38 | The nonblocking \FUNC{shmem\_atomic\_fetch\_or\_nbi} routines perform an 39 | atomic fetching bitwise OR on the remotely accessible data object pointed 40 | by \VAR{dest} at \ac{PE} \VAR{pe} with the operand \VAR{value}. This routine 41 | returns after initiating the operation. The operation is considered complete 42 | after a subsequent call to \FUNC{shmem\_quiet}. At the completion of 43 | \FUNC{shmem\_quiet}, these routines have performed a fetching bitwise OR on 44 | \VAR{dest} at \ac{PE} \VAR{pe} with the operand \VAR{value} and fetched the prior 45 | contents of \VAR{dest} into the \VAR{fetch} local data object. 46 | } 47 | 48 | \apireturnvalues{ 49 | None. 50 | } 51 | 52 | \end{apidefinition} 53 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_xor.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Atomically perform a fetching bitwise exclusive OR (XOR) operation on a 3 | remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_xor}@(TYPE *dest, TYPE value, int pe); 10 | TYPE @\FuncDecl{shmem\_atomic\_fetch\_xor}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the bitwise \ac{AMO} types specified by 13 | Table~\ref{bitamotypes}. 14 | 15 | \begin{Csynopsis} 16 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_xor}@(TYPE *dest, TYPE value, int pe); 17 | TYPE @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_xor}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the bitwise \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{bitamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 25 | When this argument is not provided, the operation is performed on 26 | the default context.} 27 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 28 | The type of \dest{} should match that implied in the SYNOPSIS section.} 29 | \apiargument{IN}{value}{The operand to the bitwise XOR operation. 30 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 32 | with the given \VAR{ctx} when provided, or the default context otherwise.} 33 | \end{apiarguments} 34 | 35 | \apidescription{ 36 | \FUNC{shmem\_atomic\_fetch\_xor} atomically performs a fetching bitwise XOR 37 | on the remotely accessible data object pointed to by \VAR{dest} at PE 38 | \VAR{pe} with the operand \VAR{value}. 39 | } 40 | 41 | \apireturnvalues{ 42 | The value pointed to by \VAR{dest} on \ac{PE} \VAR{pe} immediately before the 43 | operation is performed. 44 | } 45 | 46 | \end{apidefinition} 47 | -------------------------------------------------------------------------------- /content/shmem_atomic_fetch_xor_nbi.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | This nonblocking atomic operation performs an atomic fetching bitwise XOR 3 | operation on a remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_fetch\_xor\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 10 | void @\FuncDecl{shmem\_atomic\_fetch\_xor\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the bitwise \ac{AMO} types specified by 13 | Table~\ref{bitamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_fetch\_xor\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_fetch\_xor\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the bitwise \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{bitamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to 25 | perform the operation. When this argument is not provided, the 26 | operation is performed on the default context.} 27 | \apiargument{OUT}{fetch}{Local address of data object to be updated. 28 | The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} 29 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 30 | The type of \dest{} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{value}{The operand to the bitwise XOR operation. 32 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 33 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 34 | with the given \VAR{ctx} when provided, or the default context otherwise.} 35 | \end{apiarguments} 36 | 37 | \apidescription{ 38 | The nonblocking \FUNC{shmem\_atomic\_fetch\_xor\_nbi} routines perform an 39 | atomic fetching bitwise XOR on the remotely accessible data object pointed 40 | by \VAR{dest} at \ac{PE} \VAR{pe} with the operand \VAR{value}. This routine 41 | returns after initiating the operation. The operation is considered complete 42 | after a subsequent call to \FUNC{shmem\_quiet}. At the completion of 43 | \FUNC{shmem\_quiet}, these routines have performed a fetching bitwise XOR on 44 | \VAR{dest} at \ac{PE} \VAR{pe} with the operand \VAR{value} and fetched the prior 45 | contents of \VAR{dest} into the \VAR{fetch} local data object. 46 | } 47 | 48 | \apireturnvalues{ 49 | None. 50 | } 51 | 52 | \end{apidefinition} 53 | -------------------------------------------------------------------------------- /content/shmem_atomic_inc.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Performs an atomic increment operation on a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | void @\FuncDecl{shmem\_atomic\_inc}@(TYPE *dest, int pe); 9 | void @\FuncDecl{shmem\_atomic\_inc}@(shmem_ctx_t ctx, TYPE *dest, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the standard \ac{AMO} types specified by 12 | Table~\ref{stdamotypes}. 13 | 14 | \begin{Csynopsis} 15 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_inc}@(TYPE *dest, int pe); 16 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_inc}@(shmem_ctx_t ctx, TYPE *dest, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the standard \ac{AMO} types and has a corresponding 19 | \TYPENAME{} specified by Table~\ref{stdamotypes}. 20 | 21 | \begin{DeprecateBlock} 22 | \begin{C11synopsis} 23 | void @\FuncDecl{shmem\_inc}@(TYPE *dest, int pe); 24 | \end{C11synopsis} 25 | where \TYPE{} is one of \{\CTYPE{int}, \CTYPE{long}, \CTYPE{long long}\}. 26 | 27 | \begin{Csynopsis} 28 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_inc}@(TYPE *dest, int pe); 29 | \end{Csynopsis} 30 | where \TYPE{} is one of \{\CTYPE{int}, \CTYPE{long}, \CTYPE{long long}\} 31 | and has a corresponding \TYPENAME{} specified by Table~\ref{stdamotypes}. 32 | \end{DeprecateBlock} 33 | 34 | \begin{apiarguments} 35 | 36 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 37 | When this argument is not provided, the operation is performed on 38 | the default context.} 39 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 40 | The type of \dest{} should match that implied in the SYNOPSIS section.} 41 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 42 | with the given \VAR{ctx} when provided, or the default context otherwise.} 43 | \end{apiarguments} 44 | 45 | \apidescription{ 46 | These routines perform an atomic increment operation on the \VAR{dest} data 47 | object on \ac{PE}. 48 | } 49 | 50 | \apireturnvalues{ 51 | None. 52 | } 53 | 54 | \begin{apiexamples} 55 | 56 | \apicexample 57 | { The following \FUNC{shmem\_atomic\_inc} example is for 58 | \Cstd[11] programs: } 59 | {./example_code/shmem_atomic_inc_example.c} 60 | {} 61 | 62 | \end{apiexamples} 63 | 64 | \end{apidefinition} 65 | -------------------------------------------------------------------------------- /content/shmem_atomic_or.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Atomically perform a non-fetching bitwise OR operation on a 3 | remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_or}@(TYPE *dest, TYPE value, int pe); 10 | void @\FuncDecl{shmem\_atomic\_or}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the bitwise \ac{AMO} types specified by 13 | Table~\ref{bitamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_or}@(TYPE *dest, TYPE value, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_or}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the bitwise \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{bitamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 25 | When this argument is not provided, the operation is performed on 26 | the default context.} 27 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 28 | The type of \dest{} should match that implied in the SYNOPSIS section.} 29 | \apiargument{IN}{value}{The operand to the bitwise OR operation. 30 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 32 | with the given \VAR{ctx} when provided, or the default context otherwise.} 33 | \end{apiarguments} 34 | 35 | \apidescription{ 36 | \FUNC{shmem\_atomic\_or} atomically performs a non-fetching bitwise OR 37 | on the remotely accessible data object pointed to by \VAR{dest} at PE 38 | \VAR{pe} with the operand \VAR{value}. 39 | } 40 | 41 | \apireturnvalues{ 42 | None. 43 | } 44 | 45 | \end{apidefinition} 46 | -------------------------------------------------------------------------------- /content/shmem_atomic_set.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Atomically sets the value of a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | void @\FuncDecl{shmem\_atomic\_set}@(TYPE *dest, TYPE value, int pe); 9 | void @\FuncDecl{shmem\_atomic\_set}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the extended \ac{AMO} types specified by 12 | Table~\ref{extamotypes}. 13 | 14 | \begin{Csynopsis} 15 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_set}@(TYPE *dest, TYPE value, int pe); 16 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_set}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the extended \ac{AMO} types and has a corresponding 19 | \TYPENAME{} specified by Table~\ref{extamotypes}. 20 | 21 | \begin{DeprecateBlock} 22 | \begin{C11synopsis} 23 | void @\FuncDecl{shmem\_set}@(TYPE *dest, TYPE value, int pe); 24 | \end{C11synopsis} 25 | where \TYPE{} is one of \{\CTYPE{float}, \CTYPE{double}, \CTYPE{int}, 26 | \CTYPE{long}, \CTYPE{long long}\}. 27 | 28 | \begin{Csynopsis} 29 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_set}@(TYPE *dest, TYPE value, int pe); 30 | \end{Csynopsis} 31 | where \TYPE{} is one of \{\CTYPE{float}, \CTYPE{double}, \CTYPE{int}, 32 | \CTYPE{long}, \CTYPE{long long}\} and has a corresponding 33 | \TYPENAME{} specified by Table~\ref{extamotypes}. 34 | \end{DeprecateBlock} 35 | 36 | \begin{apiarguments} 37 | 38 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 39 | When this argument is not provided, the operation is performed on 40 | the default context.} 41 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 42 | The type of \dest{} should match that implied in the SYNOPSIS section.} 43 | \apiargument{IN}{value}{The operand to the atomic set operation. 44 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 45 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 46 | with the given \VAR{ctx} when provided, or the default context otherwise.} 47 | \end{apiarguments} 48 | 49 | \apidescription{ 50 | \FUNC{shmem\_atomic\_set} performs an atomic set operation. It writes the 51 | \VAR{value} into \VAR{dest} on \VAR{pe} as an atomic operation. 52 | } 53 | 54 | \apireturnvalues{ 55 | None. 56 | } 57 | 58 | \end{apidefinition} 59 | -------------------------------------------------------------------------------- /content/shmem_atomic_swap.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Performs an atomic swap to a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | TYPE @\FuncDecl{shmem\_atomic\_swap}@(TYPE *dest, TYPE value, int pe); 9 | TYPE @\FuncDecl{shmem\_atomic\_swap}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the extended \ac{AMO} types specified by Table \ref{extamotypes}. 12 | 13 | \begin{Csynopsis} 14 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_swap}@(TYPE *dest, TYPE value, int pe); 15 | TYPE @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_swap}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 16 | \end{Csynopsis} 17 | where \TYPE{} is one of the extended \ac{AMO} types and has a corresponding \TYPENAME{} specified by Table \ref{extamotypes}. 18 | 19 | \begin{DeprecateBlock} 20 | \begin{C11synopsis} 21 | TYPE @\FuncDecl{shmem\_swap}@(TYPE *dest, TYPE value, int pe); 22 | \end{C11synopsis} 23 | where \TYPE{} is one of \{\CTYPE{float}, \CTYPE{double}, \CTYPE{int}, 24 | \CTYPE{long}, \CTYPE{long long}\}. 25 | 26 | \begin{Csynopsis} 27 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_swap}@(TYPE *dest, TYPE value, int pe); 28 | \end{Csynopsis} 29 | where \TYPE{} is one of \{\CTYPE{float}, \CTYPE{double}, \CTYPE{int}, 30 | \CTYPE{long}, \CTYPE{long long}\} and has a corresponding 31 | \TYPENAME{} specified by Table~\ref{extamotypes}. 32 | \end{DeprecateBlock} 33 | 34 | \begin{apiarguments} 35 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 36 | When this argument is not provided, the operation is performed on 37 | the default context.} 38 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 39 | The type of \dest{} should match that implied in the SYNOPSIS section.} 40 | \apiargument{IN}{value}{The value to be atomically written to the remote \ac{PE}. 41 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 42 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 43 | with the given \VAR{ctx} when provided, or the default context otherwise.} 44 | \end{apiarguments} 45 | 46 | \apidescription{ 47 | \FUNC{shmem\_atomic\_swap} performs an atomic swap operation. 48 | It writes \VAR{value} into \dest{} on \ac{PE} and returns the previous 49 | contents of \dest{} as an atomic operation. 50 | } 51 | 52 | \apireturnvalues{ 53 | The content that had been at the \dest{} address on the remote \ac{PE} 54 | prior to the swap is returned. 55 | } 56 | 57 | \begin{apiexamples} 58 | 59 | \apicexample 60 | {The example below swaps values between odd numbered \acp{PE} and 61 | their right (modulo) neighbor and outputs the result of swap.} 62 | {./example_code/shmem_atomic_swap_example.c} 63 | {} 64 | 65 | \end{apiexamples} 66 | 67 | \end{apidefinition} 68 | -------------------------------------------------------------------------------- /content/shmem_atomic_swap_nbi.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | This nonblocking atomic operation performs an atomic swap to a remote data 3 | object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_swap\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 10 | void @\FuncDecl{shmem\_atomic\_swap\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the extended \ac{AMO} types specified by 13 | Table~\ref{extamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_swap\_nbi}@(TYPE *fetch, TYPE *dest, TYPE value, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_swap\_nbi}@(shmem_ctx_t ctx, TYPE *fetch, TYPE *dest, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the extended \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{extamotypes}. 21 | 22 | \begin{apiarguments} 23 | \apiargument{IN}{ctx}{A context handle specifying the context on which to 24 | perform the operation. When this argument is not provided, the 25 | operation is performed on the default context.} 26 | \apiargument{OUT}{fetch}{Local address of data object to be updated. 27 | The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} 28 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 29 | The type of \dest{} should match that implied in the SYNOPSIS section.} 30 | \apiargument{IN}{value}{The value to be atomically written to the remote 31 | \ac{PE}. 32 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 33 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 34 | with the given \VAR{ctx} when provided, or the default context otherwise.} 35 | \end{apiarguments} 36 | 37 | \apidescription{ 38 | The nonblocking \FUNC{shmem\_atomic\_swap\_nbi} routines perform an atomic 39 | swap operation. This routine returns after initiating the operation. The 40 | operation is considered complete after a subsequent call to 41 | \FUNC{shmem\_quiet}. At the completion of \FUNC{shmem\_quiet}, it has written 42 | \VAR{value} into \dest{} on \ac{PE} and fetched the prior contents of 43 | \dest{} into \VAR{fetch} local data object. 44 | } 45 | 46 | \apireturnvalues{ 47 | None. 48 | } 49 | 50 | \end{apidefinition} 51 | -------------------------------------------------------------------------------- /content/shmem_atomic_xor.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Atomically perform a non-fetching bitwise exclusive OR (XOR) operation on a 3 | remote data object. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_atomic\_xor}@(TYPE *dest, TYPE value, int pe); 10 | void @\FuncDecl{shmem\_atomic\_xor}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the bitwise \ac{AMO} types specified by 13 | Table~\ref{bitamotypes}. 14 | 15 | \begin{Csynopsis} 16 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_atomic\_xor}@(TYPE *dest, TYPE value, int pe); 17 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_atomic\_xor}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the bitwise \ac{AMO} types and has a corresponding 20 | \TYPENAME{} specified by Table~\ref{bitamotypes}. 21 | 22 | \begin{apiarguments} 23 | 24 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 25 | When this argument is not provided, the operation is performed on 26 | the default context.} 27 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 28 | The type of \dest{} should match that implied in the SYNOPSIS section.} 29 | \apiargument{IN}{value}{The operand to the bitwise XOR operation. 30 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 32 | with the given \VAR{ctx} when provided, or the default context otherwise.} 33 | \end{apiarguments} 34 | 35 | \apidescription{ 36 | \FUNC{shmem\_atomic\_xor} atomically performs a non-fetching bitwise XOR 37 | on the remotely accessible data object pointed to by \VAR{dest} at PE 38 | \VAR{pe} with the operand \VAR{value}. 39 | } 40 | 41 | \apireturnvalues{ 42 | None. 43 | } 44 | 45 | \end{apidefinition} 46 | -------------------------------------------------------------------------------- /content/shmem_barrier_all.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Registers the arrival of a \ac{PE} at a barrier and blocks the \ac{PE} 3 | until all other \acp{PE} arrive at the barrier and all local 4 | updates and remote memory updates on the default context are completed. 5 | } 6 | 7 | \begin{apidefinition} 8 | 9 | \begin{Csynopsis} 10 | void @\FuncDecl{shmem\_barrier\_all}@(void); 11 | \end{Csynopsis} 12 | 13 | \begin{apiarguments} 14 | 15 | \apiargument{None.}{}{} 16 | 17 | \end{apiarguments} 18 | 19 | \apidescription{ 20 | The \FUNC{shmem\_barrier\_all} routine 21 | is a mechanism for synchronizing all \acp{PE} in the world team at 22 | once. This routine blocks the calling \ac{PE} until all \acp{PE} have called 23 | \FUNC{shmem\_barrier\_all}. In a multithreaded \openshmem 24 | program, only the calling thread is blocked, however, 25 | it may not be called concurrently by multiple threads in the same \ac{PE}. 26 | 27 | Prior to synchronizing with other \acp{PE}, \FUNC{shmem\_barrier\_all} 28 | ensures completion of all previously issued memory stores and remote memory 29 | updates issued on the default context via \openshmem \acp{AMO} and 30 | \ac{RMA} routine calls such 31 | as \FUNC{shmem\_int\_add}, \FUNC{shmem\_put32}, 32 | \FUNC{shmem\_put\_nbi}, and \FUNC{shmem\_get\_nbi}. 33 | } 34 | 35 | \apireturnvalues{ 36 | None. 37 | } 38 | 39 | \apinotes{ 40 | The \FUNC{shmem\_barrier\_all} routine is equivalent to calling 41 | \FUNC{shmem\_ctx\_quiet} on the default context followed by 42 | calling \FUNC{shmem\_team\_sync} on the world team. 43 | 44 | The \FUNC{shmem\_barrier\_all} routine can be used to 45 | portably ensure that memory access operations observe remote updates in the order 46 | enforced by initiator \acp{PE}. 47 | 48 | Calls to \FUNC{shmem\_ctx\_quiet} can be performed prior 49 | to calling the barrier routine to ensure completion of operations issued on 50 | additional contexts. 51 | } 52 | 53 | \begin{apiexamples} 54 | 55 | \apicexample 56 | { The following \FUNC{shmem\_barrier\_all} example is for \Cstd[11] programs:} 57 | {./example_code/shmem_barrierall_example.c} 58 | {} 59 | 60 | \end{apiexamples} 61 | 62 | \end{apidefinition} 63 | -------------------------------------------------------------------------------- /content/shmem_calloc.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Collectively allocate a zeroed block of symmetric memory. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void *@\FuncDecl{shmem\_calloc}@(size_t count, size_t size); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{count}{The number of elements to allocate.} 13 | \apiargument{IN}{size}{The size in bytes of each element to allocate.} 14 | \end{apiarguments} 15 | 16 | 17 | \apidescription{ 18 | The \FUNC{shmem\_calloc} routine is a collective operation 19 | on the world team that allocates a 20 | region of remotely-accessible 21 | memory for an array of \VAR{count} objects of \VAR{size} bytes each and 22 | returns a pointer to the lowest byte address of the allocated symmetric 23 | memory. The space is initialized to all bits zero. 24 | 25 | If the allocation succeeds, the pointer returned shall be suitably 26 | aligned so that it may be assigned to a pointer to any type of object. 27 | If the allocation does not succeed, or either \VAR{count} or \VAR{size} is 28 | \CONST{0}, the return value is a null pointer. 29 | 30 | The values for \VAR{count} and \VAR{size} shall each be equal across 31 | all \acp{PE} calling \FUNC{shmem\_calloc}; otherwise, the behavior is 32 | undefined. 33 | 34 | When \VAR{count} or \VAR{size} is \CONST{0}, the \FUNC{shmem\_calloc} routine 35 | returns without performing a barrier. Otherwise, this 36 | routine calls a procedure that is semantically equivalent to 37 | \FUNC{shmem\_barrier\_all} on exit. 38 | } 39 | 40 | \apireturnvalues{ 41 | The \FUNC{shmem\_calloc} routine returns a pointer to the lowest byte 42 | address of the allocated space; otherwise, it returns a null pointer. 43 | } 44 | 45 | \end{apidefinition} 46 | -------------------------------------------------------------------------------- /content/shmem_ctx_create.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Create a communication context. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | int @\FuncDecl{shmem\_ctx\_create}@(long options, shmem_ctx_t *ctx); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{options}{The set of options requested for the given context. 13 | Multiple options may be requested by combining them with a bitwise 14 | OR operation; otherwise, \CONST{0} can be given if no options are 15 | requested.} 16 | \apiargument{OUT}{ctx}{A handle to the newly created context.} 17 | \end{apiarguments} 18 | 19 | \apidescription{ 20 | The \FUNC{shmem\_ctx\_create} routine creates a new communication context 21 | and returns its handle through the \VAR{ctx} argument. 22 | This context is created from the world team; 23 | however, the context creation operation is not collective. 24 | If the context was 25 | created successfully, a value of zero is returned 26 | and the context handle pointed to by \VAR{ctx} specifies a valid context; 27 | otherwise, a nonzero value is returned and \VAR{ctx} is set to 28 | \LibConstRef{SHMEM\_CTX\_INVALID}. 29 | An unsuccessful context 30 | creation call is not treated as an error and the \openshmem library remains 31 | in a correct state. The creation call can be reattempted with different 32 | options or after additional resources become available. 33 | 34 | All \openshmem routines that operate on this context will do so with 35 | respect to the associated \ac{PE} team. 36 | That is, all point-to-point routines operating on this context will use 37 | team-relative \ac{PE} numbering. 38 | } 39 | 40 | \apireturnvalues{ 41 | Zero on success and nonzero otherwise. 42 | } 43 | 44 | \end{apidefinition} 45 | 46 | -------------------------------------------------------------------------------- /content/shmem_ctx_destroy.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Destroy a communication context. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void @\FuncDecl{shmem\_ctx\_destroy}@(shmem_ctx_t ctx); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{ctx}{Handle to the context that will be destroyed.} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | \FUNC{shmem\_ctx\_destroy} destroys a context that was created by a call to 17 | \FUNC{shmem\_ctx\_create} or \FUNC{shmem\_team\_create\_ctx}. 18 | It is the user's responsibility to ensure that 19 | the context is not used after it has been destroyed, for example when the 20 | destroyed context is used by multiple threads. This function 21 | performs an implicit quiet operation on the given context before it is freed. 22 | If \VAR{ctx} has the value \CONST{SHMEM\_CTX\_INVALID}, no operation is 23 | performed. 24 | } 25 | 26 | \apireturnvalues{ 27 | None. 28 | } 29 | 30 | \apinotes{ 31 | Destroying a context makes it impossible for the user to complete 32 | communication operations that are pending on that context. This includes 33 | nonblocking communication operations, whose local buffers are only returned 34 | to the user after the operations have been completed. An implicit quiet is 35 | performed when freeing a context to avoid this ambiguity. 36 | 37 | A context with the \CONST{SHMEM\_CTX\_PRIVATE} option enabled must be 38 | destroyed by the thread that created it. 39 | } 40 | 41 | \begin{apiexamples} 42 | 43 | \apicexample 44 | {The following example demonstrates the use of contexts in a multithreaded 45 | \Cstd[11] program that uses OpenMP for threading. This example shows the 46 | shared counter load balancing method and illustrates the use of contexts 47 | for thread isolation.} 48 | {./example_code/shmem_ctx.c} 49 | {} 50 | 51 | \apicexample 52 | {The following example demonstrates the use of contexts in a 53 | single-threaded \Cstd[11] program that performs a summation reduction where 54 | the data contained in the \VAR{in\_buf} arrays on all \acp{PE} is reduced into 55 | the \VAR{out\_buf} arrays on all \acp{PE}. The buffers are divided into 56 | segments and processing of the segments is pipelined. Contexts are used 57 | to overlap an all-to-all exchange of data for segment \VAR{p} with the 58 | local reduction of segment \VAR{p-1}.} 59 | {./example_code/shmem_ctx_pipelined_reduce.c} 60 | {} 61 | 62 | \apicexample 63 | {The following example demonstrates the use of \CONST{SHMEM\_CTX\_INVALID} 64 | in a \Cstd[11] program that uses thread-local storage to provide each 65 | thread an implicit context handle via a ``library'' put routine without 66 | explicit management of the context handle from ``user'' code.} 67 | {./example_code/shmem_ctx_invalid.c} 68 | {} 69 | 70 | \end{apiexamples} 71 | 72 | \end{apidefinition} 73 | 74 | -------------------------------------------------------------------------------- /content/shmem_ctx_get_team.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Retrieve the team associated with the communication context. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | int @\FuncDecl{shmem\_ctx\_get\_team}@(shmem_ctx_t ctx, shmem_team_t *team); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{ctx}{ 13 | A handle to a communication context. 14 | } 15 | \apiargument{OUT}{team}{ 16 | A pointer to a handle to the associated \ac{PE} team. 17 | } 18 | \end{apiarguments} 19 | 20 | \apidescription{ 21 | The \FUNC{shmem\_ctx\_get\_team} routine returns a handle to the 22 | team associated with the specified communication context \VAR{ctx}. 23 | The team handle is returned through the pointer argument \VAR{team}. 24 | 25 | If \VAR{ctx} is the default context or one created by a call to 26 | \FUNC{shmem\_ctx\_create}, \VAR{team} is assigned the handle value 27 | \LibHandleRef{SHMEM\_TEAM\_WORLD}. 28 | 29 | If \VAR{ctx} compares equal to \LibConstRef{SHMEM\_CTX\_INVALID}, 30 | then \VAR{team} is assigned the value 31 | \LibConstRef{SHMEM\_TEAM\_INVALID} and a nonzero value is returned. 32 | If \VAR{ctx} is otherwise invalid, the behavior is undefined. 33 | 34 | If \VAR{team} is a null pointer, the behavior is undefined. 35 | } 36 | 37 | \apireturnvalues{ 38 | Zero on success; otherwise, nonzero. 39 | } 40 | 41 | \end{apidefinition} 42 | -------------------------------------------------------------------------------- /content/shmem_ctx_session_stop.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Stop a communication session. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void @\FuncDecl{shmem\_ctx\_session\_stop}@(shmem_ctx_t ctx); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{ctx}{A context handle specifying the context associated 13 | with this session.} 14 | \end{apiarguments} 15 | 16 | \apidescription{ 17 | The \FUNC{shmem\_ctx\_session\_stop} routine ends a session on context \VAR{ctx}. 18 | If a session is already stopped on a given communication context, another 19 | call to \FUNC{shmem\_ctx\_session\_stop} on that context has no effect. 20 | } 21 | 22 | \apireturnvalues{ 23 | None. 24 | } 25 | 26 | \apinotes{ 27 | Users are discouraged from including non-\openshmem code, such as a long 28 | computation loop, within a session without first calling 29 | \FUNC{shmem\_ctx\_session\_stop}. 30 | } 31 | 32 | 33 | \begin{apiexamples} 34 | 35 | \apicexample 36 | {The following \CorCpp{} program demonstrates the usage of 37 | \FUNC{shmem\_ctx\_session\_start} and \FUNC{shmem\_ctx\_session\_stop} with a loop of 38 | random atomic non-fetching XOR updates to a distributed table, similar to 39 | the HPC Challenge RandomAccess GUPS (Giga-updates per second) benchmark 40 | \footnote{http://icl.cs.utk.edu/projectsfiles/hpcc/RandomAccess/}.} 41 | {./example_code/shmem_ctx_session_example.c} 42 | {} 43 | \end{apiexamples} 44 | 45 | \end{apidefinition} 46 | 47 | -------------------------------------------------------------------------------- /content/shmem_free.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Collectively deallocate symmetric memory. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void @\FuncDecl{shmem\_free}@(void *ptr); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{ptr}{Symmetric address of an object in the symmetric heap.} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | The \FUNC{shmem\_free} routine is a collective operation on the 17 | world team that causes the block to which \VAR{ptr} 18 | points to be deallocated, that is, made available for further 19 | allocation. If \VAR{ptr} is a null pointer, no action is performed; 20 | otherwise, \FUNC{shmem\_free} calls a barrier on entry. 21 | It is the user's responsibility to ensure that no communication 22 | operations involving the given memory block are pending on other 23 | communication contexts prior to calling \FUNC{shmem\_free}. 24 | 25 | The value of the \VAR{ptr} argument must be identical on all 26 | \acp{PE}; otherwise, the behavior is undefined. 27 | } 28 | 29 | \apireturnvalues{ 30 | None. 31 | } 32 | 33 | \end{apidefinition} 34 | -------------------------------------------------------------------------------- /content/shmem_g.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Copies one data item from a remote \ac{PE} 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | TYPE @\FuncDecl{shmem\_g}@(const TYPE *source, int pe); 9 | TYPE @\FuncDecl{shmem\_g}@(shmem_ctx_t ctx, const TYPE *source, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}. 12 | 13 | \begin{Csynopsis} 14 | TYPE @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_g}@(const TYPE *source, int pe); 15 | TYPE @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_g}@(shmem_ctx_t ctx, const TYPE *source, int pe); 16 | \end{Csynopsis} 17 | where \TYPE{} is one of the standard \ac{RMA} types and has a corresponding \TYPENAME{} specified by Table \ref{stdrmatypes}. 18 | 19 | \begin{apiarguments} 20 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 21 | When this argument is not provided, the operation is performed on 22 | the default context.} 23 | \apiargument{IN}{source}{Symmetric address of the source data object. 24 | The type of \source{} should match that implied in the SYNOPSIS section.} 25 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} on which \VAR{source} resides 26 | relative to the team associated with the given \VAR{ctx} when provided, or the 27 | default context otherwise.} 28 | \end{apiarguments} 29 | 30 | \apidescription{ 31 | These routines provide a very low latency get capability for single elements 32 | of most basic types. 33 | } 34 | 35 | \apireturnvalues{ 36 | Returns a single element of type specified in the synopsis. 37 | } 38 | 39 | \begin{apiexamples} 40 | 41 | \apicexample 42 | {The following \FUNC{shmem\_g} example is for \Cstd[11] programs:} 43 | {./example_code/shmem_g_example.c} 44 | {} 45 | \end{apiexamples} 46 | 47 | \end{apidefinition} 48 | -------------------------------------------------------------------------------- /content/shmem_get.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Copies data from a specified \ac{PE}. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | void @\FuncDecl{shmem\_get}@(TYPE *dest, const TYPE *source, size_t nelems, int pe); 9 | void @\FuncDecl{shmem\_get}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}. 12 | 13 | \begin{Csynopsis} 14 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_get}@(TYPE *dest, const TYPE *source, size_t nelems, int pe); 15 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_get}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, int pe); 16 | \end{Csynopsis} 17 | where \TYPE{} is one of the standard \ac{RMA} types and has a corresponding \TYPENAME{} specified by Table \ref{stdrmatypes}. 18 | 19 | \begin{CsynopsisCol} 20 | void @\FuncDecl{shmem\_get\FuncParam{SIZE}}@(void *dest, const void *source, size_t nelems, int pe); 21 | void @\FuncDecl{shmem\_ctx\_get\FuncParam{SIZE}}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, int pe); 22 | \end{CsynopsisCol} 23 | where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}. 24 | 25 | \begin{CsynopsisCol} 26 | void @\FuncDecl{shmem\_getmem}@(void *dest, const void *source, size_t nelems, int pe); 27 | void @\FuncDecl{shmem\_ctx\_getmem}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, int pe); 28 | \end{CsynopsisCol} 29 | 30 | \begin{apiarguments} 31 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 32 | When this argument is not provided, the operation is performed on 33 | the default context.} 34 | \apiargument{OUT}{dest}{Local address of the data object to be updated. 35 | The type of \dest{} should match that implied in the SYNOPSIS section.} 36 | \apiargument{IN}{source}{Symmetric address of the source data object. 37 | The type of \source{} should match that implied in the SYNOPSIS section.} 38 | \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} arrays. 39 | For \FUNC{shmem\_getmem} and \FUNC{shmem\_ctx\_getmem}, elements are bytes.} 40 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 41 | with the given \VAR{ctx} when provided, or the default context otherwise.} 42 | \end{apiarguments} 43 | 44 | \apidescription{ 45 | The get routines provide a method for copying a contiguous symmetric data 46 | object from a remote \ac{PE} to a contiguous data object on the local 47 | \ac{PE}. The routines return after the data has been delivered to the 48 | \dest{} array on the local \ac{PE}. 49 | } 50 | 51 | \apireturnvalues{ 52 | None. 53 | } 54 | 55 | \apinotes{ 56 | See Section \ref{subsec:memory_model} for a definition of the term 57 | remotely accessible. 58 | } 59 | 60 | \end{apidefinition} 61 | -------------------------------------------------------------------------------- /content/shmem_global_exit.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | A routine that allows any \ac{PE} to force termination of an entire program. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | _Noreturn void @\FuncDecl{shmem\_global\_exit}@(int status); 9 | \end{C11synopsis} 10 | 11 | \begin{Csynopsis} 12 | void @\FuncDecl{shmem\_global\_exit}@(int status); 13 | \end{Csynopsis} 14 | 15 | \begin{apiarguments} 16 | \apiargument{IN}{status}{The exit status from the main program.} 17 | \end{apiarguments} 18 | 19 | \apidescription{ 20 | \FUNC{shmem\_global\_exit} is a non-collective routine that allows any one 21 | \ac{PE} to force termination of an \openshmem program for all \acp{PE}, 22 | passing an exit status to the execution environment. This routine terminates 23 | the entire program, not just the \openshmem portion. When any \ac{PE} calls 24 | \FUNC{shmem\_global\_exit}, it results in the immediate notification to all 25 | \acp{PE} to terminate. \FUNC{shmem\_global\_exit} flushes I/O and releases 26 | resources in accordance with \CorCpp language requirements for normal 27 | program termination. If more than one \ac{PE} calls 28 | \FUNC{shmem\_global\_exit}, then the exit status returned to the environment 29 | shall be one of the values passed to \FUNC{shmem\_global\_exit} as the 30 | status argument. There is no return to the caller of 31 | \FUNC{shmem\_global\_exit}; control is returned from the \openshmem program 32 | to the execution environment for all \acp{PE}. 33 | } 34 | 35 | \apireturnvalues{ 36 | None. 37 | } 38 | 39 | 40 | \apinotes{ 41 | \FUNC{shmem\_global\_exit} may be used in situations where one or more 42 | \acp{PE} have determined that the program has completed and/or should 43 | terminate early. Accordingly, the integer status argument can be used to 44 | pass any information about the nature of the exit; e.g., that the program 45 | encountered an error or found a solution. 46 | Since \FUNC{shmem\_global\_exit} is a non-collective 47 | routine, there is no implied synchronization, and all \acp{PE} must 48 | terminate regardless of their current execution state. While I/O must be 49 | flushed for standard language I/O calls from \CorCpp, it is 50 | implementation dependent as to how I/O done by other means (e.g., third 51 | party I/O libraries) are handled. Similarly, resources are released 52 | according to \CorCpp standard language requirements, but this may not 53 | include all resources allocated for the \openshmem program. However, a 54 | quality implementation will make a best effort to flush all I/O and clean 55 | up all resources. 56 | } 57 | 58 | \begin{apiexamples} 59 | 60 | \apicexample 61 | {} 62 | {./example_code/shmem_global_exit_example.c} 63 | {} 64 | 65 | \end{apiexamples} 66 | 67 | \end{apidefinition} 68 | -------------------------------------------------------------------------------- /content/shmem_iget.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Copies strided data from a specified \ac{PE}. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | void @\FuncDecl{shmem\_iget}@(TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t nelems, int pe); 9 | void @\FuncDecl{shmem\_iget}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t nelems, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}. 12 | 13 | \begin{Csynopsis} 14 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_iget}@(TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t nelems, int pe); 15 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_iget}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t nelems, int pe); 16 | \end{Csynopsis} 17 | where \TYPE{} is one of the standard \ac{RMA} types and has a corresponding \TYPENAME{} specified by Table \ref{stdrmatypes}. 18 | 19 | \begin{CsynopsisCol} 20 | void @\FuncDecl{shmem\_iget\FuncParam{SIZE}}@(void *dest, const void *source, ptrdiff_t dst, ptrdiff_t sst, size_t nelems, int pe); 21 | void @\FuncDecl{shmem\_ctx\_iget\FuncParam{SIZE}}@(shmem_ctx_t ctx, void *dest, const void *source, ptrdiff_t dst, ptrdiff_t sst, size_t nelems, int pe); 22 | \end{CsynopsisCol} 23 | where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}. 24 | 25 | \begin{apiarguments} 26 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 27 | When this argument is not provided, the operation is performed on 28 | the default context.} 29 | \apiargument{OUT}{dest}{Local address of the array to be updated. 30 | The type of \dest{} should match that implied in the SYNOPSIS section.} 31 | \apiargument{IN}{source}{Symmetric address of the source array data object. 32 | The type of \source{} should match that implied in the SYNOPSIS section.} 33 | \apiargument{IN}{dst}{The stride between consecutive elements of the \dest{} 34 | array. The stride must be greater than or equal to \CONST{1} and is 35 | scaled by the element size of the \dest{} array. A value of \CONST{1} 36 | indicates contiguous data.} 37 | \apiargument{IN}{sst}{The stride between consecutive elements of the \source{} 38 | array. The stride must be greater than or equal to \CONST{1} and is 39 | scaled by the element size of the \source{} array. A value of \CONST{1} 40 | indicates contiguous data.} 41 | \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} 42 | arrays.} 43 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 44 | with the given \VAR{ctx} when provided, or the default context otherwise.} 45 | \end{apiarguments} 46 | 47 | \apidescription{ 48 | The \FUNC{shmem\_iget} routines provide a method for copying strided data elements from 49 | a symmetric array from a specified remote \ac{PE} to strided locations on a 50 | local array. The routines return when the data has been copied into the local 51 | \VAR{dest} array. 52 | } 53 | 54 | \apireturnvalues{ 55 | None. 56 | } 57 | 58 | \end{apidefinition} 59 | -------------------------------------------------------------------------------- /content/shmem_info_get_name.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | This routine returns the vendor defined name string that is consistent 3 | with the library constant \CONST{SHMEM\_VENDOR\_STRING}. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{Csynopsis} 9 | void @\FuncDecl{shmem\_info\_get\_name}@(char *name); 10 | \end{Csynopsis} 11 | 12 | \begin{apiarguments} 13 | \apiargument{OUT}{name}{The vendor defined string.} 14 | \end{apiarguments} 15 | 16 | \apidescription{ 17 | This routine returns the vendor defined name string of size defined by 18 | the library constant \CONST{SHMEM\_MAX\_NAME\_LEN}. The program calling 19 | this function provides the \VAR{name} memory buffer of at least size 20 | \CONST{SHMEM\_MAX\_NAME\_LEN}. The implementation copies the vendor defined 21 | string of size at most \CONST{SHMEM\_MAX\_NAME\_LEN} to \VAR{name}. In 22 | \CorCpp, the string is terminated by a null character. If the 23 | \VAR{name} memory buffer is provided with size less than 24 | \CONST{SHMEM\_MAX\_NAME\_LEN}, behavior is undefined. For a given library 25 | implementation, the vendor string returned is consistent with the library 26 | constant \CONST{SHMEM\_VENDOR\_STRING}. 27 | } 28 | 29 | \apireturnvalues{ 30 | None. 31 | } 32 | 33 | \end{apidefinition} 34 | -------------------------------------------------------------------------------- /content/shmem_info_get_version.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Returns the major and minor version of the library implementation. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void @\FuncDecl{shmem\_info\_get\_version}@(int *major, int *minor); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{OUT}{major}{The major version of the \openshmem Specification in use.} 13 | \apiargument{OUT}{minor}{The minor version of the \openshmem Specification in use.} 14 | \end{apiarguments} 15 | 16 | \apidescription{ 17 | This routine returns the major and minor version of the \openshmem Specification 18 | in use. For a given library implementation, the major and minor version 19 | returned by these calls are consistent with the library constants 20 | \CONST{SHMEM\_MAJOR\_VERSION} and \CONST{SHMEM\_MINOR\_VERSION}. 21 | } 22 | 23 | \apireturnvalues{ 24 | None. 25 | } 26 | 27 | \end{apidefinition} 28 | -------------------------------------------------------------------------------- /content/shmem_init.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | A collective operation that allocates and initializes the resources used by 3 | the \openshmem library. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{Csynopsis} 9 | void @\FuncDecl{shmem\_init}@(void); 10 | \end{Csynopsis} 11 | 12 | \begin{apiarguments} 13 | \apiargument{None.}{}{} 14 | \end{apiarguments} 15 | 16 | \apidescription{ 17 | \FUNC{shmem\_init} allocates and initializes resources used by the \openshmem 18 | library. It is a collective operation that all \acp{PE} must call before any 19 | other \openshmem routine may be called, except \FUNC{shmem\_query\_initialized} 20 | which checks the current initialized state of the library. In the 21 | \openshmem program which it initialized, each call to \FUNC{shmem\_init} must 22 | be matched with a corresponding call to \FUNC{shmem\_finalize}. 23 | 24 | The \FUNC{shmem\_init} and \FUNC{shmem\_init\_thread} initialization 25 | routines may be called multiple times within an \openshmem program. A 26 | corresponding call to \FUNC{shmem\_finalize} must be made for each call to 27 | an \openshmem initialization routine. The \openshmem library must not be 28 | finalized until after the last call to \FUNC{shmem\_finalize} and may be 29 | re-initialized with a subsequent call to an initialization routine. 30 | 31 | } 32 | 33 | \apireturnvalues{ 34 | None. 35 | } 36 | 37 | \begin{DeprecateBlock} 38 | \apinotes{ 39 | As of \openshmem[1.2], the use of \FUNC{start\_pes} has been 40 | deprecated and calls to it should be replaced with calls to \FUNC{shmem\_init}. 41 | While support for \FUNC{start\_pes} is still required in \openshmem libraries, 42 | users are encouraged to use \FUNC{shmem\_init}. An important difference between 43 | \FUNC{shmem\_init} and \FUNC{start\_pes} is that every call to 44 | \FUNC{shmem\_init} within a program must be matched with a call to \FUNC{shmem\_finalize}. 45 | } 46 | \end{DeprecateBlock} 47 | 48 | \begin{apiexamples} 49 | 50 | \apicexample 51 | {The following \FUNC{shmem\_init} example is for \Cstd[11] programs:} 52 | {example_code/shmem_init_example.c} 53 | {} 54 | 55 | \end{apiexamples} 56 | 57 | \end{apidefinition} 58 | -------------------------------------------------------------------------------- /content/shmem_init_thread.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Initializes the \openshmem library, similar to \FUNC{shmem\_init}, and performs any 3 | initialization required for supporting the provided thread level. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{Csynopsis} 9 | int @\FuncDecl{shmem\_init\_thread}@(int requested, int *provided); 10 | \end{Csynopsis} 11 | 12 | \begin{apiarguments} 13 | \apiargument{IN}{requested}{The thread level support requested by the user.} 14 | \apiargument{OUT}{provided}{The thread level support provided by the \openshmem implementation.} 15 | \end{apiarguments} 16 | 17 | \apidescription{ 18 | \FUNC{shmem\_init\_thread} initializes the \openshmem library in the same way as 19 | \FUNC{shmem\_init}. In addition, \FUNC{shmem\_init\_thread} also performs 20 | the initialization required for supporting the provided thread level. 21 | The argument \VAR{requested} is used to specify the desired level of 22 | thread support. The argument \VAR{provided} returns the support level 23 | provided by the library. The allowed values for \VAR{provided} and 24 | \VAR{requested} are \CONST{SHMEM\_THREAD\_SINGLE}, \CONST{SHMEM\_THREAD\_FUNNELED}, 25 | \CONST{SHMEM\_THREAD\_SERIALIZED}, and \CONST{SHMEM\_THREAD\_MULTIPLE}. 26 | 27 | The \FUNC{shmem\_init} and \FUNC{shmem\_init\_thread} initialization 28 | routines may be called multiple times within an \openshmem program. A 29 | corresponding call to \FUNC{shmem\_finalize} must be made for each call to 30 | an \openshmem initialization routine. The \openshmem library must not be 31 | finalized until after the last call to \FUNC{shmem\_finalize} and may be 32 | re-initialized with a subsequent call to an initialization routine. 33 | 34 | If the call to \FUNC{shmem\_init\_thread} 35 | is unsuccessful in allocating and initializing resources for the 36 | \openshmem library, then the behavior of any subsequent call 37 | to the \openshmem library is undefined. 38 | 39 | 40 | } 41 | 42 | \apireturnvalues{ 43 | \FUNC{shmem\_init\_thread} returns 0 upon success; otherwise, it returns a 44 | nonzero value. 45 | } 46 | 47 | \apinotes{ 48 | The \openshmem library can be initialized either by \FUNC{shmem\_init} 49 | or \FUNC{shmem\_init\_thread}. If the \openshmem library is initialized 50 | by \FUNC{shmem\_init}, the library implementation can choose to 51 | support any one of the defined thread levels. 52 | 53 | The \openshmem library may not be able to change the level of threading support 54 | provided after the first initialization call has been made. 55 | } 56 | 57 | \end{apidefinition} 58 | -------------------------------------------------------------------------------- /content/shmem_lock.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Releases, locks, and tests a mutual exclusion memory lock. 3 | } 4 | \begin{apidefinition} 5 | 6 | \begin{Csynopsis} 7 | void @\FuncDecl{shmem\_clear\_lock}@(long *lock); 8 | void @\FuncDecl{shmem\_set\_lock}@(long *lock); 9 | int @\FuncDecl{shmem\_test\_lock}@(long *lock); 10 | \end{Csynopsis} 11 | 12 | \begin{apiarguments} 13 | \apiargument{IN}{lock}{Symmetric address of data object that is a scalar variable or an array 14 | of length \CONST{1}. This data object must be set to \CONST{0} on all 15 | \acp{PE} prior to the first use.} 16 | \end{apiarguments} 17 | 18 | \apidescription{ 19 | The \FUNC{shmem\_set\_lock} routine sets a mutual exclusion lock after 20 | waiting for the lock to be freed by any other \ac{PE} currently holding 21 | the lock. Waiting \acp{PE} are guaranteed to set the lock in a 22 | first-come, first-served manner. The \FUNC{shmem\_test\_lock} routine sets 23 | a mutual exclusion lock only if it is currently cleared. By using this 24 | routine, a \ac{PE} can avoid blocking on a set lock. If the lock is 25 | currently set, the routine returns without waiting. The 26 | \FUNC{shmem\_clear\_lock} routine releases a lock previously set by 27 | \FUNC{shmem\_set\_lock} or \FUNC{shmem\_test\_lock} after performing a 28 | quiet operation on the default context to ensure that all symmetric memory 29 | accesses that occurred during the critical region are complete. These 30 | routines are appropriate for protecting a critical region from simultaneous 31 | update by multiple \acp{PE}. 32 | 33 | The \openshmem lock \ac{API} provides a non-reentrant mutex. Thus, a call to 34 | \FUNC{shmem\_set\_lock} or \FUNC{shmem\_test\_lock} when the calling \ac{PE} 35 | already holds the given lock will result in undefined behavior. In a 36 | multithreaded \openshmem program, the user must ensure that such calls do 37 | not occur. 38 | } 39 | 40 | \apireturnvalues{ 41 | The \FUNC{shmem\_test\_lock} routine returns \CONST{0} if the lock was 42 | originally cleared and this call was able to set the lock. A value of 43 | \CONST{1} is returned if the lock had been set and the call returned without 44 | waiting to set the lock. 45 | } 46 | 47 | \apinotes{ 48 | The lock variable must be initialized to zero before any \ac{PE} performs an 49 | \openshmem lock operation on the given variable. Accessing an in-use lock 50 | variable using any method other than the \openshmem lock \ac{API} (e.g, using 51 | local load/store, \ac{RMA}, or \ac{AMO} operations) results in undefined behavior. 52 | 53 | Calls to \FUNC{shmem\_ctx\_quiet} can be performed prior to calling the 54 | \FUNC{shmem\_clear\_lock} routine to ensure completion of operations issued 55 | on additional contexts. 56 | } 57 | 58 | \begin{apiexamples} 59 | 60 | \apicexample 61 | {The following example uses \FUNC{shmem\_lock} in a \Cstd[11] program.} 62 | {./example_code/shmem_lock_example.c} 63 | {} 64 | 65 | \end{apiexamples} 66 | 67 | \end{apidefinition} 68 | -------------------------------------------------------------------------------- /content/shmem_malloc.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Collectively allocate symmetric memory. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void *@\FuncDecl{shmem\_malloc}@(size_t size); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{size}{The size, in bytes, of a block to be 13 | allocated from the symmetric heap.} 14 | \end{apiarguments} 15 | 16 | 17 | \apidescription{ 18 | The \FUNC{shmem\_malloc} routine is a collective operation on the 19 | world team and returns the symmetric address of a 20 | block of at least \VAR{size} bytes, which shall be suitably aligned 21 | so that it may be assigned to a pointer to any type of object. 22 | This space is allocated from the symmetric heap (in contrast to 23 | \FUNC{malloc}, which allocates from the private heap). 24 | When \VAR{size} is zero, the \FUNC{shmem\_malloc} routine performs 25 | no action and returns a null pointer; otherwise, 26 | \FUNC{shmem\_malloc} calls a procedure that is semantically equivalent 27 | to \FUNC{shmem\_barrier\_all} on exit. This ensures that all \acp{PE} participate 28 | in the memory allocation, and that the memory on other \acp{PE} can be used as soon as the local 29 | \ac{PE} returns. 30 | The value of the \VAR{size} argument must be identical on all 31 | \acp{PE}; otherwise, the behavior is undefined. 32 | } 33 | 34 | \apireturnvalues{ 35 | The \FUNC{shmem\_malloc} routine returns the symmetric address of 36 | the allocated space; otherwise, it returns a null pointer. 37 | } 38 | 39 | \end{apidefinition} 40 | -------------------------------------------------------------------------------- /content/shmem_my_pe.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Returns the number of the calling \ac{PE}. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | int @\FuncDecl{shmem\_my\_pe}@(void); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{None.}{}{} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | This routine returns the \ac{PE} number of the calling \ac{PE}. It accepts no 17 | arguments. The result is an integer between \CONST{0} and \VAR{npes} - 18 | \CONST{1}, where \VAR{npes} is the total number of \acp{PE} executing the 19 | current program. 20 | } 21 | 22 | \apireturnvalues{ 23 | Integer - Between \CONST{0} and \VAR{npes} - \CONST{1} 24 | } 25 | 26 | \apinotes{ 27 | Each \ac{PE} has a unique number or identifier. As of \openshmem[1.2] 28 | the use of \FUNC{\_my\_pe} has been deprecated. Although \openshmem 29 | libraries are required to support the call, users are encouraged to use 30 | \FUNC{shmem\_my\_pe} instead. The behavior and signature of the routine 31 | \FUNC{shmem\_my\_pe} remains unchanged from the deprecated \FUNC{\_my\_pe} 32 | version. 33 | } 34 | 35 | \end{apidefinition} 36 | -------------------------------------------------------------------------------- /content/shmem_n_pes.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Returns the number of \acp{PE} running in a program. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | int @\FuncDecl{shmem\_n\_pes}@(void); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{None.}{}{} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | The routine returns the number of \acp{PE} running in the program. 17 | } 18 | 19 | \apireturnvalues{ 20 | Integer - Number of \acp{PE} running in the \openshmem program. 21 | } 22 | 23 | \apinotes{ 24 | As of \openshmem[1.2] the use of \FUNC{\_num\_pes} has been 25 | deprecated. Although \openshmem libraries are required to support the call, 26 | users are encouraged to use \FUNC{shmem\_n\_pes} instead. The behavior and 27 | signature of the routine \FUNC{shmem\_n\_pes} remains unchanged from the 28 | deprecated \FUNC{\_num\_pes} version. 29 | } 30 | 31 | \begin{apiexamples} 32 | 33 | \apicexample 34 | {The following \FUNC{shmem\_my\_pe} and \FUNC{shmem\_n\_pes} example is for 35 | \CorCpp{} programs:} 36 | {./example_code/shmem_npes_example.c} 37 | {} 38 | 39 | \end{apiexamples} 40 | 41 | \end{apidefinition} 42 | -------------------------------------------------------------------------------- /content/shmem_p.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Copies one data item to a remote \ac{PE}. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | void @\FuncDecl{shmem\_p}@(TYPE *dest, TYPE value, int pe); 9 | void @\FuncDecl{shmem\_p}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 10 | \end{C11synopsis} 11 | where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}. 12 | 13 | \begin{Csynopsis} 14 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_p}@(TYPE *dest, TYPE value, int pe); 15 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_p}@(shmem_ctx_t ctx, TYPE *dest, TYPE value, int pe); 16 | \end{Csynopsis} 17 | where \TYPE{} is one of the standard \ac{RMA} types and has a corresponding \TYPENAME{} specified by Table \ref{stdrmatypes}. 18 | 19 | \begin{apiarguments} 20 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 21 | When this argument is not provided, the operation is performed on 22 | the default context.} 23 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 24 | The type of \dest{} should match that implied in the SYNOPSIS section.} 25 | \apiargument{IN}{value}{The value to be transferred to \VAR{dest}. 26 | The type of \VAR{value} should match that implied in the SYNOPSIS section.} 27 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 28 | with the given \VAR{ctx} when provided, or the default context otherwise.} 29 | \end{apiarguments} 30 | 31 | \apidescription{ 32 | These routines provide a very low latency put capability for single elements of 33 | most basic types. 34 | 35 | As with \FUNC{shmem\_put}, these routines start the remote transfer and may 36 | return before the data is delivered to the remote \ac{PE}. Use 37 | \FUNC{shmem\_quiet} to force completion of all remote \PUT{} transfers. 38 | } 39 | 40 | \apireturnvalues{ 41 | None. 42 | } 43 | 44 | \begin{apiexamples} 45 | 46 | \apicexample 47 | {The following example uses \FUNC{shmem\_p} in a \Cstd[11] program.} 48 | {./example_code/shmem_p_example.c} 49 | {} 50 | 51 | \end{apiexamples} 52 | 53 | \end{apidefinition} 54 | -------------------------------------------------------------------------------- /content/shmem_pcontrol.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Allows the user to control profiling. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void @\FuncDecl{shmem\_pcontrol}@(int level, ...); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | 13 | \apiargument{IN}{level}{The profiling level.} 14 | 15 | \end{apiarguments} 16 | 17 | \apidescription{ 18 | \FUNC{shmem\_pcontrol} sets the profiling level and any other 19 | library defined effects through additional arguments. \openshmem libraries 20 | make no use of this routine and simply return immediately to the user code. 21 | } 22 | 23 | \apireturnvalues{ 24 | None. 25 | } 26 | 27 | \apinotes{ 28 | Since \openshmem has no control of the implementation of the profiling code, 29 | it is impossible to precisely specify the semantics that will be provided by 30 | calls to \FUNC{shmem\_pcontrol}. This vagueness extends to the number of 31 | arguments to the function and their datatypes. However, to provide some 32 | level of portability of user code to different profiling libraries, the 33 | following \VAR{level} values are recommended. 34 | 35 | \begin{itemize} 36 | \item \texttt{level <= 0} Profiling is disabled. 37 | \item \texttt{level == 1} Profiling is enabled at the default level of detail. 38 | \item \texttt{level == 2} Profiling is enabled and profile buffers are 39 | flushed if available. 40 | \item \texttt{level > 2} Profiling is enabled with profile library defined 41 | effects and additional arguments. 42 | \end{itemize} 43 | 44 | The default state after \FUNC{shmem\_init} is recommended to have profiling 45 | enabled at the default level of detail (\texttt{level == 1}). This allows users 46 | to link with a profiling library and to obtain profile output without 47 | having to modify the user-level source code. 48 | } 49 | 50 | \end{apidefinition} 51 | -------------------------------------------------------------------------------- /content/shmem_pe_accessible.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Determines whether a \ac{PE} is accessible via \openshmem's data transfer 3 | routines. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{Csynopsis} 9 | int @\FuncDecl{shmem\_pe\_accessible}@(int pe); 10 | \end{Csynopsis} 11 | 12 | \begin{apiarguments} 13 | \apiargument{IN}{pe}{Specific \ac{PE} to be checked for accessibility from 14 | the local \ac{PE}.} 15 | \end{apiarguments} 16 | 17 | \apidescription{ 18 | \FUNC{shmem\_pe\_accessible} is a query routine that indicates whether a 19 | specified \ac{PE} is accessible via \openshmem from the local \ac{PE}. The 20 | \FUNC{shmem\_pe\_accessible} routine returns a value indicating whether the remote 21 | \ac{PE} is a process running from the same executable file as the local 22 | \ac{PE}, thereby indicating whether full support for symmetric data objects, 23 | which may reside in either static memory or the symmetric heap, is available. 24 | } 25 | 26 | \apireturnvalues{ 27 | The return value is 1 if the specified \ac{PE} is a valid remote \ac{PE} 28 | for \openshmem routines; otherwise, it is 0. 29 | } 30 | 31 | \apinotes{ 32 | This routine may be particularly useful for hybrid programming with other 33 | communication libraries (such as \ac{MPI}) or parallel languages. For 34 | example, when an \ac{MPI} job uses \ac{MPMD} mode, multiple executable 35 | \ac{MPI} programs are executed as part of the same MPI job. In such cases, 36 | \openshmem support may only be available between processes running from the 37 | same executable file. In addition, some environments may allow a hybrid 38 | job to span multiple network partitions. In such scenarios, \openshmem 39 | support may only be available between \acp{PE} within the same partition. 40 | } 41 | 42 | \end{apidefinition} 43 | -------------------------------------------------------------------------------- /content/shmem_pe_quiet.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Waits for completion of all outstanding memory store, blocking 3 | \PUT{}, \ac{AMO}, and \emph{put-with-signal}, as well as 4 | nonblocking \PUT{}, \emph{put-with-signal}, and \GET{} routines 5 | to symmetric data objects issued by the calling \ac{PE} at the target 6 | \acp{PE}. 7 | } 8 | 9 | \begin{apidefinition} 10 | 11 | \begin{Csynopsis} 12 | void @\FuncDecl{shmem\_pe\_quiet}@(const int *target_pes, size_t npes); 13 | void @\FuncDecl{shmem\_ctx\_pe\_quiet}@(shmem_ctx_t ctx, const int *target_pes, size_t npes); 14 | \end{Csynopsis} 15 | 16 | \begin{apiarguments} 17 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 18 | When this argument is not provided, the operation is performed on 19 | the default context.} 20 | \apiargument{IN}{target\_pes}{Address of target \ac{PE} array where the 21 | operations need to be completed} 22 | \apiargument{IN}{npes}{The number of \acp{PE} in the target \ac{PE} array} 23 | 24 | \end{apiarguments} 25 | 26 | \apidescription{ 27 | The \FUNC{shmem\_pe\_quiet} ensures completion of memory store, blocking 28 | \PUT{}, \ac{AMO}, and \emph{put-with-signal}, as well as nonblocking 29 | \PUT{}, \emph{put-with-signal}, and \GET{} routines on the symmetric data 30 | objects issued by the calling \ac{PE} to the target \acp{PE} and on the 31 | given context. If \VAR{npes} is set to 0, the \VAR{target\_pes} is ignored 32 | and the routine returns immediately. 33 | 34 | The completion and visibility semantics of these operations are the same as the 35 | \FUNC{shmem\_quiet} routine. However, it applies only to the target 36 | \acp{PE}, i.e., the operations to the target \acp{PE} are guaranteed to be 37 | complete and visible to all \acp{PE} when \FUNC{shmem\_pe\_quiet} returns. 38 | } 39 | \apireturnvalues{ 40 | None. 41 | } 42 | 43 | \apinotes{ 44 | On certain platforms, when \FUNC{shmem\_pe\_quiet} is invoked on a set of 45 | \acp{PE}, the performance might be equivalent to \FUNC{shmem\_quiet}. 46 | } 47 | \end{apidefinition} 48 | -------------------------------------------------------------------------------- /content/shmem_ptr.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Returns a local pointer to a symmetric data object on the specified \ac{PE} in the world team. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void *@\FuncDecl{shmem\_ptr}@(const void *dest, int pe); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{dest}{The symmetric address of the remotely accessible data 13 | object to be referenced.} 14 | \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which \dest{} is to 15 | be accessed.} 16 | \end{apiarguments} 17 | 18 | \apidescription{ 19 | \FUNC{shmem\_ptr} returns an address that may be used to directly reference 20 | \dest{} on the specified \ac{PE} in the world team. This address can be 21 | assigned to a pointer. After that, ordinary loads and stores to \dest{} may 22 | be performed. The address returned by \FUNC{shmem\_ptr} is a local address 23 | to a remotely accessible data object. Providing this address to an argument 24 | of an \openshmem routine that requires a symmetric address results in 25 | undefined behavior. 26 | 27 | The \FUNC{shmem\_ptr} routine can provide efficient means to accomplish 28 | communication, for example when a sequence of reads and writes to a data 29 | object on a remote \ac{PE} does not match the access pattern provided in an 30 | \openshmem data transfer routine like \FUNC{shmem\_put} or 31 | \FUNC{shmem\_iget}. 32 | } 33 | 34 | \apireturnvalues{ 35 | A local pointer to the remotely accessible \dest{} data object is returned 36 | when it can be accessed using memory loads and stores. Otherwise, a null 37 | pointer is returned. 38 | } 39 | 40 | \apinotes{ 41 | When calling \FUNC{shmem\_ptr}, \dest{} is the address of the referenced 42 | symmetric data object on the calling \ac{PE}. 43 | } 44 | 45 | \begin{apiexamples} 46 | 47 | \apicexample 48 | {In the following \Cstd[11] example, \ac{PE} 0 uses the \FUNC{shmem\_ptr} 49 | routine to query a pointer and directly access the \VAR{dest} array on 50 | \ac{PE} 1:} 51 | {./example_code/shmem_ptr_example.c} 52 | {} 53 | 54 | \end{apiexamples} 55 | 56 | \end{apidefinition} 57 | -------------------------------------------------------------------------------- /content/shmem_put.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | The put routines provide a method for copying data from a contiguous local 3 | data object to a data object on a specified \ac{PE}. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_put}@(TYPE *dest, const TYPE *source, size_t nelems, int pe); 10 | void @\FuncDecl{shmem\_put}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}. 13 | 14 | \begin{Csynopsis} 15 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_put}@(TYPE *dest, const TYPE *source, size_t nelems, int pe); 16 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_put}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the standard \ac{RMA} types and has a corresponding \TYPENAME{} specified by Table \ref{stdrmatypes}. 19 | 20 | \begin{CsynopsisCol} 21 | void @\FuncDecl{shmem\_put\FuncParam{SIZE}}@(void *dest, const void *source, size_t nelems, int pe); 22 | void @\FuncDecl{shmem\_ctx\_put\FuncParam{SIZE}}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, int pe); 23 | \end{CsynopsisCol} 24 | where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}. 25 | 26 | \begin{CsynopsisCol} 27 | void @\FuncDecl{shmem\_putmem}@(void *dest, const void *source, size_t nelems, int pe); 28 | void @\FuncDecl{shmem\_ctx\_putmem}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, int pe); 29 | \end{CsynopsisCol} 30 | 31 | \begin{apiarguments} 32 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 33 | When this argument is not provided, the operation is performed on 34 | the default context.} 35 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 36 | The type of \dest{} should match that implied in the SYNOPSIS section.} 37 | \apiargument{IN}{source}{Local address of the data object containing the data to be copied. 38 | The type of \source{} should match that implied in the SYNOPSIS section.} 39 | \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source} arrays. 40 | For \FUNC{shmem\_putmem} and \FUNC{shmem\_ctx\_putmem}, elements are bytes.} 41 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 42 | with the given \VAR{ctx} when provided, or the default context otherwise.} 43 | \end{apiarguments} 44 | 45 | \apidescription{ 46 | The routines return after the data has been copied out of the \source{} array 47 | on the local \ac{PE}. The delivery of data words into the data object on the 48 | destination \ac{PE} may occur in any order. Furthermore, two successive put 49 | routines may deliver data out of order unless a call to \FUNC{shmem\_fence} is 50 | introduced between the two calls. 51 | } 52 | 53 | \apireturnvalues{ 54 | None. 55 | } 56 | 57 | \begin{apiexamples} 58 | 59 | \apicexample 60 | { The following \FUNC{shmem\_put} example is for \Cstd[11] programs:} 61 | {./example_code/shmem_put_example.c} 62 | {} 63 | \end{apiexamples} 64 | 65 | \end{apidefinition} 66 | -------------------------------------------------------------------------------- /content/shmem_put_nbi.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | The nonblocking put routines provide a method for copying data 3 | from a contiguous local data object to a data object on a specified \ac{PE}. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{C11synopsis} 9 | void @\FuncDecl{shmem\_put\_nbi}@(TYPE *dest, const TYPE *source, size_t nelems, int pe); 10 | void @\FuncDecl{shmem\_put\_nbi}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, int pe); 11 | \end{C11synopsis} 12 | where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}. 13 | 14 | \begin{Csynopsis} 15 | void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_put\_nbi}@(TYPE *dest, const TYPE *source, size_t nelems, int pe); 16 | void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_put\_nbi}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, int pe); 17 | \end{Csynopsis} 18 | where \TYPE{} is one of the standard \ac{RMA} types and has a corresponding \TYPENAME{} specified by Table \ref{stdrmatypes}. 19 | 20 | \begin{CsynopsisCol} 21 | void @\FuncDecl{shmem\_put\FuncParam{SIZE}\_nbi}@(void *dest, const void *source, size_t nelems, int pe); 22 | void @\FuncDecl{shmem\_ctx\_put\FuncParam{SIZE}\_nbi}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, int pe); 23 | \end{CsynopsisCol} 24 | where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}. 25 | 26 | \begin{CsynopsisCol} 27 | void @\FuncDecl{shmem\_putmem\_nbi}@(void *dest, const void *source, size_t nelems, int pe); 28 | void @\FuncDecl{shmem\_ctx\_putmem\_nbi}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, int pe); 29 | \end{CsynopsisCol} 30 | 31 | \begin{apiarguments} 32 | \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. 33 | When this argument is not provided, the operation is performed on 34 | the default context.} 35 | \apiargument{OUT}{dest}{Symmetric address of the destination data object. 36 | The type of \dest{} should match that implied in the SYNOPSIS section.} 37 | \apiargument{IN}{source}{Local address of the object containing the data to be copied. 38 | The type of \source{} should match that implied in the SYNOPSIS section.} 39 | \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source} 40 | arrays. For \FUNC{shmem\_putmem\_nbi} and \FUNC{shmem\_ctx\_putmem\_nbi}, 41 | elements are bytes.} 42 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 43 | with the given \VAR{ctx} when provided, or the default context otherwise.} 44 | \end{apiarguments} 45 | 46 | \apidescription{ 47 | The routines return after initiating the operation. The operation is considered 48 | complete after a subsequent call to \FUNC{shmem\_quiet}. 49 | At the completion of \FUNC{shmem\_quiet}, the data has been copied into the \dest{} array 50 | on the destination \ac{PE}. 51 | The delivery of data words into the data object on the 52 | destination \ac{PE} may occur in any order. 53 | Furthermore, two successive put 54 | routines may deliver data out of order unless a call to \FUNC{shmem\_fence} is 55 | introduced between the two calls. 56 | } 57 | 58 | \apireturnvalues{ 59 | None. 60 | } 61 | 62 | \end{apidefinition} 63 | -------------------------------------------------------------------------------- /content/shmem_query_initialized.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Returns the initialized status of the \openshmem library. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void @\FuncDecl{shmem\_query\_initialized}@(int *initialized); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{OUT}{initialized}{Nonzero if the \openshmem library is in the initialized state. Zero otherwise.} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | The \FUNC{shmem\_query\_initialized} call returns the initialization status 17 | of the \openshmem library. If the application has called an \openshmem 18 | initialization routine and has not yet made the corresponding call to 19 | \FUNC{shmem\_finalize}, this routine returns nonzero. Otherwise, it returns 20 | zero. 21 | 22 | This function may be called at any time, regardless of the thread safety 23 | level or the current initialized state of the \openshmem library. 24 | } 25 | 26 | \apireturnvalues{ 27 | None. 28 | } 29 | 30 | \end{apidefinition} 31 | -------------------------------------------------------------------------------- /content/shmem_query_thread.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Returns the level of thread support provided by the library. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void @\FuncDecl{shmem\_query\_thread}@(int *provided); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{OUT}{provided}{The thread level support provided by the \openshmem implementation.} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | The \FUNC{shmem\_query\_thread} call returns the level of thread support 17 | currently being provided. The value returned will be same as was returned in \VAR{provided} 18 | by a call to \FUNC{shmem\_init\_thread}, if the \openshmem library was 19 | initialized by \FUNC{shmem\_init\_thread}. If the library was initialized by 20 | \FUNC{shmem\_init}, the implementation can choose to provide any one of the defined 21 | thread levels, and \FUNC{shmem\_query\_thread} returns this thread level. 22 | 23 | This function may be called at any time, regardless of the thread safety 24 | level of the \openshmem library. 25 | } 26 | 27 | \apireturnvalues{ 28 | None. 29 | } 30 | 31 | \end{apidefinition} 32 | -------------------------------------------------------------------------------- /content/shmem_realloc.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Collectively resize an allocation of symmetric memory. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void *@\FuncDecl{shmem\_realloc}@(void *ptr, size_t size); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{ptr}{Symmetric address of an object in the symmetric heap.} 13 | \apiargument{IN}{size}{The size, in bytes, of a block to be 14 | allocated from the symmetric heap.} 15 | \end{apiarguments} 16 | 17 | 18 | \apidescription{ 19 | The \FUNC{shmem\_realloc} routine is a collective operation on 20 | the world team that changes the size of the block to 21 | which \VAR{ptr} points to the size (in bytes) specified by 22 | \VAR{size}. The contents of the block are unchanged up to the 23 | lesser of the new and old sizes. 24 | 25 | The \FUNC{shmem\_realloc} routine preserves allocation hints (e.g., 26 | if \VAR{ptr} was allocated by \FUNC{shmem\_malloc\_with\_hints}). 27 | If the new size is larger, the newly allocated portion of the block 28 | is uninitialized. If \VAR{ptr} is a null pointer, the 29 | \FUNC{shmem\_realloc} routine behaves like the \FUNC{shmem\_malloc} 30 | routine for the specified size. If \VAR{size} is \CONST{0} and 31 | \VAR{ptr} is not a null pointer, the block to which it points is 32 | freed as if with \FUNC{shmem\_free}. If the space cannot be 33 | allocated or if hints cannot be preserved, the block to which 34 | \VAR{ptr} points is unchanged and a null pointer is returned. 35 | 36 | \FUNC{shmem\_realloc} may call barriers on both entry and exit, 37 | depending on whether an existing allocation is modified and whether 38 | new memory is allocated, respectively. 39 | It is the user's responsibility to ensure that no communication 40 | operations involving the given memory block are pending on other 41 | communication contexts prior to calling \FUNC{shmem\_realloc}. 42 | 43 | The value of the \VAR{ptr} and \VAR{size} arguments must be 44 | identical on all \acp{PE}; otherwise, the behavior is undefined. 45 | } 46 | 47 | \apireturnvalues{ 48 | The \FUNC{shmem\_realloc} routine returns the symmetric address of 49 | the allocated space (which may have moved); otherwise, all \acp{PE} 50 | return a null pointer. 51 | } 52 | 53 | \apinotes{ 54 | When the \VAR{ptr} argument in a call to \FUNC{shmem\_realloc} corresponds 55 | to a buffer allocated using \FUNC{shmem\_align}, the buffer returned by 56 | \FUNC{shmem\_realloc} is not guaranteed to maintain the alignment requested 57 | in the original call to \FUNC{shmem\_align}. 58 | } 59 | 60 | \end{apidefinition} 61 | -------------------------------------------------------------------------------- /content/shmem_signal_add.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Adds to a signal value of a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | void @\FuncDecl{shmem\_signal\_add}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); 9 | \end{C11synopsis} 10 | 11 | \begin{Csynopsis} 12 | void @\FuncDecl{shmem\_signal\_add}@(uint64_t *sig_addr, uint64_t signal, int pe); 13 | void @\FuncDecl{shmem\_ctx\_signal\_add}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); 14 | \end{Csynopsis} 15 | 16 | \begin{apiarguments} 17 | \apiargument{IN}{ctx}{ 18 | A context handle specifying the context on which to perform the 19 | operation. When this argument is not provided, the operation is 20 | performed on the default context. 21 | } 22 | \apiargument{OUT}{sig\_addr}{ 23 | Symmetric address of the signal data object to be updated on the 24 | remote \ac{PE}. 25 | } 26 | \apiargument{IN}{signal}{ 27 | Unsigned 64-bit value that is used for updating the remote 28 | \VAR{sig\_addr} signal data object. 29 | } 30 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 31 | with the given \VAR{ctx} when provided, or the default context otherwise.} 32 | \end{apiarguments} 33 | 34 | \apidescription{ 35 | \FUNC{shmem\_signal\_add} adds \VAR{value} to the signal data 36 | object pointed to by \VAR{sig\_addr} on \ac{PE}~\VAR{pe}. 37 | The update to the \VAR{sig\_addr} signal object at the calling 38 | \ac{PE} is expected to satisfy the atomicity guarantees as described 39 | in Section~\ref{subsec:signal_atomicity}. 40 | } 41 | 42 | \apireturnvalues{ 43 | None. 44 | } 45 | 46 | \end{apidefinition} 47 | -------------------------------------------------------------------------------- /content/shmem_signal_fetch.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Fetches the signal update on a local data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | uint64_t @\FuncDecl{shmem\_signal\_fetch}@(const uint64_t *sig_addr); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{sig\_addr}{Local address of the remotely accessible signal variable.} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | \FUNC{shmem\_signal\_fetch} performs a fetch operation and returns the 17 | contents of the \VAR{sig\_addr} signal data object. Access to 18 | \VAR{sig\_addr} signal object at the calling \ac{PE} is expected to satisfy 19 | the atomicity guarantees as described in Section~\ref{subsec:signal_atomicity}. 20 | } 21 | 22 | \apireturnvalues{ 23 | Returns the contents of the signal data object, \VAR{sig\_addr}, at the 24 | calling \ac{PE}. 25 | } 26 | 27 | \end{apidefinition} 28 | -------------------------------------------------------------------------------- /content/shmem_signal_set.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Sets the signal value of a remote data object. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | void @\FuncDecl{shmem\_signal\_set}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); 9 | \end{C11synopsis} 10 | 11 | \begin{Csynopsis} 12 | void @\FuncDecl{shmem\_signal\_set}@(uint64_t *sig_addr, uint64_t signal, int pe); 13 | void @\FuncDecl{shmem\_ctx\_signal\_set}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); 14 | \end{Csynopsis} 15 | 16 | \begin{apiarguments} 17 | \apiargument{IN}{ctx}{ 18 | A context handle specifying the context on which to perform the 19 | operation. When this argument is not provided, the operation is 20 | performed on the default context. 21 | } 22 | \apiargument{OUT}{sig\_addr}{ 23 | Symmetric address of the signal data object to be updated on the 24 | remote \ac{PE}. 25 | } 26 | \apiargument{IN}{signal}{ 27 | Unsigned 64-bit value that is used for updating the remote 28 | \VAR{sig\_addr} signal data object. 29 | } 30 | \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated 31 | with the given \VAR{ctx} when provided, or the default context otherwise.} 32 | \end{apiarguments} 33 | 34 | \apidescription{ 35 | \FUNC{shmem\_signal\_set} writes \VAR{value} into the signal data 36 | object pointed to by \VAR{sig\_addr} on \ac{PE}~\VAR{pe}. 37 | The update to the \VAR{sig\_addr} signal object at the calling 38 | \ac{PE} is expected to satisfy the atomicity guarantees as described 39 | in Section~\ref{subsec:signal_atomicity}. 40 | } 41 | 42 | \apireturnvalues{ 43 | None. 44 | } 45 | 46 | \end{apidefinition} 47 | -------------------------------------------------------------------------------- /content/shmem_signal_wait_until.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Wait for a variable on the local \ac{PE} to change from a signaling 3 | operation. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{Csynopsis} 9 | uint64_t @\FuncDecl{shmem\_signal\_wait\_until}@(uint64_t *sig_addr, int cmp, uint64_t cmp_value); 10 | \end{Csynopsis} 11 | 12 | \begin{apiarguments} 13 | 14 | \apiargument{IN}{sig\_addr}{Local address of the remotely accessible source signal variable.} 15 | \apiargument{IN}{cmp}{The comparison operator that compares \VAR{sig\_addr} with 16 | \VAR{cmp\_value}.} 17 | \apiargument{IN}{cmp\_value}{The value against which the object pointed to 18 | by \VAR{sig\_addr} will be compared.} 19 | 20 | \end{apiarguments} 21 | 22 | \apidescription{ 23 | \FUNC{shmem\_signal\_wait\_until} operation blocks until the value contained 24 | in the signal data object, \VAR{sig\_addr}, at the calling \ac{PE} satisfies 25 | the wait condition. In an \openshmem program with single-threaded or 26 | multithreaded \acp{PE}, the \VAR{sig\_addr} object at the calling \ac{PE} is 27 | expected only to be updated as a signal, through the signaling operations 28 | available in Section~\ref{subsec:shmem_put_signal} and 29 | Section~\ref{subsec:shmem_put_signal_nbi}. 30 | 31 | This routine can be used to implement point-to-point synchronization between 32 | \acp{PE} or between threads within the same \ac{PE}. A call to this routine 33 | blocks until the value of \VAR{sig\_addr} at the calling \ac{PE} satisfies 34 | the wait condition specified by the comparison operator, \VAR{cmp}, and 35 | comparison value, \VAR{cmp\_value}. 36 | 37 | Implementations must ensure that \FUNC{shmem\_signal\_wait\_until} do not 38 | return before the update of the memory indicated by \VAR{sig\_addr} is 39 | fully complete. 40 | } 41 | 42 | \apireturnvalues{ 43 | Return the contents of the signal data object, \VAR{sig\_addr}, at the 44 | calling \ac{PE} that satisfies the wait condition. 45 | } 46 | 47 | \end{apidefinition} 48 | -------------------------------------------------------------------------------- /content/shmem_sync_all.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Registers the arrival of a \ac{PE} at a synchronization point and suspends 3 | execution until all other \acp{PE} in the world team arrive at the synchronization point. 4 | For multithreaded programs, execution is suspended 5 | as specified by the threading model (Section \ref{subsec:thread_support}). 6 | } 7 | 8 | \begin{apidefinition} 9 | 10 | \begin{Csynopsis} 11 | void @\FuncDecl{shmem\_sync\_all}@(void); 12 | \end{Csynopsis} 13 | 14 | \begin{apiarguments} 15 | 16 | \apiargument{None.}{}{} 17 | 18 | \end{apiarguments} 19 | 20 | \apidescription{ 21 | 22 | This routine blocks the calling \ac{PE} until all \acp{PE} in the 23 | world team have called \FUNC{shmem\_sync\_all}. 24 | 25 | In a multithreaded \openshmem program, only the calling thread is 26 | blocked. 27 | 28 | In contrast with the \FUNC{shmem\_barrier\_all} routine, 29 | \FUNC{shmem\_sync\_all} only ensures completion and visibility of previously issued memory 30 | stores and does not ensure completion of remote memory updates issued via 31 | \openshmem routines. 32 | } 33 | 34 | \apireturnvalues{ 35 | None. 36 | } 37 | 38 | \apinotes{ 39 | The \FUNC{shmem\_sync\_all} routine is equivalent to calling 40 | \FUNC{shmem\_team\_sync} on the world team. 41 | } 42 | 43 | \end{apidefinition} 44 | -------------------------------------------------------------------------------- /content/shmem_team_config_t.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | A structure type representing team configuration arguments 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | typedef struct { 9 | int num_contexts; 10 | } shmem_team_config_t; 11 | \end{Csynopsis} 12 | 13 | \begin{apiarguments} 14 | None. 15 | \end{apiarguments} 16 | 17 | 18 | \apidescription{ 19 | A team configuration object is provided as an argument to 20 | \FUNC{shmem\_team\_split\_*} routines. 21 | It specifies the requested capabilities of the team to be 22 | created. 23 | 24 | The \VAR{num\_contexts} member specifies the total number of simultaneously 25 | existing contexts that the program requests to create from this team. 26 | These contexts may be created in any number of threads. Successful 27 | creation of a team configured with \VAR{num\_contexts} of $N$ means 28 | that the implementation will make a best effort to reserve enough 29 | resources to support $N$ contexts created from the team 30 | in existence at any given time. It is not a guarantee that $N$ 31 | calls to \FUNC{shmem\_team\_create\_ctx} will succeed. 32 | See Section~\ref{sec:ctx} for more on communication contexts and 33 | Section~\ref{subsec:shmem_team_create_ctx} for team-based context creation. 34 | 35 | When passing a configuration structure to a team creation routine, the mask parameter 36 | specifies which fields the application requests to associate with the new team. 37 | Any configuration parameter value that is not indicated in the mask will be 38 | ignored, and the default value will be used instead. 39 | Therefore, a program must set only the fields for which it does not want the default value. 40 | 41 | A configuration mask is created through a bitwise OR operation of the 42 | following library constants. 43 | A configuration mask value of \CONST{0} indicates that the team 44 | should be created with the default values for all configuration 45 | parameters. 46 | 47 | \apitablerow{\LibConstRef{SHMEM\_TEAM\_NUM\_CONTEXTS}}{ 48 | The team should be created using the value of the 49 | \VAR{num\_contexts} member of the configuration parameter 50 | \VAR{config} as a requirement. 51 | } 52 | 53 | The default values for configuration parameters are: 54 | 55 | \apitablerow{\VAR{num\_contexts} = \CONST{0}}{ 56 | By default, no contexts can be created on a new team 57 | } 58 | } 59 | 60 | \end{apidefinition} 61 | -------------------------------------------------------------------------------- /content/shmem_team_create_ctx.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Create a communication context from a team. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | int @\FuncDecl{shmem\_team\_create\_ctx}@(shmem_team_t team, long options, shmem_ctx_t *ctx); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{team}{A handle to the specified \ac{PE} team.} 13 | \apiargument{IN}{options}{ 14 | The set of options requested for the given context. 15 | Multiple options may be requested by combining them with a bitwise OR 16 | operation; otherwise, \CONST{0} can be given if no options are requested.} 17 | \apiargument{OUT}{ctx}{A handle to the newly created context.} 18 | \end{apiarguments} 19 | 20 | \apidescription{ 21 | The \FUNC{shmem\_team\_create\_ctx} routine creates a new communication 22 | context and returns its handle through the \VAR{ctx} argument. 23 | This context is created from the team specified by the \VAR{team} argument; 24 | however, the context creation operation is not collective. 25 | 26 | In addition to the team, the \FUNC{shmem\_team\_create\_ctx} routine accepts 27 | the same arguments and provides all the same return conditions as the 28 | \FUNC{shmem\_ctx\_create} routine. 29 | 30 | The \FUNC{shmem\_team\_create\_ctx} routine may be called any number of times 31 | to create multiple simultaneously existing contexts for the team. Programs 32 | should request the total number of simultaneous contexts to be created from 33 | the team during team creation. See Section~\ref{subsec:shmem_team_config_t} 34 | for more information on how to request contexts during team creation. 35 | 36 | A call to \FUNC{shmem\_team\_create\_ctx} on a team may fail, regardless 37 | of the configuration request for contexts, if the implementation is unable 38 | to create a context at the time when \FUNC{shmem\_team\_create\_ctx} is 39 | called. 40 | 41 | All explicitly created resources associated with a team must be destroyed 42 | before the \FUNC{shmem\_team\_destroy} routine is called. If a context 43 | returned from \FUNC{shmem\_team\_create\_ctx} is not explicitly 44 | destroyed before the team is destroyed, behavior is undefined. 45 | 46 | All \openshmem routines that operate on this context will do so with 47 | respect to the associated \ac{PE} team. 48 | That is, all point-to-point routines operating on this context will use 49 | team-relative \ac{PE} numbering. 50 | 51 | If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, 52 | then a nonzero value is returned and \VAR{ctx} is set to 53 | \LibConstRef{SHMEM\_CTX\_INVALID}. 54 | If \VAR{team} is otherwise invalid, the behavior is undefined. 55 | } 56 | 57 | \apireturnvalues{ 58 | Zero on success and nonzero otherwise. 59 | } 60 | 61 | \begin{apiexamples} 62 | \apicexample 63 | {The following example demonstrates the use of contexts for multiple teams in a 64 | \CorCpp program. This example shows contexts being used to communicate within 65 | a team using team \ac{PE} numbers, and across teams using translated \ac{PE} numbers.} 66 | {./example_code/shmem_team_context.c} 67 | {} 68 | \end{apiexamples} 69 | 70 | \end{apidefinition} 71 | -------------------------------------------------------------------------------- /content/shmem_team_destroy.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Destroy an existing team. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void @\FuncDecl{shmem\_team\_destroy}@(shmem_team_t team); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{team}{An \openshmem team handle.} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | 17 | The \FUNC{shmem\_team\_destroy} routine is a collective operation that 18 | destroys the team referenced by the team handle argument \VAR{team}. 19 | Upon return, the referenced team is invalid. 20 | 21 | This routine destroys all shareable contexts created from the 22 | referenced team. The user is responsible for destroying all contexts 23 | created from this team with the \CONST{SHMEM\_CTX\_PRIVATE} option 24 | enabled prior to calling this routine; otherwise, the behavior is 25 | undefined. 26 | 27 | If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_WORLD} or any other 28 | predefined team, the behavior is undefined. 29 | 30 | If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, 31 | then no operation is performed. 32 | If \VAR{team} is otherwise invalid, the behavior is undefined. 33 | } 34 | 35 | \apireturnvalues{ 36 | None. 37 | } 38 | 39 | \end{apidefinition} 40 | -------------------------------------------------------------------------------- /content/shmem_team_get_config.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Return the configuration parameters of a given team 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | int @\FuncDecl{shmem\_team\_get\_config}@(shmem_team_t team, long config_mask, shmem_team_config_t *config); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{team}{An \openshmem team handle.} 13 | \apiargument{IN}{config\_mask}{ 14 | The bitwise mask representing the set of configuration parameters to fetch from the given team. 15 | } 16 | \apiargument{OUT}{config}{ 17 | A pointer to the configuration parameters for the given team.} 18 | \end{apiarguments} 19 | 20 | \apidescription{ 21 | \FUNC{shmem\_team\_get\_config} returns through the \VAR{config} argument 22 | the configuration parameters as described by the mask, which were assigned according 23 | to input configuration parameters when the team was created. 24 | The output \VAR{config} argument indicates the \openshmem library's 25 | parameter values at the time \FUNC{shmem\_team\_get\_config} is called. 26 | These values may differ from the parameter values that were assigned at the 27 | time of the team's creation. 28 | 29 | If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, 30 | then no operation is performed. 31 | If \VAR{team} is otherwise invalid, the behavior is undefined. 32 | If \VAR{config\_mask} is 0, then \VAR{shmem\_team\_get\_config} performs no action 33 | and \VAR{config} may or may not be a null pointer. 34 | If \VAR{config} is a null pointer, then \VAR{config\_mask} must be 0, otherwise 35 | the behavior is undefined. 36 | } 37 | 38 | \apireturnvalues{ 39 | If \VAR{team} does not compare equal to 40 | \LibConstRef{SHMEM\_TEAM\_INVALID}, then 41 | \FUNC{shmem\_team\_get\_config} returns \CONST{0}; 42 | otherwise, it returns nonzero. 43 | } 44 | 45 | \end{apidefinition} 46 | -------------------------------------------------------------------------------- /content/shmem_team_my_pe.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Returns the number of the calling \ac{PE} within a specified team. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | int @\FuncDecl{shmem\_team\_my\_pe}@(shmem_team_t team); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{team}{An \openshmem team handle.} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | When \VAR{team} specifies a valid team, the 17 | \FUNC{shmem\_team\_my\_pe} routine returns the number of the calling 18 | \ac{PE} within the specified team. 19 | The number is an integer between $0$ and $N-1$ for a team containing $N$ \acp{PE}. 20 | Each member of the team has a unique number. 21 | 22 | If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, 23 | then the value \CONST{-1} is returned. 24 | If \VAR{team} is otherwise invalid, the behavior is undefined. 25 | } 26 | 27 | \apireturnvalues{ 28 | The number of the calling \ac{PE} within the specified team, or the 29 | value \CONST{-1} if the team handle compares equal to 30 | \LibConstRef{SHMEM\_TEAM\_INVALID}. 31 | } 32 | 33 | \apinotes{ 34 | For the world team, this routine will return the same value as 35 | \FUNC{shmem\_my\_pe}. 36 | } 37 | 38 | \end{apidefinition} 39 | -------------------------------------------------------------------------------- /content/shmem_team_n_pes.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Returns the number of \acp{PE} in a specified team. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | int @\FuncDecl{shmem\_team\_n\_pes}@(shmem_team_t team); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{team}{An \openshmem team handle.} 13 | \end{apiarguments} 14 | 15 | \apidescription{ 16 | When \VAR{team} specifies a valid team, the 17 | \FUNC{shmem\_team\_n\_pes} routine returns the number of \acp{PE} in 18 | the team. 19 | This will always be a value between $1$ and $N$, where $N$ is the 20 | total number of \acp{PE} running in the \openshmem program. 21 | 22 | If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, 23 | then the value \CONST{-1} is returned. 24 | If \VAR{team} is otherwise invalid, the behavior is undefined. 25 | } 26 | 27 | \apireturnvalues{ 28 | The number of \acp{PE} in the specified team, or the value 29 | \CONST{-1} if the team handle compares equal to 30 | \LibConstRef{SHMEM\_TEAM\_INVALID}. 31 | } 32 | 33 | \apinotes{ 34 | For the world team, this routine will return the same value as 35 | \FUNC{shmem\_n\_pes}. 36 | } 37 | 38 | \end{apidefinition} 39 | -------------------------------------------------------------------------------- /content/shmem_team_ptr.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Returns a local pointer to a symmetric data object on the specified \ac{PE} in the specified team. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{Csynopsis} 8 | void *@\FuncDecl{shmem\_team\_ptr}@(shmem_team_t team, const void *dest, int pe); 9 | \end{Csynopsis} 10 | 11 | \begin{apiarguments} 12 | \apiargument{IN}{team}{A handle to the specified team.} 13 | \apiargument{IN}{dest}{The symmetric address of the remotely accessible data 14 | object to be referenced.} 15 | \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number in the 16 | provided team on which \dest{} is to be accessed.} 17 | \end{apiarguments} 18 | 19 | \apidescription{ 20 | \FUNC{shmem\_team\_ptr} returns an address that may be used to directly reference 21 | \dest{} on the specified \ac{PE} in the specified team. This address can be assigned to a 22 | pointer. After that, ordinary loads and stores to \dest{} may be 23 | performed. The address returned by \FUNC{shmem\_team\_ptr} is a local address to 24 | a remotely accessible data object. Providing this address to an argument of 25 | an \openshmem routine that requires a symmetric address results in 26 | undefined behavior. 27 | 28 | The \FUNC{shmem\_team\_ptr} routine can provide efficient means to accomplish 29 | communication, for example when a sequence of reads and writes to a data 30 | object on a remote \ac{PE} does not match the access pattern provided in an 31 | \openshmem data transfer routine like \FUNC{shmem\_put} or 32 | \FUNC{shmem\_iget}. 33 | } 34 | 35 | \apireturnvalues{ 36 | A local pointer to the remotely accessible \dest{} data object is returned 37 | when it can be accessed using memory loads and stores. Otherwise, a null 38 | pointer is returned. 39 | 40 | If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_WORLD}, then 41 | the behavior is identical to that of \FUNC{shmem\_ptr} with same \VAR{dest} 42 | and \VAR{pe} arguments. 43 | If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, 44 | then a null pointer is returned. 45 | If \VAR{team} is otherwise invalid, the behavior is undefined. 46 | } 47 | 48 | \apinotes{ 49 | When calling \FUNC{shmem\_team\_ptr}, \dest{} is the address of the referenced 50 | symmetric data object on the calling \ac{PE}. 51 | } 52 | 53 | \end{apidefinition} 54 | -------------------------------------------------------------------------------- /content/shmem_team_translate_pe.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Translate a given \ac{PE} number from one team to the corresponding 3 | \ac{PE} number in another team. 4 | } 5 | 6 | \begin{apidefinition} 7 | 8 | \begin{Csynopsis} 9 | int @\FuncDecl{shmem\_team\_translate\_pe}@(shmem_team_t src_team, int src_pe, 10 | shmem_team_t dest_team); 11 | \end{Csynopsis} 12 | 13 | \begin{apiarguments} 14 | \apiargument{IN}{src\_team}{An \openshmem team handle.} 15 | \apiargument{IN}{src\_pe}{A \ac{PE} number in \VAR{src\_team}.} 16 | \apiargument{IN}{dest\_team}{An \openshmem team handle.} 17 | \end{apiarguments} 18 | 19 | \apidescription{ 20 | The \FUNC{shmem\_team\_translate\_pe} routine will translate a given \ac{PE} number 21 | in one team into the corresponding \ac{PE} number in another team. 22 | Specifically, given the \VAR{src\_pe} in \VAR{src\_team}, this routine returns that 23 | \ac{PE}'s number in \VAR{dest\_team}. If \VAR{src\_pe} is not a member of both 24 | \VAR{src\_team} and \VAR{dest\_team}, a value of \CONST{-1} is returned. 25 | 26 | If at least one of \VAR{src\_team} and \VAR{dest\_team} compares equal 27 | to \LibConstRef{SHMEM\_TEAM\_INVALID}, then \CONST{-1} is returned. 28 | If either of the \VAR{src\_team} or \VAR{dest\_team} handles are 29 | otherwise invalid, the behavior is undefined. 30 | } 31 | 32 | \apireturnvalues{ 33 | The specified \ac{PE}'s number in the \VAR{dest\_team}, or a value of \CONST{-1} if any 34 | team handle arguments are invalid or the \VAR{src\_pe} is not in both the source and destination teams. 35 | } 36 | 37 | \apinotes{ 38 | If \LibHandleRef{SHMEM\_TEAM\_WORLD} is provided as the 39 | \VAR{dest\_team} parameter, this routine acts as a global \ac{PE} 40 | number translator and will return the corresponding 41 | \LibHandleRef{SHMEM\_TEAM\_WORLD} number. 42 | } 43 | 44 | \begin{apiexamples} 45 | 46 | \apicexample 47 | {The following example demonstrates the use of the team \ac{PE} 48 | number translation routine. The program makes a new team of all 49 | of the even number \acp{PE} in the world team. Then, all \acp{PE} 50 | in the new team acquire their \ac{PE} number in the new team 51 | and translate it to the \ac{PE} number in the world team.} 52 | {./example_code/shmem_team_translate_pe.c} 53 | {} 54 | 55 | \end{apiexamples} 56 | 57 | \end{apidefinition} 58 | -------------------------------------------------------------------------------- /content/shmem_test.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Indicate whether a variable on the local \ac{PE} meets the specified condition. 3 | } 4 | 5 | \begin{apidefinition} 6 | 7 | \begin{C11synopsis} 8 | int @\FuncDecl{shmem\_test}@(TYPE *ivar, int cmp, TYPE cmp_value); 9 | \end{C11synopsis} 10 | where \TYPE{} is one of the standard \ac{AMO} types specified by 11 | Table \ref{stdamotypes}, 12 | \begin{DeprecateBlock} 13 | or \TYPE{} is one of \{\CTYPE{short}, \CTYPE{unsigned short}\}. 14 | \end{DeprecateBlock} 15 | 16 | \begin{Csynopsis} 17 | int @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_test}@(TYPE *ivar, int cmp, TYPE cmp_value); 18 | \end{Csynopsis} 19 | where \TYPE{} is one of the standard \ac{AMO} types and has a 20 | corresponding \TYPENAME{} specified by Table~\ref{stdamotypes}, 21 | \begin{DeprecateBlock} 22 | or \TYPE{} is one of \{\CTYPE{short}, \CTYPE{unsigned short}\} and 23 | has a corresponding \TYPENAME{} specified by Table~\ref{p2psynctypes}. 24 | \end{DeprecateBlock} 25 | 26 | \begin{apiarguments} 27 | 28 | \apiargument{IN}{ivar}{Symmetric address of a remotely accessible data object. 29 | The type of \VAR{ivar} should match that implied in the SYNOPSIS section.} 30 | \apiargument{IN}{cmp}{The comparison operator that compares \VAR{ivar} with 31 | \VAR{cmp\_value}.} 32 | \apiargument{IN}{cmp\_value}{The value against which the object pointed to 33 | by \VAR{ivar} will be compared. 34 | The type of \VAR{cmp\_value} should match that implied in the SYNOPSIS section.} 35 | 36 | \end{apiarguments} 37 | 38 | \apidescription{ 39 | \FUNC{shmem\_test} tests the numeric comparison of the symmetric object 40 | pointed to by \VAR{ivar} with the value \VAR{cmp\_value} according to the 41 | comparison operator \VAR{cmp}. The \VAR{ivar} object at the 42 | calling \ac{PE} may be updated by an \ac{AMO} performed by a thread located 43 | within the calling \ac{PE} or within another \ac{PE}. 44 | 45 | Implementations must ensure that \FUNC{shmem\_test} does not return 1 before 46 | the update of the memory indicated by \VAR{ivar} is fully complete. 47 | } 48 | 49 | \apireturnvalues{ 50 | \FUNC{shmem\_test} returns 1 if the comparison of the symmetric object 51 | pointed to by \VAR{ivar} with the value \VAR{cmp\_value} according to the 52 | comparison operator \VAR{cmp} evaluates to true; otherwise, it returns 0. 53 | } 54 | 55 | \begin{apiexamples} 56 | \apicexample 57 | {The following example demonstrates the use of \FUNC{shmem\_test} to 58 | wait on an array of symmetric objects and return the index of an 59 | element that satisfies the specified condition.} 60 | {./example_code/shmem_test_example1.c} 61 | {} 62 | \end{apiexamples} 63 | 64 | \end{apidefinition} 65 | -------------------------------------------------------------------------------- /content/signaling.tex: -------------------------------------------------------------------------------- 1 | This section specifies the \openshmem support for \OPR{put-with-signal}, 2 | nonblocking \OPR{put-with-signal}, and \OPR{signal-\{add, fetch, set\}} routines. The 3 | put-with-signal routines provide a method for copying data from a contiguous 4 | local data object to a data object on a specified \ac{PE} and subsequently 5 | updating a remote flag to signal completion. 6 | The signal-add and signal-set routines provide methods for updating 7 | the signal object without the associated data transfer of a 8 | put-with-signal operation. 9 | The signal-fetch routine provides support for reading a local signal value. 10 | 11 | \openshmem \OPR{put-with-signal} and \OPR{signal-\{add, set\}} 12 | routines specified in this section have two 13 | variants. In one of the variants, the context handle, \VAR{ctx}, is explicitly 14 | passed as an argument. In this variant, the operation is performed on the 15 | specified context. If the context handle \VAR{ctx} does not correspond to a 16 | valid context, the behavior is undefined. In the other variant, the context 17 | handle is not explicitly passed and thus, the operations are performed on the 18 | default context. 19 | 20 | \subsubsection{Atomicity Guarantees for Signaling Operations} 21 | \label{subsec:signal_atomicity} 22 | All signaling operations put-with-signal, nonblocking put-with-signal, and 23 | signal-\{add, fetch, set\} are performed on a signal data object, a remotely accessible 24 | symmetric object of type \VAR{uint64\_t}. A signal operator in the 25 | put-with-signal routine is an \openshmem library constant that determines the 26 | type of update to be performed as a signal on the signal data object. 27 | 28 | All signaling operations on the signal data object complete as if performed 29 | atomically with respect to the following: 30 | \begin{itemize} 31 | \item other blocking or nonblocking variant of the put-with-signal routine 32 | that updates the signal data object using the same signal update operator; 33 | \item signal-add routine when the put-with-signal routine uses the 34 | \LibConstRef{SHMEM\_SIGNAL\_ADD} signal operator; 35 | \item signal-set routine when the put-with-signal routine uses the 36 | \LibConstRef{SHMEM\_SIGNAL\_SET} signal operator; 37 | \item signal-fetch routine that fetches the signal data object; and 38 | \item any point-to-point synchronization routine that accesses the signal 39 | data object. 40 | \end{itemize} 41 | 42 | \subsubsection{Available Signal Operators} 43 | \label{subsec:signal_operator} 44 | 45 | With the atomicity guarantees as described in 46 | Section~\ref{subsec:signal_atomicity}, the following options can be used as a 47 | signal operator. 48 | 49 | \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_SET}}{An update to signal data 50 | object is an atomic set operation. It writes an unsigned 64-bit value as a 51 | signal into the signal data object on a remote \VAR{PE} as an atomic 52 | operation.} 53 | 54 | \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_ADD}}{An update to signal data 55 | object is an atomic add operation. It adds an unsigned 64-bit value as a 56 | signal into the signal data object on a remote \VAR{PE} as an atomic 57 | operation.} 58 | -------------------------------------------------------------------------------- /content/start_pes.tex: -------------------------------------------------------------------------------- 1 | \apisummary{ 2 | Called at the beginning of an \openshmem program to initialize the execution 3 | environment. This routine is deprecated and is provided for backwards 4 | compatibility. Implementations must include it, and the routine should 5 | function properly and may notify the user about deprecation of its use. 6 | } 7 | 8 | \begin{apidefinition} 9 | 10 | \begin{DeprecateBlock} 11 | \begin{Csynopsis} 12 | void @\FuncDecl{start\_pes}@(int npes); 13 | \end{Csynopsis} 14 | \end{DeprecateBlock} 15 | 16 | \begin{apiarguments} 17 | \apiargument{npes}{Unused}{ Should be set to \CONST{0}.} 18 | \end{apiarguments} 19 | 20 | \apidescription{ 21 | The \FUNC{start\_pes} routine initializes the \openshmem execution 22 | environment. An \openshmem program must call \FUNC{start\_pes}, 23 | \FUNC{shmem\_init}, or \FUNC{shmem\_init\_thread} before calling any other \openshmem routine. Unlike 24 | \FUNC{shmem\_init} and \FUNC{shmem\_init\_thread}, \FUNC{start\_pes} does not require a call to 25 | \FUNC{shmem\_finalize}. Instead, the \openshmem library is implicitly 26 | finalized when the program exits. Implicit finalization is collective and 27 | includes a global synchronization to ensure that all pending communication 28 | is completed before resources are released. 29 | } 30 | 31 | \apireturnvalues{ 32 | None. 33 | } 34 | 35 | \apinotes{ 36 | If any other \openshmem call occurs before \FUNC{start\_pes}, the 37 | behavior is undefined. Although it is recommended to set \VAR{npes} to 38 | \CONST{0} for \FUNC{start\_pes}, this is not mandated. The value is ignored. 39 | Calling \FUNC{start\_pes} more than once has no subsequent 40 | effect. 41 | 42 | As of \openshmem[1.2] the use of \FUNC{start\_pes} has 43 | been deprecated. Although \openshmem libraries are required to support the 44 | call, users are encouraged to use \FUNC{shmem\_init} or 45 | \FUNC{shmem\_init\_thread} instead. 46 | } 47 | 48 | \end{apidefinition} 49 | -------------------------------------------------------------------------------- /content/the_openshmem_effort.tex: -------------------------------------------------------------------------------- 1 | \openshmem is a \ac{PGAS} library interface specification. \openshmem aims to 2 | provide a standard \ac{API} for SHMEM libraries to aid portability and 3 | facilitate uniform predictable results of \openshmem programs by explicitly 4 | stating the behavior and semantics of the \openshmem library calls. Through the 5 | different versions, \openshmem will continue to address the requirements of the 6 | \ac{PGAS} community. As of this specification, many existing vendors support 7 | \openshmem-compliant implementations and new vendors are developing 8 | \openshmem library implementations to help the users write portable \openshmem 9 | code. This ensures that programs can run on multiple platforms without having to 10 | deal with subtle vendor-specific implementation differences. For more details on 11 | the history of \openshmem please refer to the 12 | \hyperref[sec:openshmem_history]{History of \openshmem} section. 13 | 14 | The \openshmem\footnote{The \openshmem specification is owned by Open Source 15 | Software Solutions Inc., a nonprofit organization, under an agreement with 16 | \ac{HPE}.} effort is driven by the \ac{DoD} with continuous input from the \openshmem community. 17 | To see all of the contributors and participants for the \openshmem \ac{API}, 18 | please see: \url{http://www.openshmem.org/site/Contributors}. In addition to the 19 | specification, the effort includes a reference \openshmem 20 | implementation, validation and verification suites, tools, a mailing list and 21 | website infrastructure to support specification activities. For more information 22 | please refer to: \url{http://www.openshmem.org/}. 23 | -------------------------------------------------------------------------------- /example_code/.gitignore: -------------------------------------------------------------------------------- 1 | *.[cf]x 2 | -------------------------------------------------------------------------------- /example_code/Makefile: -------------------------------------------------------------------------------- 1 | CC = oshcc 2 | CFLAGS ?= -Wall -Wextra -pedantic -Werror 3 | 4 | FC = oshfort 5 | FFLAGS ?= -Wall -Wextra 6 | 7 | RUNCMD = oshrun 8 | RUNOPT = -np 4 9 | 10 | C_TESTS = $(wildcard *.c) 11 | C_BINS = $(C_TESTS:.c=.cx) 12 | 13 | F_TESTS = $(wildcard *.f90) 14 | F_BINS = $(F_TESTS:.f90=.fx) 15 | 16 | shmem_ctx.cx: CFLAGS += -fopenmp 17 | 18 | .PHONY: all run clean 19 | 20 | all: $(C_BINS) $(F_BINS) 21 | 22 | %.cx: %.c 23 | $(CC) $(CFLAGS) -o $@ $+ 24 | 25 | %.fx: %.f90 26 | $(FC) $(FFLAGS) -o $@ $+ 27 | 28 | run: $(C_BINS) 29 | @for bin in $+; do \ 30 | echo -- $$bin ------------------------------; \ 31 | $(RUNCMD) $(RUNOPT) ./$$bin; \ 32 | echo -- exit status: $$?; \ 33 | done 34 | 35 | clean: 36 | rm -f $(C_BINS) $(F_BINS) 37 | -------------------------------------------------------------------------------- /example_code/amo_scenario_1.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static uint64_t x = 0; 6 | 7 | shmem_init(); 8 | 9 | int target = 0; 10 | shmem_ctx_t ctx; 11 | 12 | if (shmem_my_pe() > 0) { 13 | shmem_team_create_ctx(SHMEM_TEAM_WORLD, 0, &ctx); 14 | } 15 | else { 16 | shmem_team_create_ctx(SHMEM_TEAM_SHARED, 0, &ctx); 17 | target = shmem_team_translate_pe(SHMEM_TEAM_WORLD, 0, SHMEM_TEAM_SHARED); 18 | } 19 | 20 | // Undefined behavior: The following AMO may access the same 21 | // location concurrently using different atomicity domains. 22 | if (target >= 0) 23 | shmem_ctx_uint64_atomic_inc(ctx, &x, target); 24 | 25 | shmem_ctx_destroy(ctx); 26 | shmem_finalize(); 27 | return 0; 28 | } 29 | -------------------------------------------------------------------------------- /example_code/amo_scenario_2.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static uint64_t x = 0; 6 | 7 | shmem_init(); 8 | /* Undefined behavior: The following AMOs access the same location 9 | * concurrently using different types. */ 10 | if (shmem_my_pe() > 0) 11 | shmem_uint32_atomic_or((uint32_t *)&x, shmem_my_pe() + 1, 0); 12 | else 13 | shmem_uint64_atomic_or(&x, shmem_my_pe() + 1, 0); 14 | 15 | shmem_finalize(); 16 | return 0; 17 | } 18 | -------------------------------------------------------------------------------- /example_code/amo_scenario_3.c: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int main(void) { 4 | static int x = 0, y = 0; 5 | 6 | shmem_init(); 7 | shmem_int_atomic_inc(&x, (shmem_my_pe() + 1) % shmem_n_pes()); 8 | /* Undefined behavior: The following reduction operation performs accesses to 9 | * symmetric variable 'x' that are concurrent with previously issued atomic 10 | * increment operations on the same variable. */ 11 | shmem_int_sum_reduce(SHMEM_TEAM_WORLD, &y, &x, 1); 12 | 13 | shmem_finalize(); 14 | return 0; 15 | } 16 | -------------------------------------------------------------------------------- /example_code/amo_scenario_4.c: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int main(void) { 4 | static int x = 0; 5 | 6 | shmem_init(); 7 | /* Undefined behavior: OpenSHMEM atomic increment operations are concurrent 8 | * with the local increment of symmetric variable 'x'. */ 9 | if (shmem_my_pe() > 0) 10 | shmem_int_atomic_inc(&x, 0); 11 | else 12 | x++; 13 | 14 | shmem_finalize(); 15 | return 0; 16 | } 17 | -------------------------------------------------------------------------------- /example_code/hello-openshmem-c.output: -------------------------------------------------------------------------------- 1 | Hello from 0 of 4 2 | Hello from 2 of 4 3 | Hello from 3 of 4 4 | Hello from 1 of 4 5 | -------------------------------------------------------------------------------- /example_code/hello-openshmem.c: -------------------------------------------------------------------------------- 1 | #include /* The OpenSHMEM header file */ 2 | #include 3 | 4 | int main(void) { 5 | shmem_init(); 6 | int mype = shmem_my_pe(); 7 | int npes = shmem_n_pes(); 8 | printf("Hello from %d of %d\n", mype, npes); 9 | shmem_finalize(); 10 | return 0; 11 | } 12 | -------------------------------------------------------------------------------- /example_code/hybrid_mpi_mapping_id.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | int main(int argc, char *argv[]) { 6 | MPI_Init(&argc, &argv); 7 | shmem_init(); 8 | 9 | int mype = shmem_team_my_pe(SHMEM_TEAM_WORLD); 10 | int npes = shmem_team_n_pes(SHMEM_TEAM_WORLD); 11 | 12 | static int myrank; 13 | MPI_Comm_rank(MPI_COMM_WORLD, &myrank); 14 | 15 | int *mpi_ranks = shmem_calloc(npes, sizeof(int)); 16 | 17 | shmem_int_collect(SHMEM_TEAM_WORLD, mpi_ranks, &myrank, 1); 18 | if (mype == 0) 19 | for (int i = 0; i < npes; i++) 20 | printf("PE %d's MPI rank is %d\n", i, mpi_ranks[i]); 21 | 22 | shmem_free(mpi_ranks); 23 | 24 | shmem_finalize(); 25 | MPI_Finalize(); 26 | 27 | return 0; 28 | } 29 | -------------------------------------------------------------------------------- /example_code/hybrid_mpi_mapping_id_shmem_comm.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | int main(int argc, char *argv[]) { 6 | MPI_Init(&argc, &argv); 7 | shmem_init(); 8 | 9 | int mype = shmem_my_pe(); 10 | 11 | MPI_Comm shmem_comm; 12 | MPI_Comm_split(MPI_COMM_WORLD, 0, mype, &shmem_comm); 13 | 14 | int myrank; 15 | MPI_Comm_rank(shmem_comm, &myrank); 16 | printf("PE %d's MPI rank is %d\n", mype, myrank); 17 | 18 | MPI_Comm_free(&shmem_comm); 19 | shmem_finalize(); 20 | MPI_Finalize(); 21 | 22 | return 0; 23 | } 24 | -------------------------------------------------------------------------------- /example_code/pshmem_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | static double total_put_time = 0.0; 6 | static double avg_put_time = 0.0; 7 | static long put_count = 0; 8 | 9 | static inline double get_wtime(void) { 10 | double wtime = 0.0; 11 | struct timeval tv; 12 | gettimeofday(&tv, NULL); 13 | wtime = tv.tv_sec; 14 | wtime += (double)tv.tv_usec / 1.0e6; 15 | return wtime; 16 | } 17 | 18 | void shmem_long_put(long *dest, const long *source, size_t nelems, int pe) { 19 | double t_start = get_wtime(); /* Start timer */ 20 | pshmem_long_put(dest, source, nelems, pe); /* Name shifted call to put */ 21 | total_put_time += get_wtime() - t_start; /* Calculate total time elapsed */ 22 | put_count += 1; /* Increment put counts */ 23 | avg_put_time = total_put_time / (double)put_count; /* Calculate average put latency */ 24 | 25 | return; 26 | } 27 | -------------------------------------------------------------------------------- /example_code/pshmem_no_weak_symbol.c: -------------------------------------------------------------------------------- 1 | #ifdef BUILD_PSHMEM_INTERFACES 2 | #define SHFN(fn) p##fn 3 | #else 4 | #define SHFN(fn) fn 5 | #endif 6 | 7 | void SHFN(shmem_example)(/* appropriate arguments */) { /* function body */ 8 | } 9 | -------------------------------------------------------------------------------- /example_code/pshmem_weak_symbol_1.c: -------------------------------------------------------------------------------- 1 | #pragma weak shmem_example = pshmem_example 2 | 3 | void pshmem_example(/* appropriate arguments */) { /* function body */ 4 | } 5 | -------------------------------------------------------------------------------- /example_code/pshmem_weak_symbol_2.c: -------------------------------------------------------------------------------- 1 | void pshmem_example(/* appropriate arguments */) { /* function body */ 2 | } 3 | 4 | void shmem_example(/* appropriate arguments */) 5 | __attribute__((weak, alias("pshmem_example"))); 6 | -------------------------------------------------------------------------------- /example_code/shmem_alltoall_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | int main(void) { 6 | shmem_init(); 7 | int mype = shmem_my_pe(); 8 | int npes = shmem_n_pes(); 9 | 10 | const int count = 2; 11 | int64_t *dest = (int64_t *)shmem_malloc(count * npes * sizeof(int64_t)); 12 | int64_t *source = (int64_t *)shmem_malloc(count * npes * sizeof(int64_t)); 13 | 14 | /* assign source values */ 15 | for (int pe = 0; pe < npes; pe++) { 16 | for (int i = 0; i < count; i++) { 17 | source[(pe * count) + i] = mype + pe; 18 | dest[(pe * count) + i] = 9999; 19 | } 20 | } 21 | /* wait for all PEs to initialize source/dest */ 22 | shmem_team_sync(SHMEM_TEAM_WORLD); 23 | 24 | /* alltoall on all PES */ 25 | shmem_int64_alltoall(SHMEM_TEAM_WORLD, dest, source, count); 26 | 27 | /* verify results */ 28 | for (int pe = 0; pe < npes; pe++) { 29 | for (int i = 0; i < count; i++) { 30 | if (dest[(pe * count) + i] != pe + mype) { 31 | printf("[%d] ERROR: dest[%d]=%" PRId64 ", should be %d\n", mype, (pe * count) + i, 32 | dest[(pe * count) + i], pe + mype); 33 | } 34 | } 35 | } 36 | 37 | shmem_free(dest); 38 | shmem_free(source); 39 | shmem_finalize(); 40 | return 0; 41 | } 42 | -------------------------------------------------------------------------------- /example_code/shmem_alltoalls_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | int main(void) { 6 | shmem_init(); 7 | int mype = shmem_my_pe(); 8 | int npes = shmem_n_pes(); 9 | 10 | const int count = 2; 11 | const ptrdiff_t dst = 2; 12 | const ptrdiff_t sst = 3; 13 | int64_t *dest = (int64_t *)shmem_malloc(count * dst * npes * sizeof(int64_t)); 14 | int64_t *source = (int64_t *)shmem_malloc(count * sst * npes * sizeof(int64_t)); 15 | 16 | /* assign source values */ 17 | for (int pe = 0; pe < npes; pe++) { 18 | for (int i = 0; i < count; i++) { 19 | source[sst * ((pe * count) + i)] = mype + pe; 20 | dest[dst * ((pe * count) + i)] = 9999; 21 | } 22 | } 23 | /* wait for all PEs to initialize source/dest */ 24 | shmem_team_sync(SHMEM_TEAM_WORLD); 25 | 26 | /* alltoalls on all PES */ 27 | shmem_int64_alltoalls(SHMEM_TEAM_WORLD, dest, source, dst, sst, count); 28 | 29 | /* verify results */ 30 | for (int pe = 0; pe < npes; pe++) { 31 | for (int i = 0; i < count; i++) { 32 | int j = dst * ((pe * count) + i); 33 | if (dest[j] != pe + mype) { 34 | printf("[%d] ERROR: dest[%d]=%" PRId64 ", should be %d\n", mype, j, dest[j], 35 | pe + mype); 36 | } 37 | } 38 | } 39 | 40 | shmem_free(dest); 41 | shmem_free(source); 42 | shmem_finalize(); 43 | return 0; 44 | } 45 | -------------------------------------------------------------------------------- /example_code/shmem_atomic_add_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static int dst = 22; 6 | shmem_init(); 7 | int mype = shmem_my_pe(); 8 | if (mype == 1) 9 | shmem_atomic_add(&dst, 44, 0); 10 | shmem_barrier_all(); 11 | printf("%d: dst = %d\n", mype, dst); 12 | shmem_finalize(); 13 | return 0; 14 | } 15 | -------------------------------------------------------------------------------- /example_code/shmem_atomic_compare_swap_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static int race_winner = -1; 6 | shmem_init(); 7 | int mype = shmem_my_pe(); 8 | int oldval = shmem_atomic_compare_swap(&race_winner, -1, mype, 0); 9 | if (oldval == -1) 10 | printf("PE %d was first\n", mype); 11 | shmem_finalize(); 12 | return 0; 13 | } 14 | -------------------------------------------------------------------------------- /example_code/shmem_atomic_fetch_add_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | int old = -1; 6 | static int dst = 22; 7 | shmem_init(); 8 | int mype = shmem_my_pe(); 9 | if (mype == 1) 10 | old = shmem_atomic_fetch_add(&dst, 44, 0); 11 | shmem_barrier_all(); 12 | printf("%d: old = %d, dst = %d\n", mype, old, dst); 13 | shmem_finalize(); 14 | return 0; 15 | } 16 | -------------------------------------------------------------------------------- /example_code/shmem_atomic_fetch_inc_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | int old = -1; 6 | static int dst = 22; 7 | shmem_init(); 8 | int mype = shmem_my_pe(); 9 | if (mype == 0) 10 | old = shmem_atomic_fetch_inc(&dst, 1); 11 | shmem_barrier_all(); 12 | printf("%d: old = %d, dst = %d\n", mype, old, dst); 13 | shmem_finalize(); 14 | return 0; 15 | } 16 | -------------------------------------------------------------------------------- /example_code/shmem_atomic_inc_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static int dst = 74; 6 | shmem_init(); 7 | int mype = shmem_my_pe(); 8 | if (mype == 0) 9 | shmem_atomic_inc(&dst, 1); 10 | shmem_barrier_all(); 11 | printf("%d: dst = %d\n", mype, dst); 12 | shmem_finalize(); 13 | return 0; 14 | } 15 | -------------------------------------------------------------------------------- /example_code/shmem_atomic_swap_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static long dest; 6 | shmem_init(); 7 | int mype = shmem_my_pe(); 8 | int npes = shmem_n_pes(); 9 | dest = mype; 10 | shmem_barrier_all(); 11 | long new_val = mype; 12 | if (mype & 1) { 13 | long swapped_val = shmem_atomic_swap(&dest, new_val, (mype + 1) % npes); 14 | printf("%d: dest = %ld, swapped = %ld\n", mype, dest, swapped_val); 15 | } 16 | shmem_finalize(); 17 | return 0; 18 | } 19 | -------------------------------------------------------------------------------- /example_code/shmem_barrier_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static int x = 10101; 6 | static long pSync[SHMEM_BARRIER_SYNC_SIZE]; 7 | for (int i = 0; i < SHMEM_BARRIER_SYNC_SIZE; i++) 8 | pSync[i] = SHMEM_SYNC_VALUE; 9 | 10 | shmem_init(); 11 | int mype = shmem_my_pe(); 12 | int npes = shmem_n_pes(); 13 | 14 | if (mype % 2 == 0) { 15 | /* put to next even PE in a circular fashion */ 16 | shmem_p(&x, 4, (mype + 2) % npes); 17 | /* synchronize all even pes */ 18 | shmem_barrier(0, 1, (npes / 2 + npes % 2), pSync); 19 | } 20 | printf("%d: x = %d\n", mype, x); 21 | shmem_finalize(); 22 | return 0; 23 | } 24 | -------------------------------------------------------------------------------- /example_code/shmem_barrierall_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static int x = 1010; 6 | 7 | shmem_init(); 8 | int mype = shmem_my_pe(); 9 | int npes = shmem_n_pes(); 10 | 11 | /* put to next PE in a circular fashion */ 12 | shmem_p(&x, 4, (mype + 1) % npes); 13 | 14 | /* synchronize all PEs */ 15 | shmem_barrier_all(); 16 | printf("%d: x = %d\n", mype, x); 17 | shmem_finalize(); 18 | return 0; 19 | } 20 | -------------------------------------------------------------------------------- /example_code/shmem_broadcast_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | int main(void) { 6 | static long source[4], dest[4]; 7 | 8 | shmem_init(); 9 | int mype = shmem_my_pe(); 10 | int npes = shmem_n_pes(); 11 | 12 | if (mype == 0) 13 | for (int i = 0; i < 4; i++) 14 | source[i] = i; 15 | 16 | shmem_broadcast(SHMEM_TEAM_WORLD, dest, source, 4, 0); 17 | 18 | printf("%d: %ld, %ld, %ld, %ld\n", mype, dest[0], dest[1], dest[2], dest[3]); 19 | shmem_finalize(); 20 | return 0; 21 | } 22 | -------------------------------------------------------------------------------- /example_code/shmem_collect_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | int main(void) { 6 | static long lock = 0; 7 | 8 | shmem_init(); 9 | int mype = shmem_my_pe(); 10 | int npes = shmem_n_pes(); 11 | int my_nelem = mype + 1; /* linearly increasing number of elements with PE */ 12 | int total_nelem = (npes * (npes + 1)) / 2; 13 | 14 | int *source = (int *)shmem_malloc(npes * sizeof(int)); /* symmetric alloc */ 15 | int *dest = (int *)shmem_malloc(total_nelem * sizeof(int)); 16 | 17 | for (int i = 0; i < my_nelem; i++) 18 | source[i] = (mype * (mype + 1)) / 2 + i; 19 | for (int i = 0; i < total_nelem; i++) 20 | dest[i] = -9999; 21 | 22 | /* Wait for all PEs to initialize source/dest: */ 23 | shmem_team_sync(SHMEM_TEAM_WORLD); 24 | 25 | shmem_int_collect(SHMEM_TEAM_WORLD, dest, source, my_nelem); 26 | 27 | shmem_set_lock(&lock); /* Lock prevents interleaving printfs */ 28 | printf("%d: %d", mype, dest[0]); 29 | for (int i = 1; i < total_nelem; i++) 30 | printf(", %d", dest[i]); 31 | printf("\n"); 32 | shmem_clear_lock(&lock); 33 | shmem_finalize(); 34 | return 0; 35 | } 36 | -------------------------------------------------------------------------------- /example_code/shmem_ctx.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | long task_cntr = 0; /* Next task counter */ 5 | long tasks_done = 0; /* Tasks done by this PE */ 6 | long total_done = 0; /* Total tasks done by all PEs */ 7 | 8 | int main(void) { 9 | int tl, i; 10 | long ntasks = 1024; /* Total tasks per PE */ 11 | 12 | shmem_init_thread(SHMEM_THREAD_MULTIPLE, &tl); 13 | if (tl != SHMEM_THREAD_MULTIPLE) 14 | shmem_global_exit(1); 15 | 16 | int mype = shmem_my_pe(); 17 | int npes = shmem_n_pes(); 18 | 19 | #pragma omp parallel reduction(+ : tasks_done) 20 | { 21 | shmem_ctx_t ctx; 22 | int task_pe = mype, pes_done = 0; 23 | int ret = shmem_ctx_create(SHMEM_CTX_PRIVATE, &ctx); 24 | 25 | if (ret != 0) { 26 | printf("%d: Error creating context (%d)\n", mype, ret); 27 | shmem_global_exit(2); 28 | } 29 | 30 | /* Process tasks on all PEs, starting with the local PE. After 31 | * all tasks on a PE are completed, help the next PE. */ 32 | while (pes_done < npes) { 33 | long task = shmem_atomic_fetch_inc(ctx, &task_cntr, task_pe); 34 | while (task < ntasks) { 35 | /* Perform task (task_pe, task) */ 36 | tasks_done++; 37 | task = shmem_atomic_fetch_inc(ctx, &task_cntr, task_pe); 38 | } 39 | pes_done++; 40 | task_pe = (task_pe + 1) % npes; 41 | } 42 | 43 | shmem_ctx_destroy(ctx); 44 | } 45 | 46 | shmem_long_sum_reduce(SHMEM_TEAM_WORLD, &total_done, &tasks_done, 1); 47 | 48 | int result = (total_done != ntasks * npes); 49 | shmem_finalize(); 50 | return result; 51 | } 52 | -------------------------------------------------------------------------------- /example_code/shmem_ctx_invalid.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | _Thread_local shmem_ctx_t thread_ctx = SHMEM_CTX_INVALID; 6 | 7 | void lib_thread_register(void) { 8 | if (thread_ctx == SHMEM_CTX_INVALID) 9 | if (shmem_ctx_create(SHMEM_CTX_PRIVATE, &thread_ctx) && shmem_ctx_create(0, &thread_ctx)) 10 | thread_ctx = SHMEM_CTX_DEFAULT; 11 | } 12 | 13 | void lib_thread_unregister(void) { 14 | if (thread_ctx != SHMEM_CTX_DEFAULT) { 15 | shmem_ctx_destroy(thread_ctx); 16 | thread_ctx = SHMEM_CTX_INVALID; 17 | } 18 | } 19 | 20 | void lib_thread_putmem(void *dst, const void *src, size_t nbytes, int pe) { 21 | shmem_ctx_putmem(thread_ctx, dst, src, nbytes, pe); 22 | } 23 | 24 | int main() { 25 | int provided; 26 | if (shmem_init_thread(SHMEM_THREAD_MULTIPLE, &provided)) 27 | return 1; 28 | if (provided != SHMEM_THREAD_MULTIPLE) 29 | shmem_global_exit(2); 30 | 31 | const int mype = shmem_my_pe(); 32 | const int npes = shmem_n_pes(); 33 | const int count = 1 << 15; 34 | 35 | int *src_bufs[npes]; 36 | int *dst_bufs[npes]; 37 | for (int i = 0; i < npes; i++) { 38 | src_bufs[i] = shmem_calloc(count, sizeof(*src_bufs[i])); 39 | if (src_bufs[i] == NULL) 40 | shmem_global_exit(3); 41 | dst_bufs[i] = shmem_calloc(count, sizeof(*dst_bufs[i])); 42 | if (dst_bufs[i] == NULL) 43 | shmem_global_exit(4); 44 | } 45 | 46 | #pragma omp parallel 47 | { 48 | int my_thrd = omp_get_thread_num(); 49 | #pragma omp for 50 | for (int i = 0; i < npes; i++) 51 | for (int j = 0; j < count; j++) 52 | src_bufs[i][j] = (mype << 10) + my_thrd; 53 | 54 | lib_thread_register(); 55 | 56 | #pragma omp for 57 | for (int i = 0; i < npes; i++) 58 | lib_thread_putmem(dst_bufs[mype], src_bufs[i], count * sizeof(*src_bufs[i]), i); 59 | 60 | lib_thread_unregister(); 61 | } 62 | 63 | shmem_finalize(); 64 | return 0; 65 | } 66 | -------------------------------------------------------------------------------- /example_code/shmem_ctx_pipelined_reduce.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | #define LEN 8192 /* Full buffer length */ 6 | #define PLEN 512 /* Length of each pipeline stage */ 7 | 8 | int in_buf[LEN], out_buf[LEN]; 9 | 10 | int main(void) { 11 | int i, j, *pbuf[2]; 12 | shmem_ctx_t ctx[2]; 13 | 14 | shmem_init(); 15 | int mype = shmem_my_pe(); 16 | int npes = shmem_n_pes(); 17 | 18 | pbuf[0] = shmem_malloc(PLEN * npes * sizeof(int)); 19 | pbuf[1] = shmem_malloc(PLEN * npes * sizeof(int)); 20 | 21 | int ret_0 = shmem_ctx_create(0, &ctx[0]); 22 | int ret_1 = shmem_ctx_create(0, &ctx[1]); 23 | if (ret_0 || ret_1) 24 | shmem_global_exit(1); 25 | 26 | for (i = 0; i < LEN; i++) { 27 | in_buf[i] = mype; 28 | out_buf[i] = 0; 29 | } 30 | 31 | int p_idx = 0, p = 0; /* Index of ctx and pbuf (p_idx) for cur. pipeline stage (p) */ 32 | for (i = 1; i <= npes; i++) 33 | shmem_put_nbi(ctx[p_idx], &pbuf[p_idx][PLEN * mype], &in_buf[PLEN * p], PLEN, 34 | (mype + i) % npes); 35 | 36 | /* Issue puts for pipeline stage p, then accumulate results for stage p-1 */ 37 | for (p = 1; p < LEN / PLEN; p++) { 38 | p_idx ^= 1; 39 | for (i = 1; i <= npes; i++) 40 | shmem_put_nbi(ctx[p_idx], &pbuf[p_idx][PLEN * mype], &in_buf[PLEN * p], PLEN, 41 | (mype + i) % npes); 42 | 43 | shmem_ctx_quiet(ctx[p_idx ^ 1]); 44 | shmem_sync_all(); 45 | for (i = 0; i < npes; i++) 46 | for (j = 0; j < PLEN; j++) 47 | out_buf[PLEN * (p - 1) + j] += pbuf[p_idx ^ 1][PLEN * i + j]; 48 | } 49 | 50 | shmem_ctx_quiet(ctx[p_idx]); 51 | shmem_sync_all(); 52 | for (i = 0; i < npes; i++) 53 | for (j = 0; j < PLEN; j++) 54 | out_buf[PLEN * (p - 1) + j] += pbuf[p_idx][PLEN * i + j]; 55 | 56 | shmem_finalize(); 57 | return 0; 58 | } 59 | -------------------------------------------------------------------------------- /example_code/shmem_ctx_session_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | #include 5 | 6 | #define N_UPDATES (1lu << 18) 7 | #define N_INDICES (1lu << 10) 8 | #define N_VALUES (1lu << 31) 9 | 10 | int main(void) { 11 | 12 | shmem_init(); 13 | 14 | uint64_t *table = shmem_calloc(N_INDICES, sizeof(uint64_t)); 15 | 16 | int mype = shmem_my_pe(); 17 | int npes = shmem_n_pes(); 18 | srand(mype); 19 | 20 | shmem_ctx_t ctx; 21 | int ret = shmem_ctx_create(0, &ctx); 22 | if (ret != 0) { 23 | printf("%d: Error creating context (%d)\n", mype, ret); 24 | shmem_global_exit(1); 25 | } 26 | 27 | shmem_ctx_session_config_t config; 28 | long config_mask; 29 | config.total_ops = N_UPDATES; 30 | config_mask = SHMEM_CTX_SESSION_TOTAL_OPS; 31 | 32 | shmem_ctx_session_start(ctx, SHMEM_CTX_SESSION_BATCH, &config, config_mask); 33 | 34 | for (size_t i = 0; i < N_UPDATES; i++) { 35 | int random_pe = rand() % npes; 36 | size_t random_idx = rand() % N_INDICES; 37 | uint64_t random_val = rand() % N_VALUES; 38 | shmem_ctx_uint64_atomic_xor(ctx, &table[random_idx], random_val, random_pe); 39 | } 40 | 41 | shmem_ctx_session_stop(ctx); 42 | shmem_ctx_quiet(ctx); /* shmem_ctx_session_stop() does not quiet the context. */ 43 | shmem_sync_all(); /* shmem_ctx_session_stop() does not synchronize. */ 44 | 45 | /* At this point, it is safe to check and/or validate the table result... */ 46 | 47 | shmem_ctx_destroy(ctx); 48 | shmem_free(table); 49 | shmem_finalize(); 50 | return 0; 51 | } 52 | -------------------------------------------------------------------------------- /example_code/shmem_fence_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | int src = 99; 6 | long source[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; 7 | static long dest[10]; 8 | static int targ; 9 | shmem_init(); 10 | int mype = shmem_my_pe(); 11 | if (mype == 0) { 12 | shmem_put(dest, source, 10, 1); /* put1 */ 13 | shmem_put(dest, source, 10, 2); /* put2 */ 14 | shmem_fence(); 15 | shmem_put(&targ, &src, 1, 1); /* put3 */ 16 | shmem_put(&targ, &src, 1, 2); /* put4 */ 17 | } 18 | shmem_barrier_all(); /* sync sender and receiver */ 19 | printf("dest[0] on PE %d is %ld\n", mype, dest[0]); 20 | shmem_finalize(); 21 | return 0; 22 | } 23 | -------------------------------------------------------------------------------- /example_code/shmem_finalize_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static long x = 10101; 6 | long y = -1; 7 | 8 | shmem_init(); 9 | int mype = shmem_my_pe(); 10 | int npes = shmem_n_pes(); 11 | 12 | if (mype == 0) 13 | y = shmem_g(&x, npes - 1); 14 | 15 | printf("%d: y = %ld\n", mype, y); 16 | 17 | shmem_finalize(); 18 | return 0; 19 | } 20 | -------------------------------------------------------------------------------- /example_code/shmem_g_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | long y = -1; 6 | static long x = 10101; 7 | shmem_init(); 8 | int mype = shmem_my_pe(); 9 | int npes = shmem_n_pes(); 10 | if (mype == 0) 11 | y = shmem_g(&x, npes - 1); 12 | printf("%d: y = %ld\n", mype, y); 13 | shmem_finalize(); 14 | return 0; 15 | } 16 | -------------------------------------------------------------------------------- /example_code/shmem_global_exit_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | int main(void) { 6 | shmem_init(); 7 | int mype = shmem_my_pe(); 8 | if (mype == 0) { 9 | FILE *fp = fopen("input.txt", "r"); 10 | if (fp == NULL) { /* Input file required by program is not available */ 11 | shmem_global_exit(EXIT_FAILURE); 12 | } 13 | /* do something with the file */ 14 | fclose(fp); 15 | } 16 | shmem_finalize(); 17 | return 0; 18 | } 19 | -------------------------------------------------------------------------------- /example_code/shmem_init_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static int targ = 0; 6 | 7 | shmem_init(); 8 | int mype = shmem_my_pe(); 9 | int receiver = 1 % shmem_n_pes(); 10 | 11 | if (mype == 0) { 12 | int src = 33; 13 | shmem_put(&targ, &src, 1, receiver); 14 | } 15 | 16 | shmem_barrier_all(); /* Synchronizes sender and receiver */ 17 | 18 | if (mype == receiver) 19 | printf("PE %d targ=%d (expect 33)\n", mype, targ); 20 | 21 | shmem_finalize(); 22 | return 0; 23 | } 24 | -------------------------------------------------------------------------------- /example_code/shmem_iput_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | short source[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; 6 | static short dest[10]; 7 | shmem_init(); 8 | int mype = shmem_my_pe(); 9 | if (mype == 0) /* put 5 elements into dest on PE 1 */ 10 | shmem_iput(dest, source, 1, 2, 5, 1); 11 | shmem_barrier_all(); /* sync sender and receiver */ 12 | if (mype == 1) { 13 | printf("dest on PE %d is %hd %hd %hd %hd %hd\n", mype, dest[0], dest[1], dest[2], 14 | dest[3], dest[4]); 15 | } 16 | shmem_finalize(); 17 | return 0; 18 | } 19 | -------------------------------------------------------------------------------- /example_code/shmem_lock_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static long lock = 0; 6 | static int count = 0; 7 | shmem_init(); 8 | int mype = shmem_my_pe(); 9 | shmem_set_lock(&lock); 10 | int val = shmem_g(&count, 0); /* get count value on PE 0 */ 11 | printf("%d: count is %d\n", mype, val); 12 | val++; /* incrementing and updating count on PE 0 */ 13 | shmem_p(&count, val, 0); 14 | shmem_clear_lock(&lock); /* ensures count update completes before clearing the lock */ 15 | shmem_finalize(); 16 | return 0; 17 | } 18 | -------------------------------------------------------------------------------- /example_code/shmem_npes_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | shmem_init(); 6 | int mype = shmem_my_pe(); 7 | int npes = shmem_n_pes(); 8 | printf("I am #%d of %d PEs executing this program\n", mype, npes); 9 | shmem_finalize(); 10 | return 0; 11 | } 12 | -------------------------------------------------------------------------------- /example_code/shmem_p_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | int main(void) { 6 | const double e = 2.71828182; 7 | const double epsilon = 0.00000001; 8 | static double f = 3.1415927; 9 | shmem_init(); 10 | int mype = shmem_my_pe(); 11 | if (mype == 0) 12 | shmem_p(&f, e, 1); 13 | shmem_barrier_all(); 14 | if (mype == 1) 15 | printf("%s\n", (fabs(f - e) < epsilon) ? "OK" : "FAIL"); 16 | shmem_finalize(); 17 | return 0; 18 | } 19 | -------------------------------------------------------------------------------- /example_code/shmem_ptr_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static int dest[4]; 6 | shmem_init(); 7 | int mype = shmem_my_pe(); 8 | if (mype == 0) { /* initialize PE 1's dest array */ 9 | int *ptr = shmem_ptr(dest, 1); 10 | if (ptr == NULL) 11 | printf("can't use pointer to directly access PE 1's dest array\n"); 12 | else 13 | for (int i = 0; i < 4; i++) 14 | *ptr++ = i + 1; 15 | } 16 | shmem_barrier_all(); 17 | if (mype == 1) 18 | printf("PE 1 dest: %d, %d, %d, %d\n", dest[0], dest[1], dest[2], dest[3]); 19 | shmem_finalize(); 20 | return 0; 21 | } 22 | -------------------------------------------------------------------------------- /example_code/shmem_put_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | long source[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; 6 | static long dest[10]; 7 | shmem_init(); 8 | int mype = shmem_my_pe(); 9 | if (mype == 0) /* put 10 words into dest on PE 1 */ 10 | shmem_put(dest, source, 10, 1); 11 | shmem_barrier_all(); /* sync sender and receiver */ 12 | printf("dest[0] on PE %d is %ld\n", mype, dest[0]); 13 | shmem_finalize(); 14 | return 0; 15 | } 16 | -------------------------------------------------------------------------------- /example_code/shmem_put_signal_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | #include 5 | 6 | int main(void) { 7 | int i, err_count = 0; 8 | 9 | shmem_init(); 10 | 11 | size_t size = 2048; 12 | int mype = shmem_my_pe(); 13 | int npes = shmem_n_pes(); 14 | int pe = (mype + 1) % npes; 15 | uint64_t *message = malloc(size * sizeof(uint64_t)); 16 | static uint64_t sig_addr = 0; 17 | 18 | for (i = 0; i < size; i++) { 19 | message[i] = mype; 20 | } 21 | 22 | uint64_t *data = shmem_calloc(size, sizeof(uint64_t)); 23 | 24 | if (mype == 0) { 25 | shmem_put_signal(data, message, size, &sig_addr, 1, SHMEM_SIGNAL_SET, pe); 26 | } 27 | else { 28 | shmem_wait_until(&sig_addr, SHMEM_CMP_EQ, 1); 29 | shmem_put_signal(data, data, size, &sig_addr, 1, SHMEM_SIGNAL_SET, pe); 30 | } 31 | 32 | free(message); 33 | shmem_free(data); 34 | 35 | shmem_finalize(); 36 | return 0; 37 | } 38 | -------------------------------------------------------------------------------- /example_code/shmem_quiet_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static long dest[3]; 6 | static long source[3] = {1, 2, 3}; 7 | static int targ; 8 | static int src = 90; 9 | long x[3] = {0}; 10 | int y = 0; 11 | shmem_init(); 12 | int mype = shmem_my_pe(); 13 | if (mype == 0) { 14 | shmem_put(dest, source, 3, 1); /* put1 */ 15 | shmem_put(&targ, &src, 1, 2); /* put2 */ 16 | shmem_quiet(); 17 | shmem_get(x, dest, 3, 1); /* get array dest on PE 1 to local array x */ 18 | shmem_get(&y, &targ, 1, 2); /* get value targ on PE 2 to local variable y */ 19 | printf("x: { %ld, %ld, %ld }\n", x[0], x[1], x[2]); /* x: { 1, 2, 3 } */ 20 | printf("y: %d\n", y); /* y: 90 */ 21 | shmem_put(&targ, &src, 1, 1); /* put3 */ 22 | shmem_put(&targ, &src, 1, 2); /* put4 */ 23 | } 24 | shmem_finalize(); 25 | return 0; 26 | } 27 | -------------------------------------------------------------------------------- /example_code/shmem_reduce_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | #define NELEMS 32 6 | 7 | int main(void) { 8 | shmem_init(); 9 | int mype = shmem_my_pe(); 10 | int npes = shmem_n_pes(); 11 | 12 | int *values = shmem_malloc(NELEMS * sizeof(int)); 13 | 14 | unsigned char *value_is_maximal = shmem_malloc(NELEMS * sizeof(unsigned char)); 15 | unsigned char *value_is_maximal_all = shmem_malloc(NELEMS * sizeof(unsigned char)); 16 | 17 | static int maximal_values_count = 0; 18 | static int maximal_values_total; 19 | 20 | srand((unsigned)mype); 21 | 22 | for (int i = 0; i < NELEMS; i++) { 23 | values[i] = rand() % npes; 24 | 25 | /* Track and count instances of maximal values (i.e., values equal to (npes-1)) */ 26 | value_is_maximal[i] = (values[i] == (npes - 1)) ? 1 : 0; 27 | maximal_values_count += value_is_maximal[i]; 28 | } 29 | 30 | /* Wait for all PEs to initialize reductions arrays */ 31 | shmem_sync(SHMEM_TEAM_WORLD); 32 | 33 | shmem_or_reduce(SHMEM_TEAM_WORLD, value_is_maximal_all, value_is_maximal, NELEMS); 34 | shmem_sum_reduce(SHMEM_TEAM_WORLD, &maximal_values_total, &maximal_values_count, 1); 35 | 36 | if (mype == 0) { 37 | printf("Found %d maximal random numbers across all PEs.\n", maximal_values_total); 38 | printf("A maximal number occurred (at least once) at the following indices:\n"); 39 | for (int i = 0; i < NELEMS; i++) { 40 | if (value_is_maximal_all[i] == 1) { 41 | printf("%d ", i); 42 | } 43 | } 44 | printf("\n"); 45 | } 46 | 47 | shmem_finalize(); 48 | return 0; 49 | } 50 | -------------------------------------------------------------------------------- /example_code/shmem_scan_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int collect_at(shmem_team_t team, void *dest, const void *source, size_t nbytes, int who) { 4 | static size_t sym_nbytes; 5 | sym_nbytes = nbytes; 6 | shmem_team_sync(team); 7 | int rc = shmem_sum_exscan(team, &sym_nbytes, &sym_nbytes, 1); 8 | shmem_putmem((void *)((uintptr_t)dest + sym_nbytes), source, nbytes, who); 9 | shmem_quiet(); 10 | shmem_team_sync(team); 11 | return rc; 12 | } 13 | -------------------------------------------------------------------------------- /example_code/shmem_sync_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | static int x = 10101; 6 | 7 | shmem_team_t twos_team = SHMEM_TEAM_INVALID; 8 | shmem_team_t threes_team = SHMEM_TEAM_INVALID; 9 | shmem_team_config_t *config = NULL; 10 | 11 | shmem_init(); 12 | int mype = shmem_my_pe(); 13 | int npes = shmem_n_pes(); 14 | 15 | if (npes > 2) 16 | shmem_team_split_strided(SHMEM_TEAM_WORLD, 2, 2, (npes - 1) / 2, config, 0, &twos_team); 17 | 18 | if (npes > 3) 19 | shmem_team_split_strided(SHMEM_TEAM_WORLD, 3, 3, (npes - 1) / 3, config, 0, 20 | &threes_team); 21 | 22 | int mype_twos = shmem_team_my_pe(twos_team); 23 | int mype_threes = shmem_team_my_pe(threes_team); 24 | int npes_twos = shmem_team_n_pes(twos_team); 25 | int npes_threes = shmem_team_n_pes(threes_team); 26 | 27 | if (twos_team != SHMEM_TEAM_INVALID) { 28 | /* put the value 2 to the next team member in a circular fashion */ 29 | shmem_p( 30 | &x, 2, 31 | shmem_team_translate_pe(twos_team, (mype_twos + 1) % npes_twos, SHMEM_TEAM_WORLD)); 32 | shmem_quiet(); 33 | shmem_sync(twos_team); 34 | } 35 | 36 | shmem_sync(SHMEM_TEAM_WORLD); 37 | 38 | if (threes_team != SHMEM_TEAM_INVALID) { 39 | /* put the value 3 to the next team member in a circular fashion */ 40 | shmem_p(&x, 3, 41 | shmem_team_translate_pe(threes_team, (mype_threes + 1) % npes_threes, 42 | SHMEM_TEAM_WORLD)); 43 | shmem_quiet(); 44 | shmem_sync(threes_team); 45 | } 46 | 47 | if (mype && mype % 3 == 0) { 48 | if (x != 3) 49 | shmem_global_exit(3); 50 | } 51 | else if (mype && mype % 2 == 0) { 52 | if (x != 2) 53 | shmem_global_exit(2); 54 | } 55 | else if (x != 10101) { 56 | shmem_global_exit(1); 57 | } 58 | 59 | shmem_finalize(); 60 | return 0; 61 | } 62 | -------------------------------------------------------------------------------- /example_code/shmem_team_split_2D.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | /* Find x and y such that x * y == npes and abs(x - y) is minimized. */ 6 | static void find_xy_dims(int npes, int *x, int *y) { 7 | for(int divider = ceil(sqrt(npes)); divider >= 1; divider--) 8 | if (npes % divider == 0) { 9 | *x = divider; 10 | *y = npes / divider; 11 | return; 12 | } 13 | } 14 | 15 | /* Find x, y, and z such that x * y * z == npes and 16 | * abs(x - y) + abs(x - z) + abs(y - z) is minimized. */ 17 | static void find_xyz_dims(int npes, int *x, int *y, int *z) { 18 | *x = *y = *z = 1; 19 | for(int divider = ceil(cbrt(npes)); divider >= 1; divider--) 20 | if (npes % divider == 0) { 21 | *x = divider; 22 | find_xy_dims(npes / divider, y, z); 23 | return; 24 | } 25 | } 26 | 27 | int main(void) { 28 | int xdim, ydim, zdim; 29 | 30 | shmem_init(); 31 | int mype = shmem_my_pe(); 32 | int npes = shmem_n_pes(); 33 | 34 | find_xyz_dims(npes, &xdim, &ydim, &zdim); 35 | 36 | if (shmem_my_pe() == 0) printf("xdim = %d, ydim = %d, zdim = %d\n", xdim, ydim, zdim); 37 | 38 | shmem_team_t xteam, yzteam, yteam, zteam; 39 | 40 | shmem_team_split_2d(SHMEM_TEAM_WORLD, xdim, NULL, 0, &xteam, NULL, 0, &yzteam); 41 | // yzteam is immediately ready to be used in collectives 42 | shmem_team_split_2d(yzteam, ydim, NULL, 0, &yteam, NULL, 0, &zteam); 43 | 44 | // We don't need the yzteam anymore 45 | shmem_team_destroy(yzteam); 46 | 47 | int my_x = shmem_team_my_pe(xteam); 48 | int my_y = shmem_team_my_pe(yteam); 49 | int my_z = shmem_team_my_pe(zteam); 50 | 51 | for (int zdx = 0; zdx < zdim; zdx++) { 52 | for (int ydx = 0; ydx < ydim; ydx++) { 53 | for (int xdx = 0; xdx < xdim; xdx++) { 54 | if ((my_x == xdx) && (my_y == ydx) && (my_z == zdx)) { 55 | printf("(%d, %d, %d) is mype = %d\n", my_x, my_y, my_z, mype); 56 | } 57 | shmem_team_sync(SHMEM_TEAM_WORLD); 58 | } 59 | } 60 | } 61 | 62 | shmem_finalize(); 63 | return 0; 64 | } 65 | -------------------------------------------------------------------------------- /example_code/shmem_team_split_strided.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | shmem_team_t new_team; 6 | shmem_team_config_t *config; 7 | 8 | shmem_init(); 9 | config = NULL; 10 | int mype = shmem_my_pe(); 11 | int npes = shmem_n_pes(); 12 | 13 | shmem_team_split_strided(SHMEM_TEAM_WORLD, 0, 2, npes / 2, config, 0, &new_team); 14 | 15 | if (new_team != SHMEM_TEAM_INVALID) { 16 | int team_npes = shmem_team_n_pes(new_team); 17 | int team_mype = shmem_team_my_pe(new_team); 18 | 19 | if ((mype % 2 != 0) || (mype / 2 != team_mype) || (npes / 2 != team_npes)) { 20 | shmem_global_exit(1); 21 | } 22 | } 23 | 24 | shmem_finalize(); 25 | return 0; 26 | } 27 | -------------------------------------------------------------------------------- /example_code/shmem_team_translate_pe.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | shmem_init(); 6 | shmem_team_config_t *config = NULL; 7 | int mype = shmem_my_pe(); 8 | int npes = shmem_n_pes(); 9 | 10 | shmem_team_t new_team; 11 | shmem_team_split_strided(SHMEM_TEAM_WORLD, 0, 2, (npes + 1) / 2, config, 0, &new_team); 12 | 13 | if (new_team != SHMEM_TEAM_INVALID) { 14 | int team_mype = shmem_team_my_pe(new_team); 15 | int global_mype = shmem_team_translate_pe(new_team, team_mype, SHMEM_TEAM_WORLD); 16 | 17 | if (global_mype != mype) { 18 | shmem_global_exit(1); 19 | } 20 | } 21 | 22 | shmem_finalize(); 23 | return 0; 24 | } 25 | -------------------------------------------------------------------------------- /example_code/shmem_test_any_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main(void) { 5 | shmem_init(); 6 | int mype = shmem_my_pe(); 7 | int npes = shmem_n_pes(); 8 | 9 | int *flags = shmem_calloc(npes, sizeof(int)); 10 | int *status = calloc(npes, sizeof(int)); 11 | 12 | for (int i = 0; i < npes; i++) 13 | shmem_atomic_set(&flags[mype], 1, i); 14 | 15 | int ncompleted = 0; 16 | size_t completed_idx; 17 | 18 | while (ncompleted < npes) { 19 | completed_idx = shmem_test_any(flags, npes, status, SHMEM_CMP_EQ, 1); 20 | if (completed_idx != SIZE_MAX) { 21 | ncompleted++; 22 | status[completed_idx] = 1; 23 | } 24 | else { 25 | /* Overlap some computation here */ 26 | } 27 | } 28 | 29 | free(status); 30 | shmem_free(flags); 31 | shmem_finalize(); 32 | return 0; 33 | } 34 | -------------------------------------------------------------------------------- /example_code/shmem_test_example1.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int user_wait_any(long *ivar, int count, int cmp, long value) { 5 | int idx = 0; 6 | while (!shmem_test(&ivar[idx], cmp, value)) 7 | idx = (idx + 1) % count; 8 | return idx; 9 | } 10 | 11 | int main(void) { 12 | shmem_init(); 13 | const int mype = shmem_my_pe(); 14 | const int npes = shmem_n_pes(); 15 | 16 | long *wait_vars = shmem_calloc(npes, sizeof(long)); 17 | if (mype == 0) { 18 | int who = user_wait_any(wait_vars, npes, SHMEM_CMP_NE, 0); 19 | printf("PE %d observed first update from PE %d\n", mype, who); 20 | } 21 | else 22 | shmem_atomic_set(&wait_vars[mype], mype, 0); 23 | 24 | shmem_free(wait_vars); 25 | shmem_finalize(); 26 | return 0; 27 | } 28 | -------------------------------------------------------------------------------- /example_code/shmem_test_some_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | #define N 100 5 | 6 | int main(void) { 7 | int total_sum = 0; 8 | 9 | shmem_init(); 10 | int mype = shmem_my_pe(); 11 | int npes = shmem_n_pes(); 12 | 13 | int *my_data = malloc(N * sizeof(int)); 14 | int *all_data = shmem_malloc(N * npes * sizeof(int)); 15 | 16 | int *flags = shmem_calloc(npes, sizeof(int)); 17 | size_t *indices = calloc(npes, sizeof(size_t)); 18 | int *status = calloc(npes, sizeof(int)); 19 | 20 | for (int i = 0; i < N; i++) 21 | my_data[i] = mype * N + i; 22 | 23 | for (int i = 0; i < npes; i++) 24 | shmem_put_nbi(&all_data[mype * N], my_data, N, i); 25 | 26 | shmem_fence(); 27 | 28 | for (int i = 0; i < npes; i++) 29 | shmem_atomic_set(&flags[mype], 1, i); 30 | 31 | int ncompleted = 0; 32 | 33 | while (ncompleted < npes) { 34 | int ntested = shmem_test_some(flags, npes, indices, status, SHMEM_CMP_NE, 0); 35 | if (ntested > 0) { 36 | for (int i = 0; i < ntested; i++) { 37 | for (int j = 0; j < N; j++) { 38 | total_sum += all_data[indices[i] * N + j]; 39 | } 40 | status[indices[i]] = 1; 41 | } 42 | ncompleted += ntested; 43 | } 44 | else { 45 | /* Overlap some computation here */ 46 | } 47 | } 48 | 49 | /* check the result */ 50 | int M = N * npes - 1; 51 | if (total_sum != M * (M + 1) / 2) { 52 | shmem_global_exit(1); 53 | } 54 | 55 | shmem_finalize(); 56 | return 0; 57 | } 58 | -------------------------------------------------------------------------------- /example_code/shmem_wait_until_all.c: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int main(void) { 4 | shmem_init(); 5 | int mype = shmem_my_pe(); 6 | int npes = shmem_n_pes(); 7 | 8 | int *flags = shmem_calloc(npes, sizeof(int)); 9 | int *status = NULL; 10 | 11 | for (int i = 0; i < npes; i++) 12 | shmem_atomic_set(&flags[mype], 1, i); 13 | 14 | shmem_wait_until_all(flags, npes, status, SHMEM_CMP_EQ, 1); 15 | 16 | shmem_free(flags); 17 | shmem_finalize(); 18 | return 0; 19 | } 20 | -------------------------------------------------------------------------------- /example_code/shmem_wait_until_any_all2all_sum.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | #define N 100 5 | 6 | int main(void) { 7 | int total_sum = 0; 8 | 9 | shmem_init(); 10 | int mype = shmem_my_pe(); 11 | int npes = shmem_n_pes(); 12 | 13 | int *my_data = malloc(N * sizeof(int)); 14 | int *all_data = shmem_malloc(N * npes * sizeof(int)); 15 | 16 | int *flags = shmem_calloc(npes, sizeof(int)); 17 | int *status = calloc(npes, sizeof(int)); 18 | 19 | for (int i = 0; i < N; i++) 20 | my_data[i] = mype * N + i; 21 | 22 | for (int i = 0; i < npes; i++) 23 | shmem_put_nbi(&all_data[mype * N], my_data, N, i); 24 | 25 | shmem_fence(); 26 | 27 | for (int i = 0; i < npes; i++) 28 | shmem_atomic_set(&flags[mype], 1, i); 29 | 30 | for (int i = 0; i < npes; i++) { 31 | size_t completed_idx = shmem_wait_until_any(flags, npes, status, SHMEM_CMP_NE, 0); 32 | for (int j = 0; j < N; j++) { 33 | total_sum += all_data[completed_idx * N + j]; 34 | } 35 | status[completed_idx] = 1; 36 | } 37 | 38 | /* check the result */ 39 | int M = N * npes - 1; 40 | if (total_sum != M * (M + 1) / 2) { 41 | shmem_global_exit(1); 42 | } 43 | 44 | shmem_finalize(); 45 | return 0; 46 | } 47 | -------------------------------------------------------------------------------- /example_code/shmem_wait_until_any_vector.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | #define N 100 5 | 6 | int main(void) { 7 | int total_sum = 0; 8 | 9 | shmem_init(); 10 | int mype = shmem_my_pe(); 11 | int npes = shmem_n_pes(); 12 | 13 | int *ivars = shmem_calloc(npes, sizeof(int)); 14 | int *status = calloc(npes, sizeof(int)); 15 | int *cmp_values = malloc(npes * sizeof(int)); 16 | 17 | /* All odd PEs put 2 and all even PEs put 1 */ 18 | for (int i = 0; i < npes; i++) { 19 | shmem_atomic_set(&ivars[mype], mype % 2 + 1, i); 20 | 21 | /* Set cmp_values to the expected values coming from each PE */ 22 | cmp_values[i] = i % 2 + 1; 23 | } 24 | 25 | for (int i = 0; i < npes; i++) { 26 | size_t completed_idx = 27 | shmem_wait_until_any_vector(ivars, npes, status, SHMEM_CMP_EQ, cmp_values); 28 | status[completed_idx] = 1; 29 | total_sum += ivars[completed_idx]; 30 | } 31 | 32 | /* check the result */ 33 | int correct_result = npes + npes / 2; 34 | 35 | if (total_sum != correct_result) { 36 | shmem_global_exit(1); 37 | } 38 | 39 | shmem_finalize(); 40 | return 0; 41 | } 42 | -------------------------------------------------------------------------------- /example_code/shmem_wait_until_some_all2all_sum.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | #define N 100 5 | 6 | int main(void) { 7 | int total_sum = 0; 8 | 9 | shmem_init(); 10 | int mype = shmem_my_pe(); 11 | int npes = shmem_n_pes(); 12 | 13 | int *my_data = malloc(N * sizeof(int)); 14 | int *all_data = shmem_malloc(N * npes * sizeof(int)); 15 | 16 | int *flags = shmem_calloc(npes, sizeof(int)); 17 | size_t *indices = malloc(npes * sizeof(size_t)); 18 | int *status = calloc(npes, sizeof(int)); 19 | 20 | for (int i = 0; i < N; i++) 21 | my_data[i] = mype * N + i; 22 | 23 | for (int i = 0; i < npes; i++) 24 | shmem_put_nbi(&all_data[mype * N], my_data, N, i); 25 | 26 | shmem_fence(); 27 | 28 | for (int i = 0; i < npes; i++) 29 | shmem_atomic_set(&flags[mype], 1, i); 30 | 31 | size_t ncompleted; 32 | while ( 33 | (ncompleted = shmem_wait_until_some(flags, npes, indices, status, SHMEM_CMP_NE, 0))) { 34 | for (size_t i = 0; i < ncompleted; i++) { 35 | for (size_t j = 0; j < N; j++) { 36 | total_sum += all_data[indices[i] * N + j]; 37 | } 38 | status[indices[i]] = 1; 39 | } 40 | } 41 | 42 | /* check the result */ 43 | int M = N * npes - 1; 44 | if (total_sum != M * (M + 1) / 2) { 45 | shmem_global_exit(1); 46 | } 47 | 48 | shmem_finalize(); 49 | return 0; 50 | } 51 | -------------------------------------------------------------------------------- /example_code/writing_shmem_example.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | #define N 16 5 | 6 | int main(void) { 7 | short source[N]; 8 | static short dest[N]; 9 | static long lock = 0; 10 | shmem_init(); 11 | int mype = shmem_my_pe(); 12 | int npes = shmem_n_pes(); 13 | if (mype == 0) { 14 | /* initialize array */ 15 | for (int i = 0; i < N; i++) 16 | source[i] = i; 17 | /* local, not symmetric */ 18 | /* static makes it symmetric */ 19 | /* put "size" words into dest on each PE */ 20 | for (int i = 1; i < npes; i++) 21 | shmem_put(dest, source, N, i); 22 | } 23 | shmem_barrier_all(); /* sync sender and receiver */ 24 | if (mype != 0) { 25 | shmem_set_lock(&lock); 26 | printf("dest on PE %d is \t", mype); 27 | for (int i = 0; i < N; i++) 28 | printf("%hd \t", dest[i]); 29 | printf("\n"); 30 | shmem_clear_lock(&lock); 31 | } 32 | shmem_finalize(); 33 | return 0; 34 | } 35 | -------------------------------------------------------------------------------- /example_code/writing_shmem_example.output: -------------------------------------------------------------------------------- 1 | dest on PE 1 is 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 2 | dest on PE 2 is 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 3 | dest on PE 3 is 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 4 | -------------------------------------------------------------------------------- /figures/OpenSHMEM_Pound.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/OpenSHMEM_Pound.png -------------------------------------------------------------------------------- /figures/barrier.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/barrier.pdf -------------------------------------------------------------------------------- /figures/barrierall.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/barrierall.pdf -------------------------------------------------------------------------------- /figures/fence.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/fence.pdf -------------------------------------------------------------------------------- /figures/mem_model.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/mem_model.pdf -------------------------------------------------------------------------------- /figures/quiet.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/quiet.pdf -------------------------------------------------------------------------------- /figures/sync.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/sync.pdf -------------------------------------------------------------------------------- /figures/wait.graffle: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/wait.graffle -------------------------------------------------------------------------------- /figures/wait.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/wait.pdf -------------------------------------------------------------------------------- /figures/wait_v1_4.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openshmem-org/specification/3a8a05c002e15aa896374fc8b1f8e696ffcc939e/figures/wait_v1_4.pdf -------------------------------------------------------------------------------- /utils/packages.tex: -------------------------------------------------------------------------------- 1 | \usepackage[letterpaper,top=2.5cm,bottom=2.5cm,left=2.5cm,right=2.5cm]{geometry} 2 | \usepackage[T1]{fontenc} 3 | \usepackage[utf8]{inputenc} 4 | \usepackage{graphicx} 5 | \usepackage{multicol} 6 | \usepackage{multirow} 7 | \usepackage[normalem]{ulem} 8 | \usepackage{float} 9 | \usepackage[usenames,dvipsnames,table]{xcolor} 10 | \usepackage{amsmath} 11 | \usepackage{amsthm} 12 | \usepackage{amsfonts} 13 | \usepackage{xspace} 14 | \usepackage{xhfill} 15 | \usepackage{fancyhdr} 16 | \usepackage[nolist]{acronym} 17 | \usepackage{listings} 18 | % note sure after here 19 | \usepackage{makeidx} 20 | \usepackage[UKenglish]{isodate} 21 | \usepackage{ifthen} 22 | \usepackage{textcomp} 23 | \usepackage{alltt} 24 | \usepackage{ifpdf} 25 | \ifpdf 26 | \usepackage[pdftex, 27 | pagebackref=true, 28 | colorlinks=true, 29 | linkcolor=blue, 30 | unicode 31 | ]{hyperref} 32 | \else 33 | \usepackage[ps2pdf, 34 | pagebackref=true, 35 | colorlinks=true, 36 | linkcolor=blue, 37 | unicode 38 | ]{hyperref} 39 | \usepackage{pspicture} 40 | \fi 41 | \usepackage{sectsty} 42 | \usepackage{mathptmx} 43 | \usepackage[scaled=.90]{helvet} 44 | \usepackage{courier} 45 | \usepackage[titles]{tocloft} 46 | \usepackage{prettyref} 47 | \usepackage{mdwlist} 48 | \usepackage{enumitem} 49 | \usepackage{framed} 50 | \usepackage{pbox} 51 | \usepackage{draftcopy} 52 | \usepackage{draftwatermark} 53 | \usepackage{wrapfig} 54 | \usepackage{longtable} 55 | \usepackage{caption} 56 | \usepackage{subcaption} 57 | \usepackage{csquotes} 58 | \usepackage{tablefootnote} 59 | \usepackage[capitalize]{cleveref} 60 | --------------------------------------------------------------------------------