Skip to content

Commit 3a16466

Browse files
rhc54rhc54
authored
Merge pull request #522 from rhc54/topic/log2
Replace the "log" server module fn with a "log2"
2 parents 41e27e2 + 07f1e6c commit 3a16466

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
@@ -887,48 +887,59 @@ \subsection{\code{PMIx_Log}}
887887
\returnsimple
888888

889889
\reqattrstart
890-
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:
890+
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:
891891

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

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

897897
\pasteAttributeItem{PMIX_LOG_STDERR}
898898
\pasteAttributeItem{PMIX_LOG_STDOUT}
899899
\pasteAttributeItem{PMIX_LOG_SYSLOG}
900-
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
901-
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
900+
901+
Similarly, the following attributes must be supported when provided as part of the \refarg{directives} array:
902+
902903
\pasteAttributeItem{PMIX_LOG_SYSLOG_PRI}
903904
\pasteAttributeItem{PMIX_LOG_ONCE}
904905

905906
\reqattrend
906907

907908
\optattrstart
908-
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_JOB_RECORD}
913+
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
914+
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
915+
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
916+
917+
Similarly, the following attributes are optional when provided as part of the \refarg{directives} array:
909918

910919
\pasteAttributeItem{PMIX_LOG_SOURCE}
911920
\pasteAttributeItem{PMIX_LOG_TIMESTAMP}
912921
\pasteAttributeItem{PMIX_LOG_GENERATE_TIMESTAMP}
913922
\pasteAttributeItem{PMIX_LOG_TAG_OUTPUT}
914923
\pasteAttributeItem{PMIX_LOG_TIMESTAMP_OUTPUT}
915924
\pasteAttributeItem{PMIX_LOG_XML_OUTPUT}
916-
\pasteAttributeItem{PMIX_LOG_EMAIL}
917-
\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR}
918-
\pasteAttributeItem{PMIX_LOG_EMAIL_SENDER_ADDR}
919-
\pasteAttributeItem{PMIX_LOG_EMAIL_SERVER}
920-
\pasteAttributeItem{PMIX_LOG_EMAIL_SRVR_PORT}
921-
\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT}
922-
\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
923-
\pasteAttributeItem{PMIX_LOG_JOB_RECORD}
924-
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
925+
925926

926927
\optattrend
927928

928929
%%%%
929930
\descr
930931

931-
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.
932+
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:
933+
934+
\begin{itemize}
935+
\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.
936+
\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.
937+
\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.
938+
\end{itemize}
939+
940+
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.
941+
942+
Multiple instances of the same attribute can be included in the \refarg{data} array - e.g., to send different emails to various recipients.
932943

933944
\adviceuserstart
934945
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.
@@ -974,49 +985,49 @@ \subsection{\code{PMIx_Log_nb}}
974985
\returnend
975986

976987
\reqattrstart
977-
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:
988+
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:
978989

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

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

984995
\pasteAttributeItem{PMIX_LOG_STDERR}
985996
\pasteAttributeItem{PMIX_LOG_STDOUT}
986997
\pasteAttributeItem{PMIX_LOG_SYSLOG}
987-
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
988-
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
998+
999+
Similarly, the following attributes must be supported when provided as part of the \refarg{directives} array:
1000+
9891001
\pasteAttributeItem{PMIX_LOG_SYSLOG_PRI}
9901002
\pasteAttributeItem{PMIX_LOG_ONCE}
9911003

9921004
\reqattrend
9931005

9941006
\optattrstart
995-
The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation:
1007+
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:
1008+
1009+
\pasteAttributeItem{PMIX_LOG_EMAIL}
1010+
\pasteAttributeItem{PMIX_LOG_JOB_RECORD}
1011+
\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE}
1012+
\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG}
1013+
\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG}
1014+
1015+
Similarly, the following attributes are optional when provided as part of the \refarg{directives} array:
9961016

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

10131025
\optattrend
10141026

10151027
%%%%
10161028
\descr
10171029

1018-
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.
1019-
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.
1030+
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.
10201031

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

11281150
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

0 commit comments

Comments
 (0)