Merge pull request #259 from manjugv/topic/shmem_malloc_hints

Adding shmem_malloc_with_hints interface

Author: jdinan

content/shmem_malloc_hints.tex

@@ -0,0 +1,90 @@
+
+\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\_hints} routine, like \FUNC{shmem\_malloc}, 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 the \VAR{size} is zero, 
+    the \FUNC{shmem\_malloc\_with\_hints} routine performs no action and returns a null pointer. 
+    
+    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.
+	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. 
+    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\_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 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{hints} arguments are used, the behavior of the call
+    and any subsequent \openshmem calls is undefined.
+}
+
+\apireturnvalues{
+    The \FUNC{shmem\_malloc\_with\_hints} routine returns a pointer to the allocated space;
+    otherwise, it returns a null pointer.
+}
+
+	\begin{longtable}{|p{0.45\textwidth}|p{0.5\textwidth}|}
+	\hline
+	\textbf{Hints} & \textbf{Usage hint}
+	\tabularnewline \hline
+	\endhead
+	%%
+	\newline
+	\CONST{0} &
+	\newline
+	Behavior same as \FUNC{shmem\_malloc}
+	\tabularnewline \hline
+	
+		
+	\LibConstDecl{SHMEM\_HINT\_ATOMICS\_REMOTE} &
+	\newline 
+	Memory used for \VAR{atomic} operations
+	\tabularnewline \hline
+	
+	\LibConstDecl{SHMEM\_HINT\_SIGNAL} &
+	\newline
+	Memory used for \VAR{signal} operations
+	\tabularnewline \hline
+
+	\TableCaptionRef{Memory usage hints}
+        \label{usagehints}
+    \end{longtable}
+
+\apinotes{
+		The \openshmem programs should allocate memory with
+		\CONST{SHMEM\_HINT\_ATOMICS\_REMOTE}, when the majority of
+		operations performed on this memory are atomic operations, and origin
+		and target \ac{PE} of the atomic operations do not share a memory domain
+		.i.e., symmetric objects on the target \ac{PE} is not accessible using
+		load/store operations from the origin \ac{PE} or vice versa.
+}
+\end{apidefinition}
+\newpage

main_spec.tex

@@ -100,6 +100,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}