Adding shmem_malloc_with_hints interface

content/shmem_malloc_hints.tex

@@ -0,0 +1,97 @@
+
+\apisummary{
+    Collective memory allocation routine with support for providing hints.
+}
+
+\begin{apidefinition}
+
+\begin{Csynopsis}
+void *@\FuncDecl{shmem\_malloc\_with\_hints}@(size_t size, long hints);
+\end{Csynopsis}
+
+\begin{apiarguments}
+    \apiargument{IN}{size}{The size, in bytes, of a block to be
+        allocated from the symmetric heap. This argument is of type \CTYPE{size\_t}}
+    \apiargument{IN}{hints}{A bit array of hints provided by the user to the implementation}
+\end{apiarguments}
+
+
+\apidescription{
+
+    The \FUNC{shmem\_malloc\_with\_hint} like \FUNC{shmem\_malloc} routine returns a pointer to 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 space is allocated from
+    the symmetric heap (similar to \FUNC{shmem\_malloc}).  When \VAR{size} is zero, 
+    the \FUNC{shmem\_malloc\_with\_hint} routine performs no action and returns a null pointer. 
+
+    In addition to the \VAR{size} argument, the \VAR{hint} argument is provided by the user. 
+    The \VAR{hint} 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 are expressed as \CONST{OR} of \VAR{hints}.
+
+    The information provided by the \VAR{hint} is used to optimize for performance by the implementation. 
+    If the implementation cannot optimize, the behavior is same as \FUNC{shmem\_malloc}.
+    If more than one hint is provided, the implementation will make the best effort to use one or more hints 
+    to optimize performance. 
+
+    The \FUNC{shmem\_malloc\_with\_hint} 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 barrier 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
+    \acp{PE}; if differing \VAR{size}, or \VAR{hint} arguments are used, the behavior of the call
+    and any subsequent \openshmem calls is undefined.
+}
+
+\apireturnvalues{
+    The \FUNC{shmem\_malloc\_with\_hint} routine returns a pointer to the allocated space;
+    otherwise, it returns a null pointer.
+}
+
+\apinotes{ 
+}
+
+\apiimpnotes{
+}
+	\begin{longtable}{|p{0.45\textwidth}|p{0.5\textwidth}|}
+	\hline
+	\textbf{Hints} & \textbf{Usage hint}
+	\tabularnewline \hline
+	\endhead
+	%%
+	\LibConstDecl{SHMEM\_HINT\_NONE} &
+	Behavior same as shmem\_malloc
+	\tabularnewline \hline
+
+	\LibConstDecl{SHMEM\_HINT\_LOW\_LAT\_MEM} &
+	Allocate memory on low-latency storage	
+	\tabularnewline \hline
+
+	\LibConstDecl{SHMEM\_HINT\_HIGH\_BW\_MEM} &
+	Allocate memory on high-bandwidth storage	
+	\tabularnewline \hline
+
+	\LibConstDecl{SHMEM\_HINT\_PSYNC} &
+	Memory used as \CONST{PSYNC} array
+	\tabularnewline \hline
+
+	\LibConstDecl{SHMEM\_HINT\_PWORK} &
+	Memory used as \CONST{PWORK} array
+	\tabularnewline \hline
+
+	\LibConstDecl{SHMEM\_HINT\_ATOMICS} &
+	Memory used for \VAR{Atomic} operations
+	\tabularnewline \hline
+
+	\LibConstDecl{SHMEM\_HINT\_SIGNAL} &
+	Memory used for \VAR{signal} operations
+	\tabularnewline \hline
+
+	\TableCaptionRef{Memory usage hints}
+        \label{usagehints}
+    \end{longtable}
+
+\end{apidefinition}
+\newpage

main_spec.tex

@@ -103,6 +103,10 @@ \subsection{Memory Management Routines}
 \subsubsection{\textbf{SHMEM\_MALLOC, SHMEM\_FREE, SHMEM\_REALLOC, SHMEM\_ALIGN}}\label{subsec:shfree}
 \input{content/shmem_malloc.tex}
 
+\newpage
+\subsubsection{\textbf{SHMEM\_MALLOC\_WITH\_HINTS}}\label{subsec:shmmallochint}
+\input{content/shmem_malloc_hints.tex}
+
 \subsubsection{\textbf{SHMEM\_CALLOC}}\label{subsec:shmem_calloc}
 \input{content/shmem_calloc.tex}