diff --git a/content/shmem_calloc.tex b/content/shmem_calloc.tex index fc19de40..f0241bed 100644 --- a/content/shmem_calloc.tex +++ b/content/shmem_calloc.tex @@ -1,5 +1,5 @@ \apisummary{ - Allocate a zeroed block of symmetric memory. + Collectively allocate a zeroed block of symmetric memory. } \begin{apidefinition} diff --git a/content/shmem_finalize.tex b/content/shmem_finalize.tex index 7e508f12..b9c0e48a 100644 --- a/content/shmem_finalize.tex +++ b/content/shmem_finalize.tex @@ -44,7 +44,7 @@ All processes that represent the \acp{PE} will still exist after the call to \FUNC{shmem\_finalize} returns, but they will no longer have access - to resources that have been released. + to \openshmem library resources that have been released. } \apireturnvalues{ diff --git a/content/shmem_global_exit.tex b/content/shmem_global_exit.tex index f3e49092..ced34b0c 100644 --- a/content/shmem_global_exit.tex +++ b/content/shmem_global_exit.tex @@ -48,7 +48,7 @@ terminate regardless of their current execution state. While I/O must be flushed for standard language I/O calls from \CorCpp, it is implementation dependent as to how I/O done by other means (e.g., third - party I/O libraries) is handled. Similarly, resources are released + party I/O libraries) are handled. Similarly, resources are released according to \CorCpp standard language requirements, but this may not include all resources allocated for the \openshmem program. However, a quality implementation will make a best effort to flush all I/O and clean diff --git a/content/shmem_init.tex b/content/shmem_init.tex index 6bfe2e1b..4929ecaf 100644 --- a/content/shmem_init.tex +++ b/content/shmem_init.tex @@ -16,9 +16,10 @@ \apidescription{ \FUNC{shmem\_init} allocates and initializes resources used by the \openshmem library. It is a collective operation that all \acp{PE} must call before any - other \openshmem routine may be called. At the end of the \openshmem program - which it initialized, the call to \FUNC{shmem\_init} must be matched with a - call to \FUNC{shmem\_finalize}. + other \openshmem routine may be called, except \FUNC{shmem\_query\_initialized} + which checks the current initialized state of the library. In the + \openshmem program which it initialized, each call to \FUNC{shmem\_init} must + be matched with a corresponding call to \FUNC{shmem\_finalize}. The \FUNC{shmem\_init} and \FUNC{shmem\_init\_thread} initialization routines may be called multiple times within an \openshmem program. A @@ -33,16 +34,18 @@ None. } +\begin{DeprecateBlock} \apinotes{ As of \openshmem[1.2], the use of \FUNC{start\_pes} has been deprecated and calls to it should be replaced with calls to \FUNC{shmem\_init}. While support for \FUNC{start\_pes} is still required in \openshmem libraries, users are encouraged to use \FUNC{shmem\_init}. An important difference between - \FUNC{shmem\_init} and \FUNC{start\_pes} is that multiple calls to - \FUNC{shmem\_init} within a program results in undefined behavior, while in the - case of \FUNC{start\_pes}, any subsequent calls to \FUNC{start\_pes} after the + \FUNC{shmem\_init} and \FUNC{start\_pes} is that every call to + \FUNC{shmem\_init} within a program must be matched with a call to \FUNC{shmem\_finalize}. + In the case of \FUNC{start\_pes}, any subsequent calls to \FUNC{start\_pes} after the first one results in a no-op. } +\end{DeprecateBlock} \begin{apiexamples} diff --git a/content/shmem_malloc.tex b/content/shmem_malloc.tex index 6b0b176f..142f902c 100644 --- a/content/shmem_malloc.tex +++ b/content/shmem_malloc.tex @@ -23,8 +23,10 @@ \FUNC{malloc}, which allocates from the private heap). When \VAR{size} is zero, the \FUNC{shmem\_malloc} routine performs no action and returns a null pointer; otherwise, - \FUNC{shmem\_malloc} calls a barrier on exit. - + \FUNC{shmem\_malloc} calls a procedure that is semantically equivalent + to \FUNC{shmem\_barrier\_all} on exit. This ensures that all \acp{PE} participate + in the memory allocation, and that the memory on other \acp{PE} can be used as soon as the local + \ac{PE} returns. The value of the \VAR{size} argument must be identical on all \acp{PE}; otherwise, the behavior is undefined. } diff --git a/content/shmem_malloc_hints.tex b/content/shmem_malloc_hints.tex index 0377dc4f..3b10e7bc 100644 --- a/content/shmem_malloc_hints.tex +++ b/content/shmem_malloc_hints.tex @@ -27,7 +27,7 @@ In addition to the \VAR{size} argument, the \VAR{hints} argument is provided by the user. The \VAR{hints} describes the expected manner in which the \openshmem program may use the allocated memory. - The valid usage hints are described in Table~\ref{usagehints}. Multiple hints may be requested by combining them with a bitwise \CONST{OR} operation. + The valid usage of hints are described in Table~\ref{usagehints}. Multiple hints may be requested by combining them with a bitwise \CONST{OR} operation. A zero option can be given if no options are requested. The information provided by the \VAR{hints} is used to optimize for performance by the implementation. @@ -37,14 +37,11 @@ The \FUNC{shmem\_malloc\_with\_hints} routine is provided so that multiple \acp{PE} in a program can allocate symmetric, remotely accessible memory blocks. When no action is performed, these - routines return without performing a barrier. Otherwise, the routine will call a procedure that is semantically equivalent to \FUNC{shmem\_barrier\_all} on exit. - This ensures that all \acp{PE} participate in the memory allocation, and that the memory on other - \acp{PE} can be used as soon as the local \ac{PE} returns. The implicit barrier performed by this routine will quiet the - default context. It is the user's responsibility to ensure that no communication operations involving the given memory block are pending on - other contexts prior to calling the \FUNC{shmem\_free} and \FUNC{shmem\_realloc} routines. - The user is also responsible for calling these routines with identical argument(s) on all + routines return without performing a barrier. Otherwise, the routine will call a procedure that is + semantically equivalent to \FUNC{shmem\_barrier\_all} on exit, similar to the behavior of \FUNC{shmem\_malloc}. + The user is responsible for calling this routine with identical argument(s) on all \acp{PE}; if differing \VAR{size}, or \VAR{hints} arguments are used, the behavior of the call - and any subsequent \openshmem calls is undefined. + is undefined. } \apireturnvalues{ diff --git a/content/shmem_ptr.tex b/content/shmem_ptr.tex index 9207ac96..fe1a3236 100644 --- a/content/shmem_ptr.tex +++ b/content/shmem_ptr.tex @@ -24,7 +24,8 @@ of an \openshmem routine that requires a symmetric address results in undefined behavior. - The \FUNC{shmem\_ptr} routine can provide an efficient means to accomplish + + The \FUNC{shmem\_ptr} routine can provide efficient means to accomplish communication, for example when a sequence of reads and writes to a data object on a remote \ac{PE} does not match the access pattern provided in an \openshmem data transfer routine like \FUNC{shmem\_put} or diff --git a/content/shmem_query_initialized.tex b/content/shmem_query_initialized.tex index b3729b7c..b93d9917 100644 --- a/content/shmem_query_initialized.tex +++ b/content/shmem_query_initialized.tex @@ -20,7 +20,7 @@ zero. This function may be called at any time, regardless of the thread safety - level of the \openshmem library. + level or the current initialized state of the \openshmem library. } \apireturnvalues{ diff --git a/content/shmem_team_ptr.tex b/content/shmem_team_ptr.tex index 340419b5..81deaa92 100644 --- a/content/shmem_team_ptr.tex +++ b/content/shmem_team_ptr.tex @@ -25,7 +25,7 @@ an \openshmem routine that requires a symmetric address results in undefined behavior. - The \FUNC{shmem\_team\_ptr} routine can provide an efficient means to accomplish + The \FUNC{shmem\_team\_ptr} routine can provide efficient means to accomplish communication, for example when a sequence of reads and writes to a data object on a remote \ac{PE} does not match the access pattern provided in an \openshmem data transfer routine like \FUNC{shmem\_put} or diff --git a/content/threads_intro.tex b/content/threads_intro.tex index 59f134d0..3aa329c6 100644 --- a/content/threads_intro.tex +++ b/content/threads_intro.tex @@ -30,7 +30,7 @@ \begin{enumerate} \item In the \CONST{SHMEM\_THREAD\_FUNNELED}, \CONST{SHMEM\_THREAD\_SERIALIZED}, and -\CONST{SHMEM\_THREAD\_MULTIPLE} thread levels, the \FUNC{shmem\_init} and +\CONST{SHMEM\_THREAD\_MULTIPLE} thread levels, the \FUNC{shmem\_init\_thread} and \FUNC{shmem\_finalize} calls must be invoked by the same thread. \item diff --git a/main_spec.tex b/main_spec.tex index cfc3f8ae..6c3935d6 100644 --- a/main_spec.tex +++ b/main_spec.tex @@ -41,8 +41,8 @@ \section{Environment Variables }\label{subsec:environment_variables} \section{OpenSHMEM Library \acs{API}}\label{sec:openshmem_library_api} \subsection{Library Setup, Exit, and Query Routines} -The library setup and query interfaces that initialize and monitor the parallel -environment of the \acp{PE}. +This section specifies the library setup, exit, and query interfaces that initialize, +finalize, and monitor the parallel environment of the \acp{PE}, respectively. \subsubsection{\textbf{SHMEM\_INIT}}\label{subsec:shmem_init} \input{content/shmem_init} @@ -56,6 +56,10 @@ \subsubsection{\textbf{SHMEM\_N\_PES}}\label{subsec:shmem_n_pes} \subsubsection{\textbf{SHMEM\_FINALIZE}}\label{subsec:shmem_finalize} \input{content/shmem_finalize} +\subsubsection{\textbf{SHMEM\_QUERY\_INITIALIZED}} +\label{subsec:shmem_query_initialized} +\input{content/shmem_query_initialized} + \subsubsection{\textbf{SHMEM\_GLOBAL\_EXIT}}\label{subsec:shmem_global_exit} \input{content/shmem_global_exit} @@ -92,11 +96,6 @@ \subsubsection{\textbf{SHMEM\_QUERY\_THREAD}} \label{subsec:shmem_query_thread} \input{content/shmem_query_thread} -\subsubsection{\textbf{SHMEM\_QUERY\_INITIALIZED}} -\label{subsec:shmem_query_initialized} -\input{content/shmem_query_initialized} - - \subsection{Memory Management Routines} \label{sec:memory_management} \input{content/memmgmt_intro.tex}