Skip to content

Commit 871bd95

Browse files
rhc54rhc54
committed
Provide better description for PMIx_Log arguments
Expand on the use of the "data" vs "directives" attribute arrays, providing a couple of examples to help clarify their use. Signed-off-by: Ralph Castain <[email protected]>
1 parent e208f20 commit 871bd95

File tree

2 files changed

+34
-76
lines changed

2 files changed

+34
-76
lines changed

‎Chap_API_Job_Mgmt.tex

Lines changed: 32 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -886,48 +886,58 @@ \subsection{\code{PMIx_Log}}
886886
\returnsimple
887887

888888
\reqattrstart
889-
If the \ac{PMIx} library does not itself perform this operation, then it is required to pass any attributes provided by the client to the host environment for processing. In addition, it must include the following attributes in the passed \refarg{info} array:
889+
If the \ac{PMIx} library does not itself perform this operation, then it is required to pass any attributes provided by the client to the host environment for processing. In addition, it must include the following attributes in the passed \refarg{directives} array:
890890

891891
\pasteAttributeItem{PMIX_USERID}
892892
\pasteAttributeItem{PMIX_GRPID}
893893

894-
Host environments or \ac{PMIx} libraries that implement support for this operation are required to support the following attributes:
894+
Host environments or \ac{PMIx} libraries that implement support for this operation are required to support the following attributes when provided as part of the \refarg{data} array:
895895

896896
\pasteAttributeItem{PMIX_LOG_STDERR}
897897
\pasteAttributeItem{PMIX_LOG_STDOUT}
898898
\pasteAttributeItem{PMIX_LOG_SYSLOG}
899899
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
900900
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
901+
902+
Similarly, the following attributes must be supported when provided as part of the \refarg{directives} array:
901903
\pasteAttributeItem{PMIX_LOG_SYSLOG_PRI}
902904
\pasteAttributeItem{PMIX_LOG_ONCE}
903905

904906
\reqattrend
905907

906908
\optattrstart
907-
The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation:
909+
The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation when provided as part of the \refarg{data} array:
910+
911+
\pasteAttributeItem{PMIX_LOG_EMAIL}
912+
\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
913+
\pasteAttributeItem{PMIX_LOG_JOB_RECORD}
914+
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
915+
916+
Similarly, the following attributes are optional when provided as part of the \refarg{directives} array:
908917

909918
\pasteAttributeItem{PMIX_LOG_SOURCE}
910919
\pasteAttributeItem{PMIX_LOG_TIMESTAMP}
911920
\pasteAttributeItem{PMIX_LOG_GENERATE_TIMESTAMP}
912921
\pasteAttributeItem{PMIX_LOG_TAG_OUTPUT}
913922
\pasteAttributeItem{PMIX_LOG_TIMESTAMP_OUTPUT}
914923
\pasteAttributeItem{PMIX_LOG_XML_OUTPUT}
915-
\pasteAttributeItem{PMIX_LOG_EMAIL}
916924
\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR}
917925
\pasteAttributeItem{PMIX_LOG_EMAIL_SENDER_ADDR}
918926
\pasteAttributeItem{PMIX_LOG_EMAIL_SERVER}
919927
\pasteAttributeItem{PMIX_LOG_EMAIL_SRVR_PORT}
920928
\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT}
921-
\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
922-
\pasteAttributeItem{PMIX_LOG_JOB_RECORD}
923-
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
929+
924930

925931
\optattrend
926932

927933
%%%%
928934
\descr
929935

930-
Log data subject to the services offered by the host environment. The data to be logged is provided in the \refarg{data} array. The (optional) \refarg{directives} can be used to direct the choice of logging channel.
936+
Log data subject to the services offered by the host environment. The \refarg{data} array is used to specify the information that is to be logged, while the \refarg{directives} array is used to control formatting and other output options. For example, a user can log a message to \code{stderr} by including \refattr{PMIX_LOG_STDERR} in the \refarg{data} array, with the message itself provided as a string value in that \refstruct{pmix_info_t} element. They can also have that message time-stamped by including the \refattr{PMIX_LOG_TIMESTAMP} attribute in the \refarg{directives} array.
937+
938+
Note that it is possible to log multiple messages to different channels using a single call to \refapi{PMIx_Log}. In the above example, one could add another element to the \refarg{data} array to specify that a message also be output to \code{stdout} using the \refattr{PMIX_LOG_STDOUT} attribute, with that message provided as a string value in the element. Note that both messages would be time-stamped since the \refattr{PMIX_LOG_TIMESTAMP} is included in the \refarg{directives}, and that the two string messages can be different. Alternatively, one might choose to specify a message to be sent to \code{stderr} using \refattr{PMIX_LOG_STDERR} while simultaneously requesting that a message be delivered via email using \refattr{PMIX_LOG_EMAIL}. In this case, only directives that are applicable to a channel will be used in outputting to that channel. In this example, a directive such as \refattr{PMIX_LOG_TIMESTAMP} would cause both messages to be time-stamped, while directives specifying email addresses and server would only be applied to the email message.
939+
940+
While it is also permissible to include multiple instances of the same attribute in the \refarg{data} array, some care must be taken with regards to the provided \refarg{directives} as the directives are applied to all messages in the \refarg{data} array. Thus, multiple \refattr{PMIX_LOG_EMAIL} requests in the same function call will be sent to the same addresses as the \refattr{PMIX_LOG_EMAIL_ADDR} is a directive.
931941

932942
\adviceuserstart
933943
It is strongly recommended that the \refapi{PMIx_Log} API not be used by applications for streaming data as it is not a ``performant'' transport and can perturb the application since it involves the local \ac{PMIx} server and host \ac{SMS} daemon. Note that a return of \refconst{PMIX_SUCCESS} only denotes that the data was successfully handed to the appropriate system call (for local channels) or the host environment and does not indicate receipt at the final destination.
@@ -973,49 +983,55 @@ \subsection{\code{PMIx_Log_nb}}
973983
\returnend
974984

975985
\reqattrstart
976-
If the \ac{PMIx} library does not itself perform this operation, then it is required to pass any attributes provided by the client to the host environment for processing. In addition, it must include the following attributes in the passed \refarg{info} array:
986+
If the \ac{PMIx} library does not itself perform this operation, then it is required to pass any attributes provided by the client to the host environment for processing. In addition, it must include the following attributes in the passed \refarg{directives} array:
977987

978988
\pasteAttributeItem{PMIX_USERID}
979989
\pasteAttributeItem{PMIX_GRPID}
980990

981-
Host environments or \ac{PMIx} libraries that implement support for this operation are required to support the following attributes:
991+
Host environments or \ac{PMIx} libraries that implement support for this operation are required to support the following attributes when provided as part of the \refarg{data} array:
982992

983993
\pasteAttributeItem{PMIX_LOG_STDERR}
984994
\pasteAttributeItem{PMIX_LOG_STDOUT}
985995
\pasteAttributeItem{PMIX_LOG_SYSLOG}
986996
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
987997
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
998+
999+
Similarly, the following attributes must be supported when provided as part of the \refarg{directives} array:
9881000
\pasteAttributeItem{PMIX_LOG_SYSLOG_PRI}
9891001
\pasteAttributeItem{PMIX_LOG_ONCE}
9901002

9911003
\reqattrend
9921004

9931005
\optattrstart
994-
The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation:
1006+
The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation when provided as part of the \refarg{data} array:
1007+
1008+
\pasteAttributeItem{PMIX_LOG_EMAIL}
1009+
\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
1010+
\pasteAttributeItem{PMIX_LOG_JOB_RECORD}
1011+
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
1012+
1013+
Similarly, the following attributes are optional when provided as part of the \refarg{directives} array:
9951014

9961015
\pasteAttributeItem{PMIX_LOG_SOURCE}
9971016
\pasteAttributeItem{PMIX_LOG_TIMESTAMP}
9981017
\pasteAttributeItem{PMIX_LOG_GENERATE_TIMESTAMP}
9991018
\pasteAttributeItem{PMIX_LOG_TAG_OUTPUT}
10001019
\pasteAttributeItem{PMIX_LOG_TIMESTAMP_OUTPUT}
10011020
\pasteAttributeItem{PMIX_LOG_XML_OUTPUT}
1002-
\pasteAttributeItem{PMIX_LOG_EMAIL}
10031021
\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR}
10041022
\pasteAttributeItem{PMIX_LOG_EMAIL_SENDER_ADDR}
10051023
\pasteAttributeItem{PMIX_LOG_EMAIL_SERVER}
10061024
\pasteAttributeItem{PMIX_LOG_EMAIL_SRVR_PORT}
10071025
\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT}
1008-
\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
1009-
\pasteAttributeItem{PMIX_LOG_JOB_RECORD}
1010-
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
1026+
10111027

10121028
\optattrend
10131029

10141030
%%%%
10151031
\descr
10161032

10171033
Log data subject to the services offered by the host environment. The data to be logged is provided in the \refarg{data} array. The (optional) \refarg{directives} can be used to direct the choice of logging channel.
1018-
The callback function will be executed when the log operation has been completed. The \refarg{data} and \refarg{directives} arrays must be maintained until the callback is provided.
1034+
The callback function will be executed when the log operation has been completed. The \refarg{data} and \refarg{directives} arrays must be maintained until the callback is provided. See the description in \refapi{PMIx_Log} for details on use of the \refarg{data} and \refarg{directives} arrays.
10191035

10201036
\adviceuserstart
10211037
It is strongly recommended that the \refapi{PMIx_Log_nb} API not be used by applications for streaming data as it is not a ``performant'' transport and can perturb the application since it involves the local \ac{PMIx} server and host \ac{SMS} daemon. Note that a return of \refconst{PMIX_SUCCESS} only denotes that the data was successfully handed to the appropriate system call (for local channels) or the host environment and does not indicate receipt at the final destination.
@@ -1084,10 +1100,6 @@ \subsection{Log attributes}
10841100
Only log this once with whichever channel can first support it, taking the channels in priority order.
10851101
}
10861102
%
1087-
\declareAttribute{PMIX_LOG_MSG}{"pmix.log.msg"}{pmix_byte_object_t}{
1088-
Message blob to be sent somewhere.
1089-
}
1090-
%
10911103
\declareAttribute{PMIX_LOG_EMAIL}{"pmix.log.email"}{pmix_data_array_t}{
10921104
Log via email based on \refstruct{pmix_info_t} containing directives.
10931105
}

‎Chap_API_Server.tex

Lines changed: 2 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -3409,43 +3409,16 @@ \subsection{\code{pmix_server_log2_fn_t}}
34093409
Returns one of the following:
34103410

34113411
\begin{itemize}
3412-
\item \refconst{PMIX_SUCCESS}, indicating that the request is being processed by the host environment - result will be returned in the provided \refarg{cbfunc}. Note that the host must not invoke the callback function prior to returning from the \ac{API}.
3412+
\item \refconst{PMIX_SUCCESS}, indicating that the request is being processed by the host environment - result will be returned in the provided \refarg{cbfunc}.
34133413
\item \refconst{PMIX_OPERATION_SUCCEEDED}, indicating that the request was immediately processed and returned \textit{success} - the \refarg{cbfunc} will not be called
34143414
\item \refconst{PMIX_ERR_NOT_SUPPORTED}, indicating that the host environment does not support the request, even though the function entry was provided in the server module - the \refarg{cbfunc} will not be called
34153415
\item a PMIx error constant indicating either an error in the input or that the request was immediately processed and failed - the \refarg{cbfunc} will not be called
34163416
\end{itemize}
34173417

3418-
\reqattrstart
3419-
\ac{PMIx} libraries are required to pass any provided attributes to the host environment for processing. In addition, the following attributes are required to be included in the passed \refarg{info} array:
3420-
3421-
\pasteAttributeItem{PMIX_USERID}
3422-
\pasteAttributeItem{PMIX_GRPID}
3423-
3424-
\divider
3425-
3426-
Host environments that provide this module entry point are required to support the following attributes:
3427-
3428-
\pasteAttributeItem{PMIX_LOG_STDERR}
3429-
\pasteAttributeItem{PMIX_LOG_STDOUT}
3430-
\pasteAttributeItem{PMIX_LOG_SYSLOG}
3431-
3432-
\reqattrend
3433-
3434-
\optattrstart
3435-
The following attributes are optional for host environments that support this operation:
3436-
3437-
\pasteAttributeItem{PMIX_LOG_MSG}
3438-
\pasteAttributeItem{PMIX_LOG_EMAIL}
3439-
\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR}
3440-
\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT}
3441-
\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
3442-
3443-
\optattrend
3444-
34453418
%%%%
34463419
\descr
34473420

3448-
Log data on behalf of a client. This function is not intended for output of computational results, but rather for reporting status and error messages. The host must not execute the callback function prior to returning from the \ac{API}.
3421+
Log data on behalf of a client. This function is not intended for output of computational results, but rather for reporting status and error messages. See the description in \refapi{PMIx_Log} for details on information included in the data vs directives arrays.
34493422

34503423

34513424
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -3479,33 +3452,6 @@ \subsection{\code{pmix_server_log_fn_t}}
34793452
\end{arglist}
34803453

34813454

3482-
\reqattrstart
3483-
\ac{PMIx} libraries are required to pass any provided attributes to the host environment for processing. In addition, the following attributes are required to be included in the passed \refarg{info} array:
3484-
3485-
\pasteAttributeItem{PMIX_USERID}
3486-
\pasteAttributeItem{PMIX_GRPID}
3487-
3488-
\divider
3489-
3490-
Host environments that provide this module entry point are required to support the following attributes:
3491-
3492-
\pasteAttributeItem{PMIX_LOG_STDERR}
3493-
\pasteAttributeItem{PMIX_LOG_STDOUT}
3494-
\pasteAttributeItem{PMIX_LOG_SYSLOG}
3495-
3496-
\reqattrend
3497-
3498-
\optattrstart
3499-
The following attributes are optional for host environments that support this operation:
3500-
3501-
\pasteAttributeItem{PMIX_LOG_MSG}
3502-
\pasteAttributeItem{PMIX_LOG_EMAIL}
3503-
\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR}
3504-
\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT}
3505-
\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
3506-
3507-
\optattrend
3508-
35093455
%%%%
35103456
\descr
35113457

0 commit comments

Comments
 (0)