Merge remote-tracking branch 'wrrobin/sec/setup_thread_mem' into tmp

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}

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{

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

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}
 

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.
 }

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{

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

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{

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

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

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}