Use Cases Chapter

Chap_API_Data_Mgmt.tex

@@ -12,30 +12,27 @@ \section{Data Buffer Type}
 
 The \refstruct{pmix_data_buffer_t} structure describes a data buffer used for packing and unpacking.
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-typedef struct pmix_data_buffer \{
-    /** Start of my memory */
-    char *base_ptr;
-    /** Where the next data will be packed to
-        (within the allocated memory starting
-        at base_ptr) */
-    char *pack_ptr;
-    /** Where the next data will be unpacked
-        from (within the allocated memory
-        starting as base_ptr) */
-    char *unpack_ptr;
-    /** Number of bytes allocated (starting
-        at base_ptr) */
-    size_t bytes_allocated;
-    /** Number of bytes used by the buffer
-        (i.e., amount of data -- including
-        overhead -- packed in the buffer) */
-    size_t bytes_used;
+\copySignature{pmix_data_buffer_t}{2.0}{
+typedef struct pmix_data_buffer \{ \\
+\hspace*{4\sigspace}/** Start of my memory */ \\
+\hspace*{4\sigspace}char *base_ptr; \\
+\hspace*{4\sigspace}/** Where the next data will be packed to \\
+\hspace*{8\sigspace}(within the allocated memory starting \\
+\hspace*{8\sigspace}at base_ptr) */ \\
+\hspace*{4\sigspace}char *pack_ptr; \\
+\hspace*{4\sigspace}/** Where the next data will be unpacked \\
+\hspace*{8\sigspace}from (within the allocated memory \\
+\hspace*{8\sigspace}starting as base_ptr) */ \\
+\hspace*{4\sigspace}char *unpack_ptr; \\
+\hspace*{4\sigspace}/** Number of bytes allocated (starting \\
+\hspace*{8\sigspace}at base_ptr) */ \\
+\hspace*{4\sigspace}size_t bytes_allocated; \\
+\hspace*{4\sigspace}/** Number of bytes used by the buffer \\
+\hspace*{8\sigspace}(i.e., amount of data -- including \\
+\hspace*{8\sigspace}overhead -- packed in the buffer) */ \\
+\hspace*{4\sigspace}size_t bytes_used; \\
 \} pmix_data_buffer_t;
-\end{codepar}
-\cspecificend
+}
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -52,12 +49,9 @@ \section{Support Macros}
 Allocate memory for a \refstruct{pmix_data_buffer_t} object and initialize it.
 This macro uses \textit{calloc} to allocate memory for the buffer and initialize all fields in it
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
+\copySignature{PMIX_DATA_BUFFER_CREATE}{2.0}{
 PMIX_DATA_BUFFER_CREATE(buffer);
-\end{codepar}
-\cspecificend
+}
 
 \begin{arglist}
 \argout{buffer}{Variable to be assigned the pointer to the allocated \refstruct{pmix_data_buffer_t} (handle)}
@@ -70,12 +64,9 @@ \section{Support Macros}
 Free a \refstruct{pmix_data_buffer_t} object and the data it contains.
 Free's the data contained in the buffer, and then free's the buffer itself
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
+\copySignature{PMIX_DATA_BUFFER_RELEASE}{2.0}{
 PMIX_DATA_BUFFER_RELEASE(buffer);
-\end{codepar}
-\cspecificend
+}
 
 \begin{arglist}
 \argin{buffer}{Pointer to the \refstruct{pmix_data_buffer_t} to be released (handle)}
@@ -88,12 +79,9 @@ \section{Support Macros}
 
 Initialize a statically declared \refstruct{pmix_data_buffer_t} object.
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
+\copySignature{PMIX_DATA_BUFFER_CONSTRUCT}{2.0}{
 PMIX_DATA_BUFFER_CONSTRUCT(buffer);
-\end{codepar}
-\cspecificend
+}
 
 \begin{arglist}
 \argin{buffer}{Pointer to the allocated \refstruct{pmix_data_buffer_t} that is to be initialized (handle)}
@@ -105,12 +93,9 @@ \section{Support Macros}
 
 Release the data contained in a \refstruct{pmix_data_buffer_t} object.
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
+\copySignature{PMIX_DATA_BUFFER_DESTRUCT}{2.0}{
 PMIX_DATA_BUFFER_DESTRUCT(buffer);
-\end{codepar}
-\cspecificend
+}
 
 \begin{arglist}
 \argin{buffer}{Pointer to the \refstruct{pmix_data_buffer_t} whose data is to be released (handle)}
@@ -124,12 +109,9 @@ \section{Support Macros}
 Load a blob into a \refstruct{pmix_data_buffer_t} object.
 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.
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
+\copySignature{PMIX_DATA_BUFFER_LOAD}{2.0}{
 PMIX_DATA_BUFFER_LOAD(buffer, data, size);
-\end{codepar}
-\cspecificend
+}
 
 \begin{arglist}
 \argin{buffer}{Pointer to a pre-allocated \refstruct{pmix_data_buffer_t} (handle)}
@@ -144,12 +126,9 @@ \section{Support Macros}
 Unload the data from a \refstruct{pmix_data_buffer_t} object.
 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.
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
+\copySignature{PMIX_DATA_BUFFER_UNLOAD}{2.0}{
 PMIX_DATA_BUFFER_UNLOAD(buffer, data, size);
-\end{codepar}
-\cspecificend
+}
 
 \begin{arglist}
 \argin{buffer}{Pointer to the \refstruct{pmix_data_buffer_t} whose data is to be extracted (handle)}
@@ -177,16 +156,13 @@ \subsection{\code{PMIx_Data_pack}}
 %%%%
 \format
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-pmix_status_t
-PMIx_Data_pack(const pmix_proc_t *target,
-               pmix_data_buffer_t *buffer,
-               void *src, int32_t num_vals,
-               pmix_data_type_t type);
-\end{codepar}
-\cspecificend
+\copySignature{PMIx_Data_pack}{2.0}{
+pmix_status_t \\
+PMIx_Data_pack(const pmix_proc_t *target, \\
+\hspace*{15\sigspace}pmix_data_buffer_t *buffer, \\
+\hspace*{15\sigspace}void *src, int32_t num_vals, \\
+\hspace*{15\sigspace}pmix_data_type_t type);
+}
 
 \begin{arglist}
 \argin{target}{Pointer to a \refstruct{pmix_proc_t} containing the nspace/rank of the process that will be unpacking the final buffer. A NULL value may be used to indicate that the target is based on the same \ac{PMIx} version as the caller. Note that only the target's nspace is relevant. (handle)}
@@ -244,17 +220,14 @@ \subsection{\code{PMIx_Data_unpack}}
 %%%%
 \format
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-pmix_status_t
-PMIx_Data_unpack(const pmix_proc_t *source,
-                 pmix_data_buffer_t *buffer, void *dest,
-                 int32_t *max_num_values,
-                 pmix_data_type_t type);
+\copySignature{PMIx_Data_unpack}{2.0}{
+pmix_status_t \\
+PMIx_Data_unpack(const pmix_proc_t *source, \\
+\hspace*{17\sigspace}pmix_data_buffer_t *buffer, void *dest, \\
+\hspace*{17\sigspace}int32_t *max_num_values, \\
+\hspace*{17\sigspace}pmix_data_type_t type); \\
 
-\end{codepar}
-\cspecificend
+}
 
 
 \begin{arglist}
@@ -309,14 +282,11 @@ \subsection{\code{PMIx_Data_copy}}
 %%%%
 \format
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-pmix_status_t
-PMIx_Data_copy(void **dest, void *src,
-               pmix_data_type_t type);
-\end{codepar}
-\cspecificend
+\copySignature{PMIx_Data_copy}{2.0}{
+pmix_status_t \\
+PMIx_Data_copy(void **dest, void *src, \\
+\hspace*{15\sigspace}pmix_data_type_t type);
+}
 
 \begin{arglist}
 \argin{dest}{The address of a pointer into which the address of the resulting data is to be stored. (\code{void**})}
@@ -352,14 +322,11 @@ \subsection{\code{PMIx_Data_print}}
 %%%%
 \format
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-pmix_status_t
-PMIx_Data_print(char **output, char *prefix,
-                void *src, pmix_data_type_t type);
-\end{codepar}
-\cspecificend
+\copySignature{PMIx_Data_print}{2.0}{
+pmix_status_t \\
+PMIx_Data_print(char **output, char *prefix, \\
+\hspace*{16\sigspace}void *src, pmix_data_type_t type);
+}
 
 \begin{arglist}
 \argin{output}{The address of a pointer into which the address of the resulting output is to be stored. (\code{char**})}
@@ -393,14 +360,11 @@ \subsection{\code{PMIx_Data_copy_payload}}
 %%%%
 \format
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-pmix_status_t
-PMIx_Data_copy_payload(pmix_data_buffer_t *dest,
-                       pmix_data_buffer_t *src);
-\end{codepar}
-\cspecificend
+\copySignature{PMIx_Data_copy_payload}{2.0}{
+pmix_status_t \\
+PMIx_Data_copy_payload(pmix_data_buffer_t *dest, \\
+\hspace*{23\sigspace}pmix_data_buffer_t *src);
+}
 
 \begin{arglist}
 \argin{dest}{Pointer to the destination \refstruct{pmix_data_buffer_t} (handle)}

Chap_API_Event.tex

@@ -78,17 +78,14 @@ \subsection{\code{PMIx_Register_event_handler}}
 %%%%
 \format
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-pmix_status_t
-PMIx_Register_event_handler(pmix_status_t codes[], size_t ncodes,
-                            pmix_info_t info[], size_t ninfo,
-                            pmix_notification_fn_t evhdlr,
-                            pmix_hdlr_reg_cbfunc_t cbfunc,
-                            void *cbdata);
-\end{codepar}
-\cspecificend
+\copySignature{PMIx_Register_event_handler}{2.0}{
+pmix_status_t \\
+PMIx_Register_event_handler(pmix_status_t codes[], size_t ncodes, \\
+\hspace*{28\sigspace}pmix_info_t info[], size_t ninfo, \\
+\hspace*{28\sigspace}pmix_notification_fn_t evhdlr, \\
+\hspace*{28\sigspace}pmix_hdlr_reg_cbfunc_t cbfunc, \\
+\hspace*{28\sigspace}void *cbdata);
+}
 
 \begin{arglist}
 \argin{codes}{Array of status codes (array of \refstruct{pmix_status_t})}
@@ -190,12 +187,9 @@ \subsection{System events}
 
 Test a given event constant to see if it falls within the dedicated range of constants for system event reporting.
 
-\versionMarker{2.2}
-\cspecificstart
-\begin{codepar}
+\copySignature{PMIX_SYSTEM_EVENT}{2.2}{
 PMIX_SYSTEM_EVENT(a)
-\end{codepar}
-\cspecificend
+}
 
 \begin{arglist}
 \argin{a}{Error constant to be checked (\refstruct{pmix_status_t})}
@@ -333,19 +327,16 @@ \subsection{Notification Function}
 \adviceuserend
 
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-typedef void (*pmix_notification_fn_t)
-    (size_t evhdlr_registration_id,
-     pmix_status_t status,
-     const pmix_proc_t *source,
-     pmix_info_t info[], size_t ninfo,
-     pmix_info_t results[], size_t nresults,
-     pmix_event_notification_cbfunc_fn_t cbfunc,
-     void *cbdata);
-\end{codepar}
-\cspecificend
+\copySignature{pmix_notification_fn_t}{2.0}{
+typedef void (*pmix_notification_fn_t) \\
+\hspace*{4\sigspace}(size_t evhdlr_registration_id, \\
+\hspace*{5\sigspace}pmix_status_t status, \\
+\hspace*{5\sigspace}const pmix_proc_t *source, \\
+\hspace*{5\sigspace}pmix_info_t info[], size_t ninfo, \\
+\hspace*{5\sigspace}pmix_info_t results[], size_t nresults, \\
+\hspace*{5\sigspace}pmix_event_notification_cbfunc_fn_t cbfunc, \\
+\hspace*{5\sigspace}void *cbdata);
+}
 
 \begin{arglist}
 \argin{evhdlr_registration_id}{Registration number of the handler being called (\code{size_t})}
@@ -397,15 +388,12 @@ \subsection{\code{PMIx_Deregister_event_handler}}
 %%%%
 \format
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-pmix_status_t
-PMIx_Deregister_event_handler(size_t evhdlr_ref,
-                              pmix_op_cbfunc_t cbfunc,
-                              void *cbdata);
-\end{codepar}
-\cspecificend
+\copySignature{PMIx_Deregister_event_handler}{2.0}{
+pmix_status_t \\
+PMIx_Deregister_event_handler(size_t evhdlr_ref, \\
+\hspace*{30\sigspace}pmix_op_cbfunc_t cbfunc, \\
+\hspace*{30\sigspace}void *cbdata);
+}
 
 \begin{arglist}
 \argin{evhdlr_ref}{Event handler ID returned by registration (\code{size_t})}
@@ -449,17 +437,14 @@ \subsection{\code{PMIx_Notify_event}}
 %%%%
 \format
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-pmix_status_t
-PMIx_Notify_event(pmix_status_t status,
-                  const pmix_proc_t *source,
-                  pmix_data_range_t range,
-                  pmix_info_t info[], size_t ninfo,
-                  pmix_op_cbfunc_t cbfunc, void *cbdata);
-\end{codepar}
-\cspecificend
+\copySignature{PMIx_Notify_event}{2.0}{
+pmix_status_t \\
+PMIx_Notify_event(pmix_status_t status, \\
+\hspace*{18\sigspace}const pmix_proc_t *source, \\
+\hspace*{18\sigspace}pmix_data_range_t range, \\
+\hspace*{18\sigspace}pmix_info_t info[], size_t ninfo, \\
+\hspace*{18\sigspace}pmix_op_cbfunc_t cbfunc, void *cbdata);
+}
 
 \begin{arglist}
 \argin{status}{Status code of the event (\refstruct{pmix_status_t})}
@@ -536,16 +521,13 @@ \subsection{Notification Handler Completion Callback Function}
 
 The \refapi{pmix_event_notification_cbfunc_fn_t} is called by event handlers to indicate completion of their operations.
 
-\versionMarker{2.0}
-\cspecificstart
-\begin{codepar}
-typedef void (*pmix_event_notification_cbfunc_fn_t)
-    (pmix_status_t status,
-     pmix_info_t *results, size_t nresults,
-     pmix_op_cbfunc_t cbfunc, void *thiscbdata,
-     void *notification_cbdata);
-\end{codepar}
-\cspecificend
+\copySignature{pmix_event_notification_cbfunc_fn_t}{2.0}{
+typedef void (*pmix_event_notification_cbfunc_fn_t) \\
+\hspace*{4\sigspace}(pmix_status_t status, \\
+\hspace*{5\sigspace}pmix_info_t *results, size_t nresults, \\
+\hspace*{5\sigspace}pmix_op_cbfunc_t cbfunc, void *thiscbdata, \\
+\hspace*{5\sigspace}void *notification_cbdata);
+}
 
 \begin{arglist}
 \argin{status}{Status returned by the event handler's operation (\refstruct{pmix_status_t})}