Skip to content

Commit 0867065

Browse files
rhc54rhc54
committed
Replace the "log" server module fn with a "log2"
The current "log" server module function was defined with a void return. This contrasts with most of the other module functions which characteristically return a pmix_status_t, thereby supporting a return status that indicates if the function is not supported or has been atomically completed. Add a replacement "log2" function that is identical in signature except for returning a pmix_status_t instead of void. Deprecate the current "log" function. Signed-off-by: Ralph Castain <[email protected]> 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 87d6470 commit 0867065

File tree

2 files changed

+178
-96
lines changed

2 files changed

+178
-96
lines changed

‎Chap_API_Job_Mgmt.tex‎

Lines changed: 64 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -886,48 +886,59 @@ \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}
899-
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
900-
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
899+
900+
Similarly, the following attributes must be supported when provided as part of the \refarg{directives} array:
901+
901902
\pasteAttributeItem{PMIX_LOG_SYSLOG_PRI}
902903
\pasteAttributeItem{PMIX_LOG_ONCE}
903904

904905
\reqattrend
905906

906907
\optattrstart
907-
The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation:
908+
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:
909+
910+
\pasteAttributeItem{PMIX_LOG_EMAIL}
911+
\pasteAttributeItem{PMIX_LOG_JOB_RECORD}
912+
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
913+
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
914+
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
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}
916-
\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR}
917-
\pasteAttributeItem{PMIX_LOG_EMAIL_SENDER_ADDR}
918-
\pasteAttributeItem{PMIX_LOG_EMAIL_SERVER}
919-
\pasteAttributeItem{PMIX_LOG_EMAIL_SRVR_PORT}
920-
\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT}
921-
\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
922-
\pasteAttributeItem{PMIX_LOG_JOB_RECORD}
923-
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
924+
924925

925926
\optattrend
926927

927928
%%%%
928929
\descr
929930

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.
931+
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:
932+
933+
\begin{itemize}
934+
\item 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.
935+
\item send an email to one or more recipients by including \refattr{PMIX_LOG_EMAIL} in the \refarg{data} array, with the \refstruct{pmix_data_array_t} value containing the message, recipient, and any required server information. Note that any \refarg{directives} (e.g., \refattr{PMIX_LOG_GENERATE_TIMESTAMP}) will be applied to the email request.
936+
\item log a message to the syslog on the system console by including \refattr{PMIX_LOG_GLOBAL_SYSLOG} in the \refarg{data} array, with the message itself provided as a string value in that \refstruct{pmix_info_t} element. The syslog priority could be set with \refattr{PMIX_LOG_SYSLOG_PRI} in the \refarg{directives} array.
937+
\end{itemize}
938+
939+
Note that it is possible to log multiple messages to different channels using a single call to \refapi{PMIx_Log}. For instance, the above examples could be combined into a single call to \refapi{PMIx_Log}. In this case, only directives that are applicable to a channel will be used in outputting to that channel. For this example, a directive such as \refattr{PMIX_LOG_TIMESTAMP} would cause all three messages to be time-stamped, but a \refattr{PMIX_LOG_SYSLOG_PRI} directive would only be applied to the syslog channel.
940+
941+
Multiple instances of the same attribute can be included in the \refarg{data} array - e.g., to send different emails to various recipients.
931942

932943
\adviceuserstart
933944
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 +984,49 @@ \subsection{\code{PMIx_Log_nb}}
973984
\returnend
974985

975986
\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:
987+
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:
977988

978989
\pasteAttributeItem{PMIX_USERID}
979990
\pasteAttributeItem{PMIX_GRPID}
980991

981-
Host environments or \ac{PMIx} libraries that implement support for this operation are required to support the following attributes:
992+
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:
982993

983994
\pasteAttributeItem{PMIX_LOG_STDERR}
984995
\pasteAttributeItem{PMIX_LOG_STDOUT}
985996
\pasteAttributeItem{PMIX_LOG_SYSLOG}
986-
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
987-
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
997+
998+
Similarly, the following attributes must be supported when provided as part of the \refarg{directives} array:
999+
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_JOB_RECORD}
1010+
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
1011+
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
1012+
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
1013+
1014+
Similarly, the following attributes are optional when provided as part of the \refarg{directives} array:
9951015

9961016
\pasteAttributeItem{PMIX_LOG_SOURCE}
9971017
\pasteAttributeItem{PMIX_LOG_TIMESTAMP}
9981018
\pasteAttributeItem{PMIX_LOG_GENERATE_TIMESTAMP}
9991019
\pasteAttributeItem{PMIX_LOG_TAG_OUTPUT}
10001020
\pasteAttributeItem{PMIX_LOG_TIMESTAMP_OUTPUT}
10011021
\pasteAttributeItem{PMIX_LOG_XML_OUTPUT}
1002-
\pasteAttributeItem{PMIX_LOG_EMAIL}
1003-
\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR}
1004-
\pasteAttributeItem{PMIX_LOG_EMAIL_SENDER_ADDR}
1005-
\pasteAttributeItem{PMIX_LOG_EMAIL_SERVER}
1006-
\pasteAttributeItem{PMIX_LOG_EMAIL_SRVR_PORT}
1007-
\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT}
1008-
\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
1009-
\pasteAttributeItem{PMIX_LOG_JOB_RECORD}
1010-
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
1022+
10111023

10121024
\optattrend
10131025

10141026
%%%%
10151027
\descr
10161028

1017-
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.
1029+
Log data subject to the services offered by the host environment. See the description in \refapi{PMIx_Log} for details on use of the \refarg{data} and \refarg{directives} arrays.
10191030

10201031
\adviceuserstart
10211032
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,12 +1095,14 @@ \subsection{Log attributes}
10841095
Only log this once with whichever channel can first support it, taking the channels in priority order.
10851096
}
10861097
%
1087-
\declareAttribute{PMIX_LOG_MSG}{"pmix.log.msg"}{pmix_byte_object_t}{
1088-
Message blob to be sent somewhere.
1089-
}
1090-
%
10911098
\declareAttribute{PMIX_LOG_EMAIL}{"pmix.log.email"}{pmix_data_array_t}{
1092-
Log via email based on \refstruct{pmix_info_t} containing directives.
1099+
Log via email based on \refstruct{pmix_info_t} containing directives. The array must contain at least one of
1100+
the \refattr{PMIX_LOG_BLOB} or \refattr{PMIX_LOG_MSG} attributes containing the body of the
1101+
message. In addition, it must contain at least the \refattr{PMIX_LOG_EMAIL_ADDR} and \refattr{PMIX_LOG_EMAIL_SUBJECT}
1102+
attributes identifying the intended recipients and the subject for the message. The array can optionally include
1103+
the server information (\refattr{PMIX_LOG_EMAIL_SERVER} and \refattr{PMIX_LOG_EMAIL_SRVR_PORT}) if required by the
1104+
local system, and a return email address for the sender (\refattr{PMIX_LOG_EMAIL_SENDER_ADDR}. No specific ordering
1105+
of these directives is required.
10931106
}
10941107
%
10951108
\declareAttribute{PMIX_LOG_EMAIL_ADDR}{"pmix.log.emaddr"}{char*}{
@@ -1104,8 +1117,12 @@ \subsection{Log attributes}
11041117
Subject line for email.
11051118
}
11061119
%
1107-
\declareAttribute{PMIX_LOG_EMAIL_MSG}{"pmix.log.emmsg"}{char*}{
1108-
Message to be included in email.
1120+
\declareAttribute{PMIX_LOG_MSG}{"pmix.log.msg"}{char*}{
1121+
Message to be included in a log operation.
1122+
}
1123+
%
1124+
\declareAttributeProvisional{PMIX_LOG_BLOB}{"pmix.log.blob"}{pmix_byte_object_t}{
1125+
Message blob (e.g., PDF attachment) to be included in a log operation.
11091126
}
11101127
%
11111128
\declareAttribute{PMIX_LOG_EMAIL_SERVER}{"pmix.log.esrvr"}{char*}{
@@ -1116,12 +1133,17 @@ \subsection{Log attributes}
11161133
Port the email server is listening to.
11171134
}
11181135
%
1119-
\declareAttribute{PMIX_LOG_GLOBAL_DATASTORE}{"pmix.log.gstore"}{bool}{
1120-
Store the log data in a global data store (e.g., database).
1136+
\declareAttributeProvisional{PMIX_LOG_GLOBAL_DATASTORE}{"pmix.log.gstore"}{pmix_data_array_t}{
1137+
Store the log data in a global data store (e.g., database). Directs the host environment to
1138+
store the provided message in a data store available
1139+
to the host. The associated array must contain at least one of
1140+
the \refattr{PMIX_LOG_BLOB} or \refattr{PMIX_LOG_MSG} attributes containing the data to be
1141+
stored.
11211142
}
11221143
%
1123-
\declareAttribute{PMIX_LOG_JOB_RECORD}{"pmix.log.jrec"}{bool}{
1124-
Log the provided information to the host environment's job record.
1144+
\declareAttributeProvisional{PMIX_LOG_JOB_RECORD}{"pmix.log.jrec"}{char*}{
1145+
Log the provided message to the host environment's job record. An error must be returned if the host
1146+
does not support this service.
11251147
}
11261148

11271149
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

0 commit comments

Comments
 (0)