Init/Finalize Clarification

content/backmatter.tex

@@ -23,11 +23,9 @@ \section*{Incorporating \openshmem{} into Programs}\label{sec:writing_programs}
 \begin{itemize}
 \item Add the include file \HEADER{shmem.h} (for \Cstd) or \HEADER{shmem.fh} (for \Fortran).
 \item Add the initialization call \FUNC{shmem\_init}, (line 9).
-\item Use OpenSHMEM calls to query the the total number of PEs (line 10) and PE
+\item Use OpenSHMEM calls to query the total number of \acp{PE} (line 10) and \ac{PE}
     id (line 11).
-\item There is no explicit finalize call; either a return from \texttt{main()}
-    (line 13) or an explicit \texttt{exit()} acts as an implicit \openshmem
-    finalization.
+\item Add the finalization call \FUNC{shmem\_finalize}, (line 13).
 \item In \openshmem the order in which lines appear in the output is not fixed
     as \acp{PE} execute asynchronously in parallel.
 \end{itemize}
@@ -244,7 +242,7 @@ \section{\ac{MPI} Interoperability}
 
 Another important feature of these systems is that the
 \FUNC{shmem\_pe\_accessible} routine returns \CONST{TRUE} only if the remote
-\ac{PE} is a process running from the same executable file as the local PE,
+\ac{PE} is a process running from the same executable file as the local \ac{PE},
 indicating that full \openshmem support (static memory and symmetric heap) is
 available.  When using \openshmem routines within an \ac{MPI} program, the use
 of \ac{MPI} memory placement environment variables is required when using
@@ -336,6 +334,7 @@ \section{Overview}\label{subsec:dep_overview}
     \hline
     \CorCpp: \hyperref[subsec:start_pes]{\FUNC{start\_pes}} & 1.2 & Current & \hyperref[subsec:shmem_init]{\FUNC{shmem\_init}} \\ \hline
     \Fortran: \hyperref[subsec:start_pes]{\FUNC{START\_PES}} & 1.2 & Current & \hyperref[subsec:shmem_init]{\FUNC{SHMEM\_INIT}} \\ \hline
+    \hyperref[subsec:start_pes]{Implicit finalization} & 1.2 & Current & \hyperref[subsec:shmem_finalize]{\FUNC{shmem\_finalize}} \\ \hline
     \CorCpp: \FUNC{\_my\_pe} & 1.2 & Current & \hyperref[subsec:shmem_my_pe]{\FUNC{shmem\_my\_pe}} \\ \hline
     \CorCpp: \FUNC{\_num\_pes} & 1.2 & Current & \hyperref[subsec:shmem_n_pes]{\FUNC{shmem\_n\_pes}} \\ \hline
     \Fortran: \FUNC{MY\_PE} & 1.2 & Current & \hyperref[subsec:shmem_my_pe]{\FUNC{SHMEM\_MY\_PE}} \\ \hline
@@ -395,6 +394,11 @@ \subsection{\CorCpp: \_my\_pe, \_num\_pes, shmalloc, shfree, shrealloc, shmemali
 to normalize the \openshmem \ac{API} to use \shmemprefixLC{} as the standard
 prefix for all routines.
 
+\subsection{Implicit Finalization}
+Implicit finalization has been replaced with explicit finalization using the
+\FUNC{shmem\_finalize} routine.  Explicit finalization improves portability and
+also improves interoperability with profiling and debugging tools.
+
 \subsection{\Fortran: START\_PES, MY\_PE, NUM\_PES}
 The \Fortran routines \FUNC{START\_PES}, \FUNC{MY\_PE}, and \FUNC{NUM\_PES}
 were deprecated in order to minimize the API differences from the deprecation
@@ -471,6 +475,10 @@ \section{Version 1.4}
     routines are included in the Fortran language bindings.\\
     See Sections \ref{subsec:shmem_get} and \ref{subsec:shmem_get_nbi}.
 %
+\item Clarified that \FUNC{shmem\_init} must be matched with a call to
+    \FUNC{shmem\_finalize}.
+\\See Sections \ref{subsec:shmem_init} and \ref{subsec:shmem_finalize}.
+%
 \item Added the \VAR{SHMEM\_SYNC\_SIZE} constant.
 \\See Section \ref{subsec:library_constants}.
 %

content/execution_model.tex

@@ -6,14 +6,14 @@
 start by calling the initialization routine  \FUNC{shmem\_init}
 \footnote{\textbf{start\_pes} has been deprecated as of Specification 1.2}
 before using any of the other \openshmem library routines.  An \openshmem
-program finishes execution by returning from the main routine or when any PE
-calls \FUNC{shmem\_global\_exit}. When returning from main, \openshmem must
+program concludes its use of the \openshmem library when all \acp{PE} call
+\FUNC{shmem\_finalize}. An \openshmem program can also be terminated
+when any \ac{PE} calls \FUNC{shmem\_global\_exit}.
+During a call to \FUNC{shmem\_finalize}, the \openshmem library must
 complete all pending communication and release all the resources associated to
-the library using an implicit collective synchronization across PEs. The user
-has the option to call \FUNC{shmem\_finalize} (before returning from main) to
-complete all pending communication and release all the \openshmem library
-resources without terminating the program. Calling any \openshmem routine after
-\FUNC{shmem\_finalize} leads to undefined behavior.
+the library using an implicit collective synchronization across PEs.
+Calling any \openshmem routine after \FUNC{shmem\_finalize} leads to undefined
+behavior.
 
 The \acp{PE} of the \openshmem program are identified by unique integers.  The
 identifiers are integers assigned in a monotonically increasing manner from zero

content/shmem_finalize.tex

@@ -44,11 +44,7 @@
     \FUNC{shmem\_ptr}. This collective operation requires all \acp{PE} to
     participate in the call, not just a subset of the \acp{PE}. The
     non-\openshmem portion of a program may continue after a call to
-    \FUNC{shmem\_finalize} by all \acp{PE}. There is an implicit
-    \FUNC{shmem\_finalize} at the end of main, so that having an explicit call
-    to \FUNC{shmem\_finalize} is optional. However, an explicit
-    \FUNC{shmem\_finalize} may be required as an entry point for wrappers used
-    by profiling or other tools that need to perform their own finalization.
+    \FUNC{shmem\_finalize} by all \acp{PE}.
 }
 
 \begin{apiexamples}

content/shmem_init.tex

@@ -36,10 +36,8 @@
     As of \openshmem Specification 1.2 the use of \FUNC{start\_pes} has been
     deprecated and is replaced with \FUNC{shmem\_init}. While support for
     \FUNC{start\_pes} is still required in \openshmem libraries, users are
-    encouraged to use \FUNC{shmem\_init}. Replacing \FUNC{start\_pes} with
-    \FUNC{shmem\_init} in \openshmem programs with no further changes is possible;
-    there is an implicit \FUNC{shmem\_finalize} at the end of main.  However,
-    \FUNC{shmem\_init} differs slightly from \FUNC{start\_pes}: multiple calls to
+    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
     first one resulted in a no-op.

content/start_pes.tex

@@ -25,8 +25,13 @@
 
 \apidescription{   
      The \FUNC{start\_pes} routine initializes the \openshmem execution
-     environment.  An \openshmem program must call \FUNC{start\_pes} before
-     calling any other \openshmem routine.
+     environment.  An \openshmem program must call either \FUNC{start\_pes} or
+     \FUNC{shmem\_init} before calling any other \openshmem routine.  Unlike
+     \FUNC{shmem\_init}, \FUNC{start\_pes} does not require a call to
+     \FUNC{shmem\_finalize}.  Instead, the \openshmem library is implicitly
+     finalized when the program exits.  Implicit finalization is collective and
+     includes a global synchronization to ensure that all pending communication
+     is completed before resources are released.
 }
 
 \apireturnvalues{