add shmem_space_malloc and shmem_space_free

content/environment_variables.tex

@@ -14,7 +14,7 @@
 
 \medskip{}
 
-\begin{longtable}{|p{0.260\textwidth}|p{0.145\textwidth}|p{0.50\textwidth}|}
+\begin{longtable}{|p{0.360\textwidth}|p{0.145\textwidth}|p{0.50\textwidth}|}
 \hline
 \textbf{Variable} & \textbf{Value} & \textbf{Description}
 \tabularnewline\hline
@@ -31,8 +31,17 @@
 %%
 \EnvVarDecl{SHMEM\_SYMMETRIC\_SIZE}
     & Non-negative integer or floating point value with an optional character
-    suffix
-    & Specifies the size (in bytes) of the symmetric heap memory per \ac{PE}.
+    suffiximport itertools
+
+mat = sum([1 for c in itertools.product([1,2,3,4,5,6],repeat=4) if (c[0] + c[1]) == (c[2] + c[3])])
+tot = 6 * 6 * 6 * 6
+
+print(tot, mat, mat/tot)
+
+    & Specifies the size (in bytes) of the symmetric heap memory per
+    \ac{PE}.
+    This applies to \LibHandleRef{SHMEM\_SPACE\_DEFAULT} and maintains
+    backward compatibility with existing OpenSHMEM applications.
     The resulting size is implementation-defined and must be at least as large as
     the integer ceiling of the product of the numeric prefix and the scaling
     factor. The allowed character suffixes for the scaling factor are as
@@ -56,6 +65,68 @@
       \FUNC{shmem\_init\_thread} or causing program termination.
     \tabularnewline\hline
 %%
+\EnvVarDecl{SHMEM\_CPU\_SYMMETRIC\_SIZE}
+    & Non-negative integer or floating point value with an optional character
+    suffiximport itertools
+
+mat = sum([1 for c in itertools.product([1,2,3,4,5,6],repeat=4) if (c[0] + c[1]) == (c[2] + c[3])])
+tot = 6 * 6 * 6 * 6
+
+print(tot, mat, mat/tot)
+
+    & Specifies the size (in bytes) of the CPU symmetric heap memory per \ac{PE}.
+    The resulting size is implementation-defined and must be at least as large as
+    the integer ceiling of the product of the numeric prefix and the scaling
+    factor. The allowed character suffixes for the scaling factor are as
+    follows:
+      \begin{itemize}
+        \item k or K multiplies by \(2^{10}\)  (kibibytes)
+        \item m or M multiplies by \(2^{20}\)  (mebibytes)
+        \item g or G multiplies by \(2^{30}\)  (gibibytes)
+        \item t or T multiplies by \(2^{40}\)  (tebibytes)
+      \end{itemize}
+    \tabularnewline\hline
+%%
+\EnvVarDecl{SHMEM\_GPU\_SYMMETRIC\_SIZE}
+    & Non-negative integer or floating point value with an optional character
+    suffiximport itertools
+
+mat = sum([1 for c in itertools.product([1,2,3,4,5,6],repeat=4) if (c[0] + c[1]) == (c[2] + c[3])])
+tot = 6 * 6 * 6 * 6
+
+print(tot, mat, mat/tot)
+
+    & Specifies the size (in bytes) of the GPU symmetric heap memory per \ac{PE}.
+    The resulting size is implementation-defined and must be at least as large as
+    the integer ceiling of the product of the numeric prefix and the scaling
+    factor. The allowed character suffixes for the scaling factor are as
+    follows:
+      \begin{itemize}
+        \item k or K multiplies by \(2^{10}\)  (kibibytes)
+        \item m or M multiplies by \(2^{20}\)  (mebibytes)
+        \item g or G multiplies by \(2^{30}\)  (gibibytes)
+        \item t or T multiplies by \(2^{40}\)  (tebibytes)
+      \end{itemize}
+    \tabularnewline\hline
+%%
+\EnvVarDecl{SHMEM\_ENABLE\_CPU\_SPACE}
+    & Any
+    & Enables CPU symmetric heap. When not set or empty, CPU symmetric
+    heap is disabled.
+    \tabularnewline\hline
+%%
+\EnvVarDecl{SHMEM\_ENABLE\_GPU\_SPACE}
+    & Any
+    & Enables GPU symmetric heap. When not set or empty, GPU symmetric
+    heap is disabled.
+    \tabularnewline\hline
+%%
+\EnvVarDecl{SHMEM\_DEFAULT\_SPACE}
+    & CPU or GPU
+    & Controls whether \LibHandleRef{SHMEM\_DEFAULT\_SPACE} alias to
+    \LibHandleRef{SHMEM\_SPACE\_CPU} or \LibHandleRef{SHMEM\_SPACE\_GPU}.
+    \tabularnewline\hline
+%%
 \EnvVarDecl{SHMEM\_DEBUG}
     & Any
     & Enable debugging messages

content/library_constants.tex

@@ -115,10 +115,13 @@
 for more detail about its use.
 \tabularnewline \hline
 %%
-\LibConstDecl{SHMEM\_MALLOC\_SIGNAL\_REMOTE} &
-The hint to the memory allocation routine which specifies that the allocated
-memory will be used for signal variables. See Section
-\ref{subsec:shmmallochint} for more detail about its use.
+\LibConstDecl{SHMEM\_SPACE\_INVALID} &
+A value corresponding to an invalid space.
+This value can be used to initialize or update space handles to indicate
+that they do not reference a valid space.
+When managed in this way, applications can use an equality comparison
+to test whether a given space handle references a valid space.
+See Section~\ref{sec:memory_management} for more detail about its use.
 \tabularnewline \hline
 %%
 \begin{DeprecateBlock}

content/library_handles.tex

@@ -21,6 +21,20 @@
 See Section~\ref{subsec:team} for more detail about its use.
 \tabularnewline \hline
 %%
+\LibHandleDecl{SHMEM\_TEAM\_CPU} &
+Handle of type \CTYPE{shmem\_team\_t} that corresponds to the 
+team that can access the CPU symmetric heap. It is available when
+\LibHandleRef{SHMEM\_SPACE\_CPU} is enabled.
+See Section~\ref{subsec:team} for more detail about its use.
+\tabularnewline \hline
+%%
+\LibHandleDecl{SHMEM\_TEAM\_GPU} &
+Handle of type \CTYPE{shmem\_team\_t} that corresponds to the 
+team that can access the GPU symmetric heap. It is available when
+\LibHandleRef{SHMEM\_SPACE\_GPU} is enabled.
+See Section~\ref{subsec:team} for more detail about its use.
+\tabularnewline \hline
+%%
 \LibHandleDecl{SHMEM\_TEAM\_SHARED} &
 Handle of type \CTYPE{shmem\_team\_t} that corresponds to a team of \acp{PE}
 that share a memory domain.  \LibHandleRef{SHMEM\_TEAM\_SHARED} refers to
@@ -41,4 +55,24 @@
 See Section~\ref{sec:ctx} for more detail about its use.
 \tabularnewline \hline
 %%
+\LibHandleDecl{SHMEM\_SPACE\_DEFAULT} &
+A memory space handle representing the default symmetric heap. This
+space aliases to either \LibHandleRef{SHMEM\_SPACE\_CPU} or\LibHandleRef{SHMEM\_SPACE\_GPU} based
+on implementation choice or user configuration via the
+\ENVVAR{SHMEM\_DEFAULT\_SPACE} environment variable. This space is
+used for memory allocated via shmem\_malloc.
+\tabularnewline \hline
+%%
+\LibHandleDecl{SHMEM\_SPACE\_GPU} &
+Handle of type \CTYPE{shmem\_space\_t} that corresponds to a symmetric
+heap in GPU (device) memory. If the GPU space is not available
+(e.g. disabled or not supported), this handle is set to \LibConstRef{SHMEM\_SPACE\_INVALID}.
+\tabularnewline \hline
+%%
+\LibHandleDecl{SHMEM\_SPACE\_CPU} &
+Handle of type \CTYPE{shmem\_space\_t} that corresponds to a symmetric
+heap in CPU (host) memory. If the CPU space is not available
+(e.g. disabled or not supported), this handle is set to \LibConstRef{SHMEM\_SPACE\_INVALID}.
+\tabularnewline \hline
+%%
 \end{longtable}

content/shmem_space_free.tex

@@ -0,0 +1,34 @@
+\apisummary{
+  Collectively deallocate symmetric memory in a specific space.
+}
+
+\begin{apidefinition}
+
+\begin{Csynopsis}
+void @\FuncDecl{shmem\_space\_free}@(shmem_space_t space, void *ptr);
+\end{Csynopsis}
+
+\begin{apiarguments}
+  \apiargument{IN}{space}{Space handle from which ptr was allocated.}
+  \apiargument{IN}{ptr}{Symmetric address of an object in the given space.}
+\end{apiarguments}
+
+\apidescription{
+  The \FUNC{shmem\_space\_free} routine is a collective operation on the
+  team associated with \VAR{space} that causes the block to which \VAR{ptr}
+  points to be deallocated, that is, made available for further
+  allocation.  If \VAR{ptr} is a null pointer, no action is performed;
+  otherwise, \FUNC{shmem\_space\_free} calls a function equivalent to barrier on entry.
+  It is the user's responsibility to ensure that no communication
+  operations involving the given memory block are pending on other
+  communication contexts prior to calling \FUNC{shmem\_space\_free}.
+
+  The values of the \VAR{space} and \VAR{ptr} arguments must be identical on all
+  \acp{PE}; otherwise, the behavior is undefined.
+}
+
+\apireturnvalues{
+  None.
+}
+
+\end{apidefinition}

content/shmem_space_malloc.tex

@@ -0,0 +1,41 @@
+\apisummary{
+  Collectively allocate symmetric memory in a specific space.
+}
+
+\begin{apidefinition}
+
+\begin{Csynopsis}
+void *@\FuncDecl{shmem\_space\_malloc}@(shmem_space_t space, size_t size);
+\end{Csynopsis}
+
+\begin{apiarguments}
+  \apiargument{IN}{space}{The space within which to allocate.}
+  \apiargument{IN}{size}{The size, in bytes, of a block to be
+    allocated from the space.}
+\end{apiarguments}
+
+
+\apidescription{
+  The \FUNC{shmem\_space\_malloc} routine is a collective operation on the
+  team associated with \VAR{space} and returns the symmetric address of a
+  block of at least \VAR{size} bytes, which shall be suitably aligned
+  so that it may be assigned to a pointer to any type of object.
+  This block is allocated from the specific symmetric heap identified
+  by \VAR{space}.
+  When \VAR{size} is zero, the \FUNC{shmem\_space\_malloc} routine performs
+  no action and returns a null pointer; otherwise,
+  \FUNC{shmem\_space\_malloc} calls a procedure that is semantically equivalent 
+  to \FUNC{shmem\_team\_sync} on exit. This ensures
+  that all \acp{PE} with access to the space participate
+  in the memory allocation, and that the object on other \acp{PE} can be used as soon as the local
+  \ac{PE} returns. 
+  The values of the \VAR{space} and \VAR{size} arguments must be identical on all
+  \acp{PE}; otherwise, the behavior is undefined.
+}
+
+\apireturnvalues{
+  The \FUNC{shmem\_space\_malloc} routine returns the symmetric address of
+  the allocated space; otherwise, it returns a null pointer.
+}
+
+\end{apidefinition}

main_spec.tex

@@ -118,6 +118,13 @@ \subsubsection{\textbf{SHMEM\_MALLOC\_WITH\_HINTS}}\label{subsec:shmmallochint}
 \subsubsection{\textbf{SHMEM\_CALLOC}}\label{subsec:shmem_calloc}
 \input{content/shmem_calloc.tex}
 
+\subsubsection{\textbf{SHMEM\_SPACE\_MALLOC}}\label{subsec:shmem_space_malloc}
+\input{content/shmem_space_malloc.tex}
+
+\subsubsection{\textbf{SHMEM\_SPACE\_FREE}}\label{subsec:shmem_space_free}
+\input{content/shmem_space_free.tex}
+
+
 
 
 \subsection{Team Management Routines}\label{subsec:team}