Skip to content

Commit fc84155

Browse files
michael-beebemichael-beebe
authored
Merge pull request #1 from lstewart/larry-spaces
add shmem_space_malloc and shmem_space_free
2 parents 3a8a05c + 12d4eda commit fc84155

File tree

6 files changed

+197
-7
lines changed

6 files changed

+197
-7
lines changed

‎content/environment_variables.tex‎

Lines changed: 74 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414

1515
\medskip{}
1616

17-
\begin{longtable}{|p{0.260\textwidth}|p{0.145\textwidth}|p{0.50\textwidth}|}
17+
\begin{longtable}{|p{0.360\textwidth}|p{0.145\textwidth}|p{0.50\textwidth}|}
1818
\hline
1919
\textbf{Variable} & \textbf{Value} & \textbf{Description}
2020
\tabularnewline\hline
@@ -31,8 +31,17 @@
3131
%%
3232
\EnvVarDecl{SHMEM\_SYMMETRIC\_SIZE}
3333
& Non-negative integer or floating point value with an optional character
34-
suffix
35-
& Specifies the size (in bytes) of the symmetric heap memory per \ac{PE}.
34+
suffiximport itertools
35+
36+
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])])
37+
tot = 6 * 6 * 6 * 6
38+
39+
print(tot, mat, mat/tot)
40+
41+
& Specifies the size (in bytes) of the symmetric heap memory per
42+
\ac{PE}.
43+
This applies to \LibHandleRef{SHMEM\_SPACE\_DEFAULT} and maintains
44+
backward compatibility with existing OpenSHMEM applications.
3645
The resulting size is implementation-defined and must be at least as large as
3746
the integer ceiling of the product of the numeric prefix and the scaling
3847
factor. The allowed character suffixes for the scaling factor are as
@@ -56,6 +65,68 @@
5665
\FUNC{shmem\_init\_thread} or causing program termination.
5766
\tabularnewline\hline
5867
%%
68+
\EnvVarDecl{SHMEM\_CPU\_SYMMETRIC\_SIZE}
69+
& Non-negative integer or floating point value with an optional character
70+
suffiximport itertools
71+
72+
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])])
73+
tot = 6 * 6 * 6 * 6
74+
75+
print(tot, mat, mat/tot)
76+
77+
& Specifies the size (in bytes) of the CPU symmetric heap memory per \ac{PE}.
78+
The resulting size is implementation-defined and must be at least as large as
79+
the integer ceiling of the product of the numeric prefix and the scaling
80+
factor. The allowed character suffixes for the scaling factor are as
81+
follows:
82+
\begin{itemize}
83+
\item k or K multiplies by \(2^{10}\) (kibibytes)
84+
\item m or M multiplies by \(2^{20}\) (mebibytes)
85+
\item g or G multiplies by \(2^{30}\) (gibibytes)
86+
\item t or T multiplies by \(2^{40}\) (tebibytes)
87+
\end{itemize}
88+
\tabularnewline\hline
89+
%%
90+
\EnvVarDecl{SHMEM\_GPU\_SYMMETRIC\_SIZE}
91+
& Non-negative integer or floating point value with an optional character
92+
suffiximport itertools
93+
94+
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])])
95+
tot = 6 * 6 * 6 * 6
96+
97+
print(tot, mat, mat/tot)
98+
99+
& Specifies the size (in bytes) of the GPU symmetric heap memory per \ac{PE}.
100+
The resulting size is implementation-defined and must be at least as large as
101+
the integer ceiling of the product of the numeric prefix and the scaling
102+
factor. The allowed character suffixes for the scaling factor are as
103+
follows:
104+
\begin{itemize}
105+
\item k or K multiplies by \(2^{10}\) (kibibytes)
106+
\item m or M multiplies by \(2^{20}\) (mebibytes)
107+
\item g or G multiplies by \(2^{30}\) (gibibytes)
108+
\item t or T multiplies by \(2^{40}\) (tebibytes)
109+
\end{itemize}
110+
\tabularnewline\hline
111+
%%
112+
\EnvVarDecl{SHMEM\_ENABLE\_CPU\_SPACE}
113+
& Any
114+
& Enables CPU symmetric heap. When not set or empty, CPU symmetric
115+
heap is disabled.
116+
\tabularnewline\hline
117+
%%
118+
\EnvVarDecl{SHMEM\_ENABLE\_GPU\_SPACE}
119+
& Any
120+
& Enables GPU symmetric heap. When not set or empty, GPU symmetric
121+
heap is disabled.
122+
\tabularnewline\hline
123+
%%
124+
\EnvVarDecl{SHMEM\_DEFAULT\_SPACE}
125+
& CPU or GPU
126+
& Controls whether \LibHandleRef{SHMEM\_DEFAULT\_SPACE} alias to
127+
\LibHandleRef{SHMEM\_SPACE\_CPU} or \LibHandleRef{SHMEM\_SPACE\_GPU}.
128+
\tabularnewline\hline
129+
%%
59130
\EnvVarDecl{SHMEM\_DEBUG}
60131
& Any
61132
& Enable debugging messages

‎content/library_constants.tex‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -115,10 +115,13 @@
115115
for more detail about its use.
116116
\tabularnewline \hline
117117
%%
118-
\LibConstDecl{SHMEM\_MALLOC\_SIGNAL\_REMOTE} &
119-
The hint to the memory allocation routine which specifies that the allocated
120-
memory will be used for signal variables. See Section
121-
\ref{subsec:shmmallochint} for more detail about its use.
118+
\LibConstDecl{SHMEM\_SPACE\_INVALID} &
119+
A value corresponding to an invalid space.
120+
This value can be used to initialize or update space handles to indicate
121+
that they do not reference a valid space.
122+
When managed in this way, applications can use an equality comparison
123+
to test whether a given space handle references a valid space.
124+
See Section~\ref{sec:memory_management} for more detail about its use.
122125
\tabularnewline \hline
123126
%%
124127
\begin{DeprecateBlock}

‎content/library_handles.tex‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,20 @@
2121
See Section~\ref{subsec:team} for more detail about its use.
2222
\tabularnewline \hline
2323
%%
24+
\LibHandleDecl{SHMEM\_TEAM\_CPU} &
25+
Handle of type \CTYPE{shmem\_team\_t} that corresponds to the
26+
team that can access the CPU symmetric heap. It is available when
27+
\LibHandleRef{SHMEM\_SPACE\_CPU} is enabled.
28+
See Section~\ref{subsec:team} for more detail about its use.
29+
\tabularnewline \hline
30+
%%
31+
\LibHandleDecl{SHMEM\_TEAM\_GPU} &
32+
Handle of type \CTYPE{shmem\_team\_t} that corresponds to the
33+
team that can access the GPU symmetric heap. It is available when
34+
\LibHandleRef{SHMEM\_SPACE\_GPU} is enabled.
35+
See Section~\ref{subsec:team} for more detail about its use.
36+
\tabularnewline \hline
37+
%%
2438
\LibHandleDecl{SHMEM\_TEAM\_SHARED} &
2539
Handle of type \CTYPE{shmem\_team\_t} that corresponds to a team of \acp{PE}
2640
that share a memory domain. \LibHandleRef{SHMEM\_TEAM\_SHARED} refers to
@@ -41,4 +55,24 @@
4155
See Section~\ref{sec:ctx} for more detail about its use.
4256
\tabularnewline \hline
4357
%%
58+
\LibHandleDecl{SHMEM\_SPACE\_DEFAULT} &
59+
A memory space handle representing the default symmetric heap. This
60+
space aliases to either \LibHandleRef{SHMEM\_SPACE\_CPU} or\LibHandleRef{SHMEM\_SPACE\_GPU} based
61+
on implementation choice or user configuration via the
62+
\ENVVAR{SHMEM\_DEFAULT\_SPACE} environment variable. This space is
63+
used for memory allocated via shmem\_malloc.
64+
\tabularnewline \hline
65+
%%
66+
\LibHandleDecl{SHMEM\_SPACE\_GPU} &
67+
Handle of type \CTYPE{shmem\_space\_t} that corresponds to a symmetric
68+
heap in GPU (device) memory. If the GPU space is not available
69+
(e.g. disabled or not supported), this handle is set to \LibConstRef{SHMEM\_SPACE\_INVALID}.
70+
\tabularnewline \hline
71+
%%
72+
\LibHandleDecl{SHMEM\_SPACE\_CPU} &
73+
Handle of type \CTYPE{shmem\_space\_t} that corresponds to a symmetric
74+
heap in CPU (host) memory. If the CPU space is not available
75+
(e.g. disabled or not supported), this handle is set to \LibConstRef{SHMEM\_SPACE\_INVALID}.
76+
\tabularnewline \hline
77+
%%
4478
\end{longtable}

‎content/shmem_space_free.tex‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
\apisummary{
2+
Collectively deallocate symmetric memory in a specific space.
3+
}
4+
5+
\begin{apidefinition}
6+
7+
\begin{Csynopsis}
8+
void @\FuncDecl{shmem\_space\_free}@(shmem_space_t space, void *ptr);
9+
\end{Csynopsis}
10+
11+
\begin{apiarguments}
12+
\apiargument{IN}{space}{Space handle from which ptr was allocated.}
13+
\apiargument{IN}{ptr}{Symmetric address of an object in the given space.}
14+
\end{apiarguments}
15+
16+
\apidescription{
17+
The \FUNC{shmem\_space\_free} routine is a collective operation on the
18+
team associated with \VAR{space} that causes the block to which \VAR{ptr}
19+
points to be deallocated, that is, made available for further
20+
allocation. If \VAR{ptr} is a null pointer, no action is performed;
21+
otherwise, \FUNC{shmem\_space\_free} calls a function equivalent to barrier on entry.
22+
It is the user's responsibility to ensure that no communication
23+
operations involving the given memory block are pending on other
24+
communication contexts prior to calling \FUNC{shmem\_space\_free}.
25+
26+
The values of the \VAR{space} and \VAR{ptr} arguments must be identical on all
27+
\acp{PE}; otherwise, the behavior is undefined.
28+
}
29+
30+
\apireturnvalues{
31+
None.
32+
}
33+
34+
\end{apidefinition}

‎content/shmem_space_malloc.tex‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
\apisummary{
2+
Collectively allocate symmetric memory in a specific space.
3+
}
4+
5+
\begin{apidefinition}
6+
7+
\begin{Csynopsis}
8+
void *@\FuncDecl{shmem\_space\_malloc}@(shmem_space_t space, size_t size);
9+
\end{Csynopsis}
10+
11+
\begin{apiarguments}
12+
\apiargument{IN}{space}{The space within which to allocate.}
13+
\apiargument{IN}{size}{The size, in bytes, of a block to be
14+
allocated from the space.}
15+
\end{apiarguments}
16+
17+
18+
\apidescription{
19+
The \FUNC{shmem\_space\_malloc} routine is a collective operation on the
20+
team associated with \VAR{space} and returns the symmetric address of a
21+
block of at least \VAR{size} bytes, which shall be suitably aligned
22+
so that it may be assigned to a pointer to any type of object.
23+
This block is allocated from the specific symmetric heap identified
24+
by \VAR{space}.
25+
When \VAR{size} is zero, the \FUNC{shmem\_space\_malloc} routine performs
26+
no action and returns a null pointer; otherwise,
27+
\FUNC{shmem\_space\_malloc} calls a procedure that is semantically equivalent
28+
to \FUNC{shmem\_team\_sync} on exit. This ensures
29+
that all \acp{PE} with access to the space participate
30+
in the memory allocation, and that the object on other \acp{PE} can be used as soon as the local
31+
\ac{PE} returns.
32+
The values of the \VAR{space} and \VAR{size} arguments must be identical on all
33+
\acp{PE}; otherwise, the behavior is undefined.
34+
}
35+
36+
\apireturnvalues{
37+
The \FUNC{shmem\_space\_malloc} routine returns the symmetric address of
38+
the allocated space; otherwise, it returns a null pointer.
39+
}
40+
41+
\end{apidefinition}

‎main_spec.tex‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,13 @@ \subsubsection{\textbf{SHMEM\_MALLOC\_WITH\_HINTS}}\label{subsec:shmmallochint}
118118
\subsubsection{\textbf{SHMEM\_CALLOC}}\label{subsec:shmem_calloc}
119119
\input{content/shmem_calloc.tex}
120120

121+
\subsubsection{\textbf{SHMEM\_SPACE\_MALLOC}}\label{subsec:shmem_space_malloc}
122+
\input{content/shmem_space_malloc.tex}
123+
124+
\subsubsection{\textbf{SHMEM\_SPACE\_FREE}}\label{subsec:shmem_space_free}
125+
\input{content/shmem_space_free.tex}
126+
127+
121128

122129

123130
\subsection{Team Management Routines}\label{subsec:team}

0 commit comments

Comments
 (0)