Skip to content

Replace the "tool_connection" fn with a "tool_connection2" #524

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rhc54 merged 1 commit into from
Jul 21, 2025
Merged

Replace the "tool_connection" fn with a "tool_connection2" #524

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 77 additions & 10 deletions Chap_API_Server.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -955,7 +955,7 @@ \subsection{\code{PMIx_server_deregister_resources}}

A \code{NULL} \refarg{cbfunc} reference indicates that the function is to be executed as a blocking operation.
% TODO: If this is one of those functions that can be blocking or non-blocking, then
% it needs a full return code explanation, not the returnsimple
% it needs a full return code explanation, not the returnsimple

\advicermend

Expand Down Expand Up @@ -1995,7 +1995,7 @@ \subsection{\code{pmix_server_module_t} Module}
/* v2x interfaces */
pmix_server_notify_event_fn_t notify_event;
pmix_server_query_fn_t query;
pmix_server_tool_connection_fn_t tool_connected;
pmix_server_tool_connection_fn_t tool_connected; // DEPRECATED
pmix_server_log_fn_t log;
pmix_server_alloc_fn_t allocate;
pmix_server_job_control_fn_t job_control;
Expand All @@ -2009,6 +2009,7 @@ \subsection{\code{pmix_server_module_t} Module}
pmix_server_grp_fn_t group;
pmix_server_fabric_fn_t fabric;
pmix_server_client_connected2_fn_t client_connected2;
pmix_server_tool_connection2_fn_t tool_connected2;
\} pmix_server_module_t;
\end{codepar}
\cspecificend
Expand Down Expand Up @@ -3246,8 +3247,9 @@ \subsection{\code{pmix_server_query_fn_t}}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\code{pmix_server_tool_connection_fn_t}}
\declareapi{pmix_server_tool_connection_fn_t}
\versionMarkerProvisional{6.0}
\subsection{\code{pmix_server_tool_connection2_fn_t}}
\declareapi{pmix_server_tool_connection2_fn_t}

%%%%
\summary
Expand All @@ -3257,8 +3259,8 @@ \subsection{\code{pmix_server_tool_connection_fn_t}}
%%%%
\format

\copySignature{pmix_server_tool_connection_fn_t}{2.0}{
typedef void (*pmix_server_tool_connection_fn_t)( \\
\copySignature{pmix_server_tool_connection2_fn_t}{6.0}{
typedef pmix_status_t (*pmix_server_tool_connection2_fn_t)( \\
\hspace*{29\sigspace}pmix_info_t info[], size_t ninfo, \\
\hspace*{29\sigspace}pmix_tool_connection_cbfunc_t cbfunc, \\
\hspace*{29\sigspace}void *cbdata);
Expand All @@ -3271,6 +3273,15 @@ \subsection{\code{pmix_server_tool_connection_fn_t}}
\argin{cbdata}{Data to be passed to the callback function (memory reference)}
\end{arglist}

Returns one of the following:

\begin{itemize}
\item \refconst{PMIX_SUCCESS}, indicating that the request is being processed by the host environment - result will be returned in the provided \refarg{cbfunc}.
\item \refconst{PMIX_OPERATION_SUCCEEDED}, indicating that the request was immediately processed and returned \textit{success} - the \refarg{cbfunc} will not be called
\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
\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
\end{itemize}

\reqattrstart
\ac{PMIx} libraries are required to pass the following attributes in the \refarg{info} array:

Expand Down Expand Up @@ -3307,19 +3318,20 @@ \subsection{\code{pmix_server_tool_connection_fn_t}}
If the tool already has an assigned process identifier, then this must be
indicated in the \refarg{info} array. The host is responsible for checking
that the provided namespace does not conflict with any currently known
assignments, returning an appropriate error in the callback function if a conflict is found.
assignments, returning an appropriate error (either directly or in the
callback function) if a conflict is found.

The host environment is solely responsible for authenticating and authorizing
the connection using whatever means it deems appropriate. If certificates or
other authentication information are required, then the tool must provide them.
The conclusion of those operations shall be communicated back to the \ac{PMIx}
server library via the callback function.

Approval or rejection of the connection request shall be returned in the
Approval or rejection of the connection request shall be returned either directly
or in the
\refarg{status} parameter of the \refapi{pmix_tool_connection_cbfunc_t}. If
the connection is refused, the \ac{PMIx} server library must terminate the
connection attempt. The host must not execute the callback function prior to
returning from the \ac{API}.
connection attempt.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Tool connection attributes}
Expand Down Expand Up @@ -3374,6 +3386,61 @@ \subsubsection{PMIx Tool Connection Callback Function}
\advicermend


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\code{pmix_server_tool_connection_fn_t}}
\declareapi{pmix_server_tool_connection_fn_t}

%%%%
\summary

Register that a tool has connected to the server.

%%%%
\format

\copySignature{pmix_server_tool_connection_fn_t}{2.0}{
typedef pmix_status_t (*pmix_server_tool_connection_fn_t)( \\
\hspace*{29\sigspace}pmix_info_t info[], size_t ninfo, \\
\hspace*{29\sigspace}pmix_tool_connection_cbfunc_t cbfunc, \\
\hspace*{29\sigspace}void *cbdata);
}

\begin{arglist}
\argin{info}{Array of \refstruct{pmix_info_t} structures (array of handles)}
\argin{ninfo}{Number of elements in the \refarg{info} array (integer)}
\argin{cbfunc}{Callback function \refapi{pmix_tool_connection_cbfunc_t} (function reference)}
\argin{cbdata}{Data to be passed to the callback function (memory reference)}
\end{arglist}

\reqattrstart
\ac{PMIx} libraries are required to pass the following attributes in the \refarg{info} array:

\pasteAttributeItem{PMIX_USERID}
\pasteAttributeItem{PMIX_GRPID}
\pasteAttributeItemBegin{PMIX_TOOL_NSPACE}This must be included only if the tool already has an assigned namespace.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_TOOL_RANK}This must be included only if the tool already has an assigned rank.
\pasteAttributeItemEnd{}
\pasteAttributeItem{PMIX_CREDENTIAL}

\reqattrend


\optattrstart
The following attributes are optional for host environments that support this operation:

\pasteAttributeItem{PMIX_FWD_STDOUT}
\pasteAttributeItem{PMIX_FWD_STDERR}
\pasteAttributeItem{PMIX_FWD_STDIN}
\pasteAttributeItem{PMIX_VERSION_INFO}

\optattrend

%%%%
\descr

This function module entry has been \textbf{DEPRECATED} in favor of \refapi{pmix_server_tool_connection2_fn_t}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\code{pmix_server_log_fn_t}}
\declareapi{pmix_server_log_fn_t}
Expand Down