You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Complete draft of PMIx v4 Standard
Includes a broad range of changes and updates that reorganize the document
into several new chapters, places attributes next to the functions that primarily
utilize them, adds a number of new APIs, deprecates and removes all
implementation-related attributes, and cleans up explanations.
Signed-off-by: Ralph Castain <[email protected]>
Signed-off-by: Joshua Hursey <[email protected]>
Copy file name to clipboardExpand all lines: Chap_API_Data_Mgmt.tex
+28-93Lines changed: 28 additions & 93 deletions
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ \chapter{Data Packing and Unpacking}
6
6
7
7
\ac{PMIx} intentionally does not include support for internode communications in the standard, instead relying on its host \ac{SMS} environment to transfer any needed data and/or requests between nodes. These operations frequently involve PMIx-defined public data structures that include binary data. Many \ac{HPC} clusters are homogeneous, and so transferring the structures can be done rather simply. However, greater effort is required in heterogeneous environments to ensure binary data is correctly transferred. \ac{PMIx} buffer manipulation functions are provided for this purpose via standardized interfaces to ease adoption.
8
8
9
-
%%%%%%%%%%%
9
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10
10
\section{Data Buffer Type}
11
11
\declarestruct{pmix_data_buffer_t}
12
12
@@ -38,24 +38,19 @@ \section{Data Buffer Type}
38
38
\cspecificend
39
39
40
40
41
-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
42
-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
41
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
42
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
43
43
\section{Support Macros}
44
44
\label{chap:datamgt:macros}
45
45
46
46
\ac{PMIx} provides a set of convenience macros for creating, initiating, and releasing data buffers.
47
47
48
48
%%%%%%%%%%%
49
-
\subsection{\code{PMIX_DATA_BUFFER_CREATE}}
49
+
\littleheader{\code{PMIX_DATA_BUFFER_CREATE}}
50
50
\declaremacro{PMIX_DATA_BUFFER_CREATE}
51
51
52
-
%%%%
53
-
\summary
54
-
55
-
Allocate memory for a \refstruct{pmix_data_buffer_t} object and initialize it
56
-
57
-
%%%%
58
-
\format
52
+
Allocate memory for a \refstruct{pmix_data_buffer_t} object and initialize it.
53
+
This macro uses \textit{calloc} to allocate memory for the buffer and initialize all fields in it
\argin{buffer}{Pointer to the \refstruct{pmix_data_buffer_t} whose data is to be released (handle)}
156
117
\end{arglist}
157
118
158
-
%%%%
159
-
\descr
160
-
161
-
Free's the data contained in a \refstruct{pmix_data_buffer_t} object
162
-
163
119
164
120
%%%%%%%%%%%
165
-
\subsection{\code{PMIX_DATA_BUFFER_LOAD}}
121
+
\littleheader{\code{PMIX_DATA_BUFFER_LOAD}}
166
122
\declaremacro{PMIX_DATA_BUFFER_LOAD}
167
123
168
-
%%%%
169
-
\summary
170
-
171
-
Load a blob into a \refstruct{pmix_data_buffer_t} object
172
-
173
-
%%%%
174
-
\format
124
+
Load a blob into a \refstruct{pmix_data_buffer_t} object.
125
+
Load the given data into the provided \refstruct{pmix_data_buffer_t} object, usually done in preparation for unpacking the provided data. Note that the data is \textit{not} copied into the buffer - thus, the blob must not be released until after operations on the buffer have completed.
\argin{size}{Number of bytes in the blob {\code{size_t}}}
187
138
\end{arglist}
188
139
189
-
%%%%
190
-
\descr
191
-
192
-
Load the given data into the provided \refstruct{pmix_data_buffer_t} object, usually done in preparation for unpacking the provided data. Note that the data is \textit{not} copied into the buffer - thus, the blob must not be released until after operations on the buffer have completed.
193
-
194
-
195
140
%%%%%%%%%%%
196
-
\subsection{\code{PMIX_DATA_BUFFER_UNLOAD}}
141
+
\littleheader{\code{PMIX_DATA_BUFFER_UNLOAD}}
197
142
\declaremacro{PMIX_DATA_BUFFER_UNLOAD}
198
143
199
-
%%%%
200
-
\summary
201
-
202
-
Unload the data from a \refstruct{pmix_data_buffer_t} object
203
-
204
-
%%%%
205
-
\format
144
+
Unload the data from a \refstruct{pmix_data_buffer_t} object.
145
+
Extract the data in a buffer, assigning the pointer to the data (and the number of bytes in the blob) to the provided variables, usually done to transmit the blob to a remote process for unpacking. The buffer's internal pointer will be set to NULL to protect the data upon buffer destruct or release - thus, the user is responsible for releasing the blob when done with it.
\argout{size}{Variable to be assigned the number of bytes in the blob {\code{size_t}}}
218
158
\end{arglist}
219
159
220
-
%%%%
221
-
\descr
222
160
223
-
Extract the data in a buffer, assigning the pointer to the data (and the number of bytes in the blob) to the provided variables, usually done to transmit the blob to a remote process for unpacking. The buffer's internal pointer will be set to NULL to protect the data upon buffer destruct or release - thus, the user is responsible for releasing the blob when done with it.
224
-
225
-
226
-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
227
-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
161
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
162
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
228
163
\section{General Routines}
229
164
\label{chap:data_mgmt:general}
230
165
231
166
The following routines are provided to support internode transfers in heterogeneous environments.
232
167
233
-
%%%%%%%%%%%
168
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
234
169
\subsection{\code{PMIx_Data_pack}}
235
170
\declareapi{PMIx_Data_pack}
236
171
237
172
%%%%
238
173
\summary
239
174
240
-
Pack one or more values of a specified type into a buffer, usually for transmission to another process
175
+
Pack one or more values of a specified type into a buffer, usually for transmission to another process.
The unpack function unpacks the next value (or values) of a specified type from the given buffer. The buffer must have already been initialized via an \refmacro{PMIX_DATA_BUFFER_CREATE} or \refmacro{PMIX_DATA_BUFFER_CONSTRUCT} call (and assumedly filled with some data) --- otherwise, the unpack_value function will return an error. Providing an unsupported type flag will likewise be reported as an error, as will specifying a data type that \textit{does not} match the type of the next item in the buffer. An attempt to read beyond the end of the stored data held in the buffer will also return an error.
347
282
348
-
NOTE: it is possible for the buffer to be corrupted and that \ac{PMIx} will \textit{think} there is a proper variable type at the beginning of an unpack region --- but that the value is bogus (e.g., just a byte field in a string array that so happens to have a value that matches the specified data type flag). Therefore, the data type error check is \textit{not} completely safe.
283
+
Note that it is possible for the buffer to be corrupted and that \ac{PMIx} will \textit{think} there is a proper variable type at the beginning of an unpack region --- but that the value is bogus (e.g., just a byte field in a string array that so happens to have a value that matches the specified data type flag). Therefore, the data type error check is \textit{not} completely safe.
349
284
350
285
Unpacking values is a "nondestructive" process --- i.e., the values are not removed from the buffer. It is therefore possible for the caller to re-unpack a value from the same buffer by resetting the unpack_ptr.
Since registered data types can be complex structures, the system needs some way to know how to copy the data from one location to another (e.g., for storage in the registry). This function, which can call other copy functions to build up complex data types, defines the method for making a copy of the specified data type.
Since registered data types can be complex structures, the system needs some way to know how to print them (i.e., convert them to a string representation). Primarily for debug purposes.
0 commit comments