diff --git a/App_Python.tex b/App_Python.tex index 46c8e940..cb0bb36a 100644 --- a/App_Python.tex +++ b/App_Python.tex @@ -51,49 +51,49 @@ \section{Datatype Definitions} \hline C-Definition & PMIx Name & Python Definition & Notes \\ \hline \endhead - \code{bool} & PMIX_BOOL & boolean & \\ \hline - \code{byte} & PMIX_BYTE & A single element byte array (i.e., a byte array of length one) & \\ \hline - \code{char*} & PMIX_STRING & string & \\ \hline - \code{size_t} & PMIX_SIZE & integer & \\ \hline - \code{pid_t} & PMIX_PID & integer & value shall be limited to the \code{uint32_t} range \\ \hline - \code{int, int8_t, int16_t, int32_t, int64_t} & PMIX_INT, PMIX_INT8, PMIX_INT16, PMIX_INT32, PMIX_INT64 & integer & value shall be limited to its corresponding range \\ \hline - \code{uint, uint8_t, uint16_t, uint32_t, uint64_t} & PMIX_UINT, PMIX_UINT8, PMIX_UINT16, PMIX_UINT32, PMIX_UINT64 & integer & value shall be limited to its corresponding range \\ \hline - \code{float, double} & PMIX_FLOAT, PMIX_DOUBLE & float & value shall be limited to its corresponding range \\ \hline - \code{struct timeval} & PMIX_TIMEVAL & \{'sec': sec, 'usec': microsec\} & each field is an integer value \\ \hline - \code{time_t} & PMIX_TIME & integer & limited to positive values \\ \hline - \refstruct{pmix_data_type_t} & PMIX_DATA_TYPE & integer & value shall be limited to the \code{uint16_t} range \\ \hline - \refstruct{pmix_status_t} & PMIX_STATUS & integer & \\ \hline + \code{bool} & \refconst{PMIX_BOOL} & boolean & \\ \hline + \code{byte} & \refconst{PMIX_BYTE} & A single element byte array (i.e., a byte array of length one) & \\ \hline + \code{char*} & \refconst{PMIX_STRING} & string & \\ \hline + \code{size_t} & \refconst{PMIX_SIZE} & integer & \\ \hline + \code{pid_t} & \refconst{PMIX_PID} & integer & value shall be limited to the \code{uint32_t} range \\ \hline + \code{int, int8_t, int16_t, int32_t, int64_t} & \refconst{PMIX_INT}, \refconst{PMIX_INT8}, \refconst{PMIX_INT16}, \refconst{PMIX_INT32}, \refconst{PMIX_INT64} & integer & value shall be limited to its corresponding range \\ \hline + \code{uint, uint8_t, uint16_t, uint32_t, uint64_t} & \refconst{PMIX_UINT}, \refconst{PMIX_UINT8}, \refconst{PMIX_UINT16}, \refconst{PMIX_UINT32}, \refconst{PMIX_UINT64} & integer & value shall be limited to its corresponding range \\ \hline + \code{float, double} & \refconst{PMIX_FLOAT}, \refconst{PMIX_DOUBLE} & float & value shall be limited to its corresponding range \\ \hline + \code{struct timeval} & \refconst{PMIX_TIMEVAL} & \{'sec': sec, 'usec': microsec\} & each field is an integer value \\ \hline + \code{time_t} & \refconst{PMIX_TIME} & integer & limited to positive values \\ \hline + \refstruct{pmix_data_type_t} & \refconst{PMIX_DATA_TYPE} & integer & value shall be limited to the \code{uint16_t} range \\ \hline + \refstruct{pmix_status_t} & \refconst{PMIX_STATUS} & integer & \\ \hline \refstruct{pmix_key_t} & N/A & \pylabel{key}string & The string's length shall be limited to one less than the size of the \refstruct{pmix_key_t} array (to reserve space for the terminating \code{NULL}) \\ \hline \refstruct{pmix_nspace_t} & N/A & \pylabel{nspace}string & The string's length shall be limited to one less than the size of the \refstruct{pmix_nspace_t} array (to reserve space for the terminating \code{NULL}) \\ \hline - \refstruct{pmix_rank_t} & PMIX_PROC_RANK & \pylabel{rank}integer & value shall be limited to the \code{uint32_t} range excepting the reserved values near \code{UINT32_MAX} \\ \hline - \refstruct{pmix_proc_t} & PMIX_PROC & \pylabel{proc}\{'nspace': nspace, 'rank': rank\} & \refarg{nspace} is a Python string and \refarg{rank} is an integer value. The \refarg{nspace} string's length shall be limited to one less than the size of the \refstruct{pmix_nspace_t} array (to reserve space for the terminating \code{NULL}), and the \refarg{rank} value shall conform to the constraints associated with \refstruct{pmix_rank_t} \\ \hline - \refstruct{pmix_byte_object_t} & PMIX_BYTE_OBJECT & \pylabel{byteobject}\{'bytes': bytes, 'size': size\} & \refarg{bytes} is a Python byte array and \refarg{size} is the integer number of bytes in that array. \\ \hline - \refstruct{pmix_persistence_t} & PMIX_PERSISTENCE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_scope_t} & PMIX_SCOPE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_data_range_t} & PMIX_RANGE & \pylabel{range}integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_proc_state_t} & PMIX_PROC_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_proc_info_t} & PMIX_PROC_INFO & \{'proc': \{'nspace': nspace, 'rank': rank\}, 'hostname': hostname, 'executable': executable, 'pid': pid, 'exitcode': exitcode, 'state': state\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{hostname} and \refarg{executable} are Python strings; and \refarg{pid}, \refarg{exitcode}, and \refarg{state} are Python integers \\ \hline - \refstruct{pmix_data_array_t} & PMIX_DATA_ARRAY & \pylabel{array}\{'type': type, 'array': array\} & \refarg{type} is the \ac{PMIx} type of object in the array and \refarg{array} is a Python \emph{list} containing the individual array elements. Note that \refarg{array} can consist of \emph{any} \ac{PMIx} types, including (for example) a Python \refpy{info} object that itself contains an \refpy{array} value \\ \hline - \refstruct{pmix_info_directives_t} & PMIX_INFO_DIRECTIVES & \pylabel{info directives}list & list of integer values (defined in Section \ref{api:struct:infodirs}) \\ \hline - \refstruct{pmix_alloc_directive_t} & PMIX_ALLOC_DIRECTIVE & \pylabel{allocdir}integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_iof_channel_t} & PMIX_IOF_CHANNEL & \pylabel{channel}list & list of integer values (defined in Section \ref{api:tool:iofchannels}) \\ \hline - \refstruct{pmix_envar_t} & PMIX_ENVAR & \{'envar': envar, 'value': value, 'separator': separator\} & \refarg{envar} and \refarg{value} are Python strings, and \refarg{separator} a single-character Python string \\ \hline - \refstruct{pmix_value_t} & PMIX_VALUE & \pylabel{value}\{'value': value, 'val_type': type\} & \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline - \refstruct{pmix_info_t} & PMIX_INFO & \pylabel{info}\{'key': key, 'flags': flags, value': value, 'val_type': type\} & \refarg{key} is a Python string \refpy{key}, \refarg{flags} is an \refpy{info directives} value, \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline - \refstruct{pmix_pdata_t} & PMIX_PDATA & \pylabel{pdata}\{'proc': \{'nspace': nspace, 'rank': rank\}, 'key': key, 'value': value, 'val_type': type\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{key} is a Python string \refpy{key}; \refarg{type} is the \ac{PMIx} datatype of \refarg{value}; and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline - \refstruct{pmix_app_t} & PMIX_APP & \pylabel{app}\{'cmd': cmd, 'argv': [argv], 'env': [env], 'maxprocs': maxprocs, 'info': [info]\} & \refarg{cmd} is a Python string; \refarg{argv} and \refarg{env} are Python \emph{lists} containing Python strings; \refarg{maxprocs} is an integer; and \refarg{info} is a Python \emph{list} of \refpy{info} values \\ \hline - \refstruct{pmix_query_t} & PMIX_QUERY & \pylabel{query}\{'keys': [keys], 'qualifiers': [info]\} & \refarg{keys} is a Python \emph{list} of Python strings, and \refarg{qualifiers} is a Python \emph{list} of \refpy{info} values \\ \hline - \refstruct{pmix_regattr_t} & PMIX_REGATTR & \pylabel{regattr}\{'name': name, 'key': key, 'type': type, 'info': [info], 'description': [desc]\} & \refarg{name} and \refarg{string} are Python strings; \refarg{type} is the \ac{PMIx} datatype for the attribute's value; \refarg{info} is a Python \emph{list} of \refpy{info} values; and \refarg{description} is a list of Python strings describing the attribute \\ \hline - \refstruct{pmix_job_state_t} & PMIX_JOB_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_link_state_t} & PMIX_LINK_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_cpuset_t} & PMIX_PROC_CPUSET & \pylabel{cpuset}\{'source': source, 'cpus': bitmap\} & \refarg{source} is a string name of the library that created the cpuset; and \refarg{cpus} is a list of string ranges identifying the \acp{PU} to which the process is bound (e.g., [1, 3-5, 7]) \\ \hline - \refstruct{pmix_locality_t} & PMIX_LOCTYPE & \pylabel{locality}list & list of integer values (defined in Section \ref{api:proc:locality}) describing the relative locality of the specified local process \\ \hline + \refstruct{pmix_rank_t} & \refconst{PMIX_PROC_RANK} & \pylabel{rank}integer & value shall be limited to the \code{uint32_t} range excepting the reserved values near \code{UINT32_MAX} \\ \hline + \refstruct{pmix_proc_t} & \refconst{PMIX_PROC} & \pylabel{proc}\{'nspace': nspace, 'rank': rank\} & \refarg{nspace} is a Python string and \refarg{rank} is an integer value. The \refarg{nspace} string's length shall be limited to one less than the size of the \refstruct{pmix_nspace_t} array (to reserve space for the terminating \code{NULL}), and the \refarg{rank} value shall conform to the constraints associated with \refstruct{pmix_rank_t} \\ \hline + \refstruct{pmix_byte_object_t} & \refconst{PMIX_BYTE_OBJECT} & \pylabel{byteobject}\{'bytes': bytes, 'size': size\} & \refarg{bytes} is a Python byte array and \refarg{size} is the integer number of bytes in that array. \\ \hline + \refstruct{pmix_persistence_t} & \refattr{PMIX_PERSISTENCE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_scope_t} & \refconst{PMIX_SCOPE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_data_range_t} & \refattr{PMIX_RANGE} & \pylabel{range}integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_proc_state_t} & \refconst{PMIX_PROC_STATE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_proc_info_t} & \refconst{PMIX_PROC_INFO} & \{'proc': \{'nspace': nspace, 'rank': rank\}, 'hostname': hostname, 'executable': executable, 'pid': pid, 'exitcode': exitcode, 'state': state\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{hostname} and \refarg{executable} are Python strings; and \refarg{pid}, \refarg{exitcode}, and \refarg{state} are Python integers \\ \hline + \refstruct{pmix_data_array_t} & \refconst{PMIX_DATA_ARRAY} & \pylabel{array}\{'type': type, 'array': array\} & \refarg{type} is the \ac{PMIx} type of object in the array and \refarg{array} is a Python \emph{list} containing the individual array elements. Note that \refarg{array} can consist of \emph{any} \ac{PMIx} types, including (for example) a Python \refpy{info} object that itself contains an \refpy{array} value \\ \hline + \refstruct{pmix_info_directives_t} & \refconst{PMIX_INFO_DIRECTIVES} & \pylabel{info directives}list & list of integer values (defined in Section \ref{api:struct:infodirs}) \\ \hline + \refstruct{pmix_alloc_directive_t} & \refconst{PMIX_ALLOC_DIRECTIVE} & \pylabel{allocdir}integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_iof_channel_t} & \refconst{PMIX_IOF_CHANNEL} & \pylabel{channel}list & list of integer values (defined in Section \ref{api:tool:iofchannels}) \\ \hline + \refstruct{pmix_envar_t} & \refconst{PMIX_ENVAR} & \{'envar': envar, 'value': value, 'separator': separator\} & \refarg{envar} and \refarg{value} are Python strings, and \refarg{separator} a single-character Python string \\ \hline + \refstruct{pmix_value_t} & \refconst{PMIX_VALUE} & \pylabel{value}\{'value': value, 'val_type': type\} & \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline + \refstruct{pmix_info_t} & \refconst{PMIX_INFO} & \pylabel{info}\{'key': key, 'flags': flags, value': value, 'val_type': type\} & \refarg{key} is a Python string \refpy{key}, \refarg{flags} is an \refpy{info directives} value, \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline + \refstruct{pmix_pdata_t} & \refconst{PMIX_PDATA} & \pylabel{pdata}\{'proc': \{'nspace': nspace, 'rank': rank\}, 'key': key, 'value': value, 'val_type': type\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{key} is a Python string \refpy{key}; \refarg{type} is the \ac{PMIx} datatype of \refarg{value}; and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline + \refstruct{pmix_app_t} & \refconst{PMIX_APP} & \pylabel{app}\{'cmd': cmd, 'argv': [argv], 'env': [env], 'maxprocs': maxprocs, 'info': [info]\} & \refarg{cmd} is a Python string; \refarg{argv} and \refarg{env} are Python \emph{lists} containing Python strings; \refarg{maxprocs} is an integer; and \refarg{info} is a Python \emph{list} of \refpy{info} values \\ \hline + \refstruct{pmix_query_t} & \refconst{PMIX_QUERY} & \pylabel{query}\{'keys': [keys], 'qualifiers': [info]\} & \refarg{keys} is a Python \emph{list} of Python strings, and \refarg{qualifiers} is a Python \emph{list} of \refpy{info} values \\ \hline + \refstruct{pmix_regattr_t} & \refconst{PMIX_REGATTR} & \pylabel{regattr}\{'name': name, 'key': key, 'type': type, 'info': [info], 'description': [desc]\} & \refarg{name} and \refarg{string} are Python strings; \refarg{type} is the \ac{PMIx} datatype for the attribute's value; \refarg{info} is a Python \emph{list} of \refpy{info} values; and \refarg{description} is a list of Python strings describing the attribute \\ \hline + \refstruct{pmix_job_state_t} & \refconst{PMIX_JOB_STATE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_link_state_t} & \refconst{PMIX_LINK_STATE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_cpuset_t} & \refconst{PMIX_PROC_CPUSET} & \pylabel{cpuset}\{'source': source, 'cpus': bitmap\} & \refarg{source} is a string name of the library that created the cpuset; and \refarg{cpus} is a list of string ranges identifying the \acp{PU} to which the process is bound (e.g., [1, 3-5, 7]) \\ \hline + \refstruct{pmix_locality_t} & \refconst{PMIX_LOCTYPE} & \pylabel{locality}list & list of integer values (defined in Section \ref{api:proc:locality}) describing the relative locality of the specified local process \\ \hline \refstruct{pmix_fabric_t} & N/A & \pylabel{fabric}\{'name': name, 'index': idx, 'info': [info]\} & \refarg{name} is the string name assigned to the fabric; \refarg{index} is the integer ID assigned to the fabric; \refarg{info} is a list of \refpy{info} describing the fabric \\ \hline - \refstruct{pmix_endpoint_t} & PMIX_ENDPOINT & \pylabel{endpoint}\{'uuid': uuid, 'osname': osname, endpt': endpt\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; \refarg{endpt} is a \refpy{byteobject} containing the endpoint information \\ \hline - \refstruct{pmix_device_distance_t} & PMIX_DEVICE_DIST & \pylabel{devdist}\{'uuid': uuid, 'osname': osname, mindist': mindist, 'maxdist': maxdist\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{mindist} and \refarg{maxdist} are Python integers \\ \hline - \refstruct{pmix_coord_t} & PMIX_COORD & \pylabel{coord}\{'view': view, 'coord': [coords]\} & \refarg{view} is the \refstruct{pmix_coord_view_t} of the coordinate; and \refarg{coord} is a list of integer coordinates, one for each dimension of the fabric \\ \hline - \refstruct{pmix_geometry_t} & PMIX_GEOMETRY & \pylabel{geometry}\{'fabric': idx, 'uuid': uuid, 'osname': osname, coordinates': [coords]\} & \refarg{fabric} is the Python integer index of the fabric; \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{coordinates} is a list of \refpy{coord} containing the coordinates for the device across all views \\ \hline - \refstruct{pmix_device_type_t} & PMIX_DEVTYPE & \pylabel{devtype}list & list of integer values (defined in Section \ref{api:proc:devtype}) \\ \hline + \refstruct{pmix_endpoint_t} & \refconst{PMIX_ENDPOINT} & \pylabel{endpoint}\{'uuid': uuid, 'osname': osname, endpt': endpt\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; \refarg{endpt} is a \refpy{byteobject} containing the endpoint information \\ \hline + \refstruct{pmix_device_distance_t} & \refconst{PMIX_DEVICE_DIST} & \pylabel{devdist}\{'uuid': uuid, 'osname': osname, mindist': mindist, 'maxdist': maxdist\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{mindist} and \refarg{maxdist} are Python integers \\ \hline + \refstruct{pmix_coord_t} & \refconst{PMIX_COORD} & \pylabel{coord}\{'view': view, 'coord': [coords]\} & \refarg{view} is the \refstruct{pmix_coord_view_t} of the coordinate; and \refarg{coord} is a list of integer coordinates, one for each dimension of the fabric \\ \hline + \refstruct{pmix_geometry_t} & \refconst{PMIX_GEOMETRY} & \pylabel{geometry}\{'fabric': idx, 'uuid': uuid, 'osname': osname, coordinates': [coords]\} & \refarg{fabric} is the Python integer index of the fabric; \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{coordinates} is a list of \refpy{coord} containing the coordinates for the device across all views \\ \hline + \refstruct{pmix_device_type_t} & \refconst{PMIX_DEVTYPE} & \pylabel{devtype}list & list of integer values (defined in Section \ref{api:proc:devtype}) \\ \hline \refstruct{pmix_bind_envelope_t} & N/A & \pylabel{bindenv}integer & one of the values defined in Section \ref{api:proc:bindenv} \\ \hline \end{longtable} \end{small} @@ -148,6 +148,7 @@ \section{Callback Function Definitions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{IOF Delivery Function} \pylabel{iofcbfunc} +\declareapibinding{iofcbfunc}{pmix_iof_cbfunc_t}{Python} %%%% \summary @@ -181,6 +182,7 @@ \subsection{IOF Delivery Function} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Event Handler} \pylabel{evhandler} +\declareapibinding{evhandler}{pmix_notification_fn_t}{Python} %%%% \summary @@ -224,6 +226,7 @@ \subsection{Server Module Functions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Client Connected} +\declareapibinding{clientconnected2}{pmix_server_client_connected2_fn_t}{Python} %%%% \summary @@ -255,6 +258,7 @@ \subsubsection{Client Connected} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Client Finalized} +\declareapibinding{clientfinalized}{pmix_server_client_finalized_fn_t}{Python} %%%% \summary @@ -282,6 +286,7 @@ \subsubsection{Client Finalized} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Client Aborted} +\declareapibinding{clientaborted}{pmix_server_abort_fn_t}{Python} %%%% \summary @@ -318,6 +323,7 @@ \subsubsection{Client Aborted} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Fence} +\declareapibinding{fence}{pmix_server_fencenb_fn_t}{Python} %%%% \summary @@ -354,6 +360,7 @@ \subsubsection{Fence} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Direct Modex} +\declareapibinding{dmodex}{pmix_server_dmodex_req_fn_t}{Python} %%%% \summary @@ -389,6 +396,7 @@ \subsubsection{Direct Modex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Publish} +\declareapibinding{publish}{pmix_server_publish_fn_t}{Python} %%%% \summary @@ -423,6 +431,7 @@ \subsubsection{Publish} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Lookup} +\declareapibinding{lookup}{pmix_server_lookup_fn_t}{Python} %%%% \summary @@ -459,6 +468,7 @@ \subsubsection{Lookup} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Unpublish} +\declareapibinding{unpublish}{pmix_server_unpublish_fn_t}{Python} %%%% \summary @@ -494,6 +504,7 @@ \subsubsection{Unpublish} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Spawn} +\declareapibinding{spawn}{pmix_server_spawn_fn_t}{Python} %%%% \summary @@ -530,6 +541,7 @@ \subsubsection{Spawn} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Connect} +\declareapibinding{connect}{pmix_server_connect_fn_t}{Python} %%%% \summary @@ -564,6 +576,7 @@ \subsubsection{Connect} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Disconnect} +\declareapibinding{disconnect}{pmix_server_disconnect_fn_t}{Python} %%%% \summary @@ -598,6 +611,7 @@ \subsubsection{Disconnect} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Register Events} +\declareapibinding{register_events}{pmix_server_register_events_fn_t}{Python} %%%% \summary @@ -632,6 +646,7 @@ \subsubsection{Register Events} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Deregister Events} +\declareapibinding{deregister_events}{pmix_server_deregister_events_fn_t}{Python} %%%% \summary @@ -665,6 +680,7 @@ \subsubsection{Deregister Events} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Notify Event} +\declareapibinding{notify_event}{pmix_server_notify_event_fn_t}{Python} %%%% \summary @@ -701,6 +717,7 @@ \subsubsection{Notify Event} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Query} +\declareapibinding{query}{pmix_server_query_fn_t}{Python} %%%% \summary @@ -736,6 +753,7 @@ \subsubsection{Query} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Tool Connected} +\declareapibinding{tool_connected}{pmix_server_tool_connection_fn_t}{Python} %%%% \summary @@ -770,6 +788,7 @@ \subsubsection{Tool Connected} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Log} +\declareapibinding{log}{pmix_server_log_fn_t}{Python} %%%% \summary @@ -805,6 +824,7 @@ \subsubsection{Log} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Allocate Resources} +\declareapibinding{allocate}{pmix_server_alloc_fn_t}{Python} %%%% \summary @@ -841,6 +861,7 @@ \subsubsection{Allocate Resources} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Job Control} +\declareapibinding{job_control}{pmix_server_job_control_fn_t}{Python} %%%% \summary @@ -876,6 +897,7 @@ \subsubsection{Job Control} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Monitor} +\declareapibinding{monitor}{pmix_server_monitor_fn_t}{Python} %%%% \summary @@ -912,6 +934,7 @@ \subsubsection{Monitor} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Get Credential} +\declareapibinding{get_credential}{pmix_server_get_cred_fn_t}{Python} %%%% \summary @@ -948,6 +971,7 @@ \subsubsection{Get Credential} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Validate Credential} +\declareapibinding{validate_credential}{pmix_server_validate_cred_fn_t}{Python} %%%% \summary @@ -984,6 +1008,7 @@ \subsubsection{Validate Credential} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{IO Forward} +\declareapibinding{iof_pull}{pmix_server_iof_fn_t}{Python} %%%% \summary @@ -1019,6 +1044,7 @@ \subsubsection{IO Forward} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{IO Push} +\declareapibinding{iof_push}{pmix_server_stdin_fn_t}{Python} %%%% \summary @@ -1055,6 +1081,7 @@ \subsubsection{IO Push} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Group Operations} +\declareapibinding{group}{pmix_server_grp_fn_t}{Python} %%%% \summary @@ -1092,6 +1119,7 @@ \subsubsection{Group Operations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Fabric Operations} +\declareapibinding{fabric}{pmix_server_fabric_fn_t}{Python} %%%% \summary @@ -1710,7 +1738,7 @@ \subsection{Client.resolve_nodes} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Client.query} -\declareapibinding{PMIxClient.query}{PMIx_Query_info_nb}{Python} +\declareapibinding{PMIxClient.query}{PMIx_Query_info}{Python} %%%% \summary @@ -1738,7 +1766,7 @@ \subsection{Client.query} \item \refarg{info} - List of Python \refpy{info} containing results of the query (list) \end{itemize} -See \refapi{PMIx_Query_info_nb} for description of all relevant attributes and behaviors. +See \refapi{PMIx_Query_info} for description of all relevant attributes and behaviors. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1775,8 +1803,8 @@ \subsection{Client.log} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Client.allocate} -\declareapibinding{PMIxClient.allocate}{PMIx_Allocation_request_nb}{Python} +\subsection{Client.allocation_request} +\declareapibinding{PMIxClient.allocation_request}{PMIx_Allocation_request}{Python} %%%% \summary @@ -1789,7 +1817,7 @@ \subsection{Client.allocate} \versionMarker{4.0} \pyspecificstart \begin{codepar} -rc,info = myclient.allocate(request:integer, directives:list) +rc,info = myclient.allocation_request(request:integer, directives:list) \end{codepar} \pyspecificend @@ -1805,12 +1833,12 @@ \subsection{Client.allocate} \item \refarg{info} - List of Python \refpy{info} containing results of the request (list) \end{itemize} -See \refapi{PMIx_Allocation_request_nb} for description of all relevant attributes and behaviors. +See \refapi{PMIx_Allocation_request} for description of all relevant attributes and behaviors. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Client.job_ctrl} -\declareapibinding{PMIxClient.job_ctrl}{PMIx_Job_control_nb}{Python} +\declareapibinding{PMIxClient.job_ctrl}{PMIx_Job_control}{Python} %%%% \summary @@ -1839,12 +1867,12 @@ \subsection{Client.job_ctrl} \item \refarg{info} - List of Python \refpy{info} containing results of the request (list) \end{itemize} -See \refapi{PMIx_Job_control_nb} for description of all relevant attributes and behaviors. +See \refapi{PMIx_Job_control} for description of all relevant attributes and behaviors. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Client.monitor} -\declareapibinding{PMIxClient.monitor}{PMIx_Process_monitor_nb}{Python} +\declareapibinding{PMIxClient.monitor}{PMIx_Process_monitor}{Python} %%%% \summary @@ -1874,7 +1902,7 @@ \subsection{Client.monitor} \item \refarg{info} - List of Python \refpy{info} containing results of the request (list) \end{itemize} -See \refapi{PMIx_Process_monitor_nb} for description of all relevant attributes and behaviors. +See \refapi{PMIx_Process_monitor} for description of all relevant attributes and behaviors. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2400,6 +2428,36 @@ \subsection{Client.get_cpuset} See \refapi{PMIx_Get_cpuset} for details. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Client.parse_cpuset_string} +\declareapibinding{PMIxClient.parse_cpuset_string}{PMIx_Parse_cpuset_string}{Python} + +\summary +Parse the \ac{PU} binding bitmap from its string representation. + +\format + +\versionMarker{4.0} +\pyspecificstart +\begin{codepar} +rc,cpuset = myclient.parse_cpuset_string(cpuset:string) +\end{codepar} +\pyspecificend + +\begin{arglist} +\argin{cpuset}{String returned by \refapibinding{PMIxServer.generate_cpuset_string} (string)} +\end{arglist} + + +Returns: + +\begin{itemize} + \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer) + \item \refarg{cpuset} - \refpy{cpuset} containing the source and bitmap of the cpuset (dict) +\end{itemize} + +See \refapi{PMIx_Parse_cpuset_string} for details. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Client.compute_distances} @@ -2917,7 +2975,7 @@ \subsection{Server.init} \begin{arglist} \argin{directives}{List of Python \refpy{info} dictionaries (list)} -\argin{map}{Python dictionary key-function pairs that map \refpy{server module} callback functions to provided implementations (dict)} +\argin{map}{Python dictionary key-function pairs that map \refpy{server module} callback functions to provided implementations (see \refapi{pmix_server_module_t}) (dict)} \end{arglist} Returns: @@ -3016,6 +3074,67 @@ \subsection{Server.generate_ppn} See \refapi{PMIx_generate_ppn} for details. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Server.generate_locality_string} +\declareapibinding{PMIxServer.generate_locality_string}{PMIx_server_generate_locality_string}{Python} + +\summary +Generate a PMIx locality string from a given cpuset. + +\format + +\versionMarker{4.0} +\pyspecificstart +\begin{codepar} +rc,locality = myserver.generate_locality_string(cpuset:dict) +\end{codepar} +\pyspecificend + + +\begin{arglist} +\argin{cset}{\refpy{cpuset} containing the bitmap of assigned PUs (dict)} +\end{arglist} + +Returns: + +\begin{itemize} + \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer) + \item \refarg{locality} - String representation of the PMIx locality corresponding to the input bitmap (string) +\end{itemize} + +See \refapi{PMIx_server_generate_locality_string} for details. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Server.generate_cpuset_string} +\declareapibinding{PMIxServer.generate_cpuset_string}{PMIx_server_generate_cpuset_string}{Python} + +\summary +Generate a PMIx string representation of the provided cpuset. + +\format + +\versionMarker{4.0} +\pyspecificstart +\begin{codepar} +rc,cpustr = myserver.generate_cpuset_string(cpuset:dict) +\end{codepar} +\pyspecificend + + +\begin{arglist} +\argin{cset}{\refpy{cpuset} containing the bitmap of assigned PUs (dict)} +\end{arglist} + +Returns: + +\begin{itemize} + \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer) + \item \refarg{cpustr} - String representation of the input bitmap (string) +\end{itemize} + +See \refapi{PMIx_server_generate_cpuset_string} for details. + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Server.register_nspace} \declareapibinding{PMIxServer.register_nspace}{PMIx_server_register_nspace}{Python} @@ -3733,12 +3852,13 @@ \subsection{Tool.set_server} \versionMarker{4.0} \pyspecificstart \begin{codepar} -rc = mytool.set_server(proc:dict) +rc = mytool.set_server(proc:dict, info:list) \end{codepar} \pyspecificend \begin{arglist} -\argin{proc}{Python \refpy{proc} containing the identifier of the servers\ to which the tool is to attach (list)} +\argin{proc}{Python \refpy{proc} containing the identifier of the servers to which the tool is to attach (list)} +\argin{info}{List of Python \refpy{info} dictionaries (list)} \end{arglist} Returns: diff --git a/Chap_API_Proc_Mgmt.tex b/Chap_API_Proc_Mgmt.tex index 330cd075..3cb67919 100644 --- a/Chap_API_Proc_Mgmt.tex +++ b/Chap_API_Proc_Mgmt.tex @@ -335,7 +335,7 @@ \subsection{Spawn-specific constants} \subsection{Spawn attributes} \label{api:struct:attributes:spawn} -Attributes used to describe \refapi{PMIx_Spawn} behavior - they are values passed to the \refapi{PMIx_Spawn} \ac{API} and therefore are not accessed using the \refapi{PMIx_Get} \acp{API} when used in that context. However, some of the attributes defined in this section can be provided by the host environment for other purposes - e.g., the host might provide the \refattr{PMIX_MAPPER} attribute in the job-related information so that an application can use \refapi{PMIx_Get} to discover the layout algorithm used for determining process locations. Multi-use attributes and their respective access reference rank are denoted below. +Attributes used to describe \refapi{PMIx_Spawn} behavior - they are values passed to the \refapi{PMIx_Spawn} \ac{API} and therefore are not accessed using the \refapi{PMIx_Get} \acp{API} when used in that context. However, some of the attributes defined in this section can be provided by the host environment for other purposes - e.g., the host might provide the \refattr{PMIX_MAPBY} attribute in the job-related information so that an application can use \refapi{PMIx_Get} to discover the mapping used for determining process locations. Multi-use attributes and their respective access reference rank are denoted below. % \declareAttribute{PMIX_PERSONALITY}{"pmix.pers"}{char*}{ diff --git a/Chap_API_Security.tex b/Chap_API_Security.tex index 60c69e47..50af3fc0 100644 --- a/Chap_API_Security.tex +++ b/Chap_API_Security.tex @@ -8,7 +8,7 @@ \chapter{Security} When the client attempts to connect to the \ac{PMIx} server, the server shall use available standard \ac{OS} methods to determine the effective \ac{UID}/\ac{GID} of the process requesting the connection. \ac{PMIx} implementations shall not rely on any values reported by the client process itself. The effective \ac{UID}/\ac{GID} reported by the \ac{OS} is compared to the values provided by the host during registration - if the values fail to match, the \ac{PMIx} server is required to drop the connection request. This ensures that the \ac{PMIx} server does not allow connection from a client that doesn't at least meet some minimal security requirement. -Once the requesting client passes the initial test, the \ac{PMIx} server can, at the choice of the implementor, perform additional security checks. This may involve a variety of methods such as exchange of a system-provided key or credential. At the conclusion of that process, the \ac{PMIx} server reports the client connection request to the host via the \refapi{pmix_server_client_connected_fn_t} interface, if provided. The host may perform any additional checks and operations before responding with either \refconst{PMIX_SUCCESS} to indicate that the connection is approved, or a \ac{PMIx} error constant indicating that the connection request is refused. In this latter case, the \ac{PMIx} server is required to drop the connection. +Once the requesting client passes the initial test, the \ac{PMIx} server can, at the choice of the implementor, perform additional security checks. This may involve a variety of methods such as exchange of a system-provided key or credential. At the conclusion of that process, the \ac{PMIx} server reports the client connection request to the host via the \refapi{pmix_server_client_connected2_fn_t} interface, if provided. The host may perform any additional checks and operations before responding with either \refconst{PMIX_SUCCESS} to indicate that the connection is approved, or a \ac{PMIx} error constant indicating that the connection request is refused. In this latter case, the \ac{PMIx} server is required to drop the connection. Tools started by the host environment are classed as a subgroup of client processes and follow the client process procedure. However, tools that are not started by the host environment must be handled differently as registration information is not available prior to the connection request. In these cases, the \ac{PMIx} server library is required to use available standard \ac{OS} methods to get the effective \ac{UID}/\ac{GID} of the tool and report them upwards as part of invoking the \refapi{pmix_server_tool_connection_fn_t} interface, deferring initial security screening to the host. Host environments willing to accept tool connections must therefore both explicitly enable them via the \refattr{PMIX_SERVER_TOOL_SUPPORT} attribute, thereby confirming acceptance of the authentication and authorization burden, and provide the \refapi{pmix_server_tool_connection_fn_t} server module function pointer. diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index 3f2544a1..9a6e4963 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -1017,11 +1017,11 @@ \subsection{\code{PMIx_server_register_client}} The host server can also, if it desires, provide an object it wishes to be returned when a server function is called that relates to a specific process. For example, the host server may have an object that tracks the specific client. -Passing the object to the library allows the library to provide that object to the host server during subsequent calls related to that client, such as a \refapi{pmix_server_client_connected_fn_t} function. This allows the host server to access the object without performing a lookup based on the client's namespace and rank. +Passing the object to the library allows the library to provide that object to the host server during subsequent calls related to that client, such as a \refapi{pmix_server_client_connected2_fn_t} function. This allows the host server to access the object without performing a lookup based on the client's namespace and rank. \advicermstart Host environments are required to execute this operation prior to starting the client process. -The expected user ID and group ID of the child process allows the server library to properly authenticate clients as they connect by requiring the two values to match. Accordingly, the detected user and group ID's of the connecting process are not included in the \refapi{pmix_server_client_connected_fn_t} server module function. +The expected user ID and group ID of the child process allows the server library to properly authenticate clients as they connect by requiring the two values to match. Accordingly, the detected user and group ID's of the connecting process are not included in the \refapi{pmix_server_client_connected2_fn_t} server module function. \advicermend \adviceimplstart @@ -2832,13 +2832,11 @@ \subsection{\code{pmix_server_spawn_fn_t}} \pasteAttributeItem{PMIX_PRELOAD_BIN} \pasteAttributeItem{PMIX_PRELOAD_FILES} \pasteAttributeItem{PMIX_PERSONALITY} -\pasteAttributeItem{PMIX_MAPPER} \pasteAttributeItem{PMIX_DISPLAY_MAP} \pasteAttributeItem{PMIX_PPR} \pasteAttributeItem{PMIX_MAPBY} \pasteAttributeItem{PMIX_RANKBY} \pasteAttributeItem{PMIX_BINDTO} -\pasteAttributeItem{PMIX_NON_PMI} \pasteAttributeItem{PMIX_STDIN_TGT} \pasteAttributeItem{PMIX_FWD_STDIN} \pasteAttributeItem{PMIX_FWD_STDOUT} @@ -3694,7 +3692,7 @@ \subsection{\code{pmix_server_job_control_fn_t}} \argin{ntargets}{Number of elements in the \refarg{targets} array (integer)} \argin{directives}{Array of info structures (array of handles)} \argin{ndirs}{Number of elements in the \refarg{info} array (integer)} -\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)} +\argin{cbfunc}{Callback function \refapi{pmix_info_cbfunc_t} (function reference)} \argin{cbdata}{Data to be passed to the callback function (memory reference)} \end{arglist} @@ -3785,7 +3783,7 @@ \subsection{\code{pmix_server_monitor_fn_t}} \argin{error}{Status code to use in generating event if alarm triggers (integer)} \argin{directives}{Array of info structures (array of handles)} \argin{ndirs}{Number of elements in the \refarg{info} array (integer)} -\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)} +\argin{cbfunc}{Callback function \refapi{pmix_info_cbfunc_t} (function reference)} \argin{cbdata}{Data to be passed to the callback function (memory reference)} \end{arglist} diff --git a/Chap_API_Struct.tex b/Chap_API_Struct.tex index 2e56b995..250c067a 100644 --- a/Chap_API_Struct.tex +++ b/Chap_API_Struct.tex @@ -2215,7 +2215,7 @@ \subsection{Op Callback Function} %%%% \descr -Used by a wide range of \ac{PMIx} API's including \refapi{PMIx_Fence_nb}, \refapi{pmix_server_client_connected_fn_t}, \refapi{PMIx_server_register_nspace}. +Used by a wide range of \ac{PMIx} API's including \refapi{PMIx_Fence_nb}, \refapi{pmix_server_client_connected2_fn_t}, \refapi{PMIx_server_register_nspace}. This callback function is used to return a status to an often nonblocking operation. diff --git a/Chap_API_Sync_Access.tex b/Chap_API_Sync_Access.tex index abb7e0bf..fd2c7d15 100644 --- a/Chap_API_Sync_Access.tex +++ b/Chap_API_Sync_Access.tex @@ -556,8 +556,6 @@ \subsection{\code{PMIx_Query_info}} \pasteAttributeItem{PMIX_TIME_REMAINING} \pasteAttributeItemBegin{PMIX_SERVER_URI} Requests the URI of the specified \ac{PMIx} server's \ac{PMIx} connection. Defaults to requesting the information for the local \ac{PMIx} server. \pasteAttributeItemEnd -\pasteAttributeItemBegin{PMIX_PROC_URI} Requests the URI of the specified \ac{PMIx} server's out-of-band connection. Defaults to requesting the information for the local \ac{PMIx} server. -\pasteAttributeItemEnd \pasteAttributeItem{PMIX_CLIENT_AVG_MEMORY} \pasteAttributeItem{PMIX_DAEMON_MEMORY} \pasteAttributeItem{PMIX_QUERY_AUTHORIZATIONS} @@ -676,8 +674,6 @@ \subsection{\code{PMIx_Query_info_nb}} \pasteAttributeItem{PMIX_TIME_REMAINING} \pasteAttributeItemBegin{PMIX_SERVER_URI} Requests the URI of the specified \ac{PMIx} server's \ac{PMIx} connection. Defaults to requesting the information for the local \ac{PMIx} server. \pasteAttributeItemEnd -\pasteAttributeItemBegin{PMIX_PROC_URI} Requests the URI of the specified \ac{PMIx} server's out-of-band connection. Defaults to requesting the information for the local \ac{PMIx} server. -\pasteAttributeItemEnd \pasteAttributeItem{PMIX_CLIENT_AVG_MEMORY} \pasteAttributeItem{PMIX_DAEMON_MEMORY} \pasteAttributeItem{PMIX_QUERY_AUTHORIZATIONS} @@ -1026,7 +1022,7 @@ \section{Using Get vs Query} \section{Accessing attribute support information} \label{chap:api_job_mgmt:queryattrs} -Information as to which attributes are supported by either the \ac{PMIx} implementation or its host environment can be obtained via the \refapi{PMIx_Query_info} \acp{API}. The \refattr{PMIX_QUERY_ATTRIBUTE_SUPPORT} attribute must be listed as the first entry in the \refarg{keys} field of the \refstruct{pmix_query_t} structure, followed by the name of the function whose attribute support is being requested - support for multiple functions can be requested simultaneously by simply adding the function names to the array of \refarg{keys}. Function names \emph{must} be given as user-level \ac{API} names - e.g., ``PMIx_Get'', ``PMIx_server_setup_application'', or ``PMIx_tool_connect_to_server''. +Information as to which attributes are supported by either the \ac{PMIx} implementation or its host environment can be obtained via the \refapi{PMIx_Query_info} \acp{API}. The \refattr{PMIX_QUERY_ATTRIBUTE_SUPPORT} attribute must be listed as the first entry in the \refarg{keys} field of the \refstruct{pmix_query_t} structure, followed by the name of the function whose attribute support is being requested - support for multiple functions can be requested simultaneously by simply adding the function names to the array of \refarg{keys}. Function names \emph{must} be given as user-level \ac{API} names - e.g., ``PMIx_Get'', ``PMIx_server_setup_application'', or ``PMIx_tool_attach_to_server''. The desired levels of attribute support are provided as qualifiers. Multiple levels can be requested simultaneously by simply adding elements to the \refarg{qualifiers} array. Each qualifier should contain the desired level attribute with the boolean value set to indicate whether or not that level is to be included in the returned information. Failure to provide any levels is equivalent to a request for all levels. Supported levels include: diff --git a/Chap_API_Tools.tex b/Chap_API_Tools.tex index 7316a86b..a52c1d66 100644 --- a/Chap_API_Tools.tex +++ b/Chap_API_Tools.tex @@ -193,6 +193,7 @@ \subsection{Tool initialization environmental variables} \subsection{Tool connection attributes} \label{api:struct:attributes:connection} + These attributes are defined to assist \ac{PMIx}-enabled tools to connect with a \ac{PMIx} server by passing them into either the \refapi{PMIx_tool_init} or the \refapi{PMIx_tool_attach_to_server} \acp{API} - thus, they are not typically accessed via the \refapi{PMIx_Get} \ac{API}. % diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index 0cb34bc8..cdb1b770 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -78,7 +78,7 @@ \section{Version 2.0: Sept. 2018} \subsection{Removed/Modified \acp{API}} The \refapi{PMIx_Init} \ac{API} was modified in v2.0 of the standard from its \textit{ad hoc} v1.0 signature to include passing of a \refstruct{pmix_info_t} array for flexibility and ``future-proofing'' of the \ac{API}. -In addition, the PMIx_Notify_error, PMIx_Register_errhandler, and PMIx_Deregister_errhandler \acp{API} were replaced. This pre-dated official adoption of \ac{PMIx} as a Standard. +In addition, the \code{PMIx_Notify_error}, \code{PMIx_Register_errhandler}, and \code{PMIx_Deregister_errhandler} \acp{API} were replaced. This pre-dated official adoption of \ac{PMIx} as a Standard. \subsection{Deprecated constants} @@ -210,7 +210,7 @@ \subsection{Removed constants} The following constants were removed in v3.0: -\refconst{PMIX_MODEX} +\refconst{PMIX_MODEX}\\ \refconst{PMIX_INFO_ARRAY} \subsection{Deprecated attributes} @@ -226,43 +226,43 @@ \subsection{Removed attributes} The following attributes were removed in v3.0: % -\declareAttributeDEP{PMIX_ERROR_NAME}{"pmix.errname"}{pmix_status_t}{ +\declareAttributeRM{PMIX_ERROR_NAME}{"pmix.errname"}{pmix_status_t}{ Specific error to be notified } % -\declareAttributeDEP{PMIX_ERROR_GROUP_COMM}{"pmix.errgroup.comm"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_COMM}{"pmix.errgroup.comm"}{bool}{ Set true to get comm errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_ABORT}{"pmix.errgroup.abort"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_ABORT}{"pmix.errgroup.abort"}{bool}{ Set true to get abort errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_MIGRATE}{"pmix.errgroup.migrate"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_MIGRATE}{"pmix.errgroup.migrate"}{bool}{ Set true to get migrate errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_RESOURCE}{"pmix.errgroup.resource"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_RESOURCE}{"pmix.errgroup.resource"}{bool}{ Set true to get resource errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_SPAWN}{"pmix.errgroup.spawn"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_SPAWN}{"pmix.errgroup.spawn"}{bool}{ Set true to get spawn errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_NODE}{"pmix.errgroup.node"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_NODE}{"pmix.errgroup.node"}{bool}{ Set true to get node status notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_LOCAL}{"pmix.errgroup.local"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_LOCAL}{"pmix.errgroup.local"}{bool}{ Set true to get local errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_GENERAL}{"pmix.errgroup.gen"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_GENERAL}{"pmix.errgroup.gen"}{bool}{ Set true to get notified of generic errors } % -\declareAttributeDEP{PMIX_ERROR_HANDLER_ID}{"pmix.errhandler.id"}{int}{ +\declareAttributeRM{PMIX_ERROR_HANDLER_ID}{"pmix.errhandler.id"}{int}{ Errhandler reference id of notification being reported } @@ -303,6 +303,175 @@ \section{Version 3.2: Oct. 2020} \item Add a new \refconst{PMIX_REGEX} constant that represents a regular expression data type. \end{compactitemize} + +\subsection{Deprecated constants} + +The following constants were deprecated in v3.2: + +\begin{constantdesc} +% +\declareconstitemDEP{PMIX_ERR_DATA_VALUE_NOT_FOUND} +Data value not found +% +\declareconstitemDEP{PMIX_ERR_HANDSHAKE_FAILED} +Connection handshake failed +% +\declareconstitemDEP{PMIX_ERR_IN_ERRNO} +Error defined in \code{errno} +% +\declareconstitemDEP{PMIX_ERR_INVALID_ARG} +Invalid argument +% +\declareconstitemDEP{PMIX_ERR_INVALID_ARGS} +Invalid arguments +% +\declareconstitemDEP{PMIX_ERR_INVALID_KEY} +Invalid key +% +\declareconstitemDEP{PMIX_ERR_INVALID_KEY_LENGTH} +Invalid key length +% +\declareconstitemDEP{PMIX_ERR_INVALID_KEYVALP} +Invalid key/value pair +% +\declareconstitemDEP{PMIX_ERR_INVALID_LENGTH} +Invalid argument length +% +\declareconstitemDEP{PMIX_ERR_INVALID_NAMESPACE} +Invalid namespace +% +\declareconstitemDEP{PMIX_ERR_INVALID_NUM_ARGS} +Invalid number of arguments +% +\declareconstitemDEP{PMIX_ERR_INVALID_NUM_PARSED} +Invalid number parsed +% +\declareconstitemDEP{PMIX_ERR_INVALID_SIZE} +Invalid size +% +\declareconstitemDEP{PMIX_ERR_INVALID_VAL} +Invalid value +% +\declareconstitemDEP{PMIX_ERR_INVALID_VAL_LENGTH} +Invalid value length +% +\declareconstitemDEP{PMIX_ERR_NOT_IMPLEMENTED} +Not implemented +% +\declareconstitemDEP{PMIX_ERR_PACK_MISMATCH} +Pack mismatch +% +\declareconstitemDEP{PMIX_ERR_PROC_ENTRY_NOT_FOUND} +Process not found +% +\declareconstitemDEP{PMIX_ERR_PROC_REQUESTED_ABORT} +Process is already requested to abort +% +\declareconstitemDEP{PMIX_ERR_READY_FOR_HANDSHAKE} +Ready for handshake +% +\declareconstitemDEP{PMIX_ERR_SERVER_FAILED_REQUEST} +Failed to connect to the server +% +\declareconstitemDEP{PMIX_ERR_SERVER_NOT_AVAIL} +Server is not available +% +\declareconstitemDEP{PMIX_ERR_SILENT} +Silent error +% +\declareconstitemDEP{PMIX_GDS_ACTION_COMPLETE} +The \ac{GDS} action has completed +% +\declareconstitemDEP{PMIX_NOTIFY_ALLOC_COMPLETE} +Notify that a requested allocation operation is complete - the result of +the request will be included in the \refarg{info} array +% +\end{constantdesc} + + +\subsection{Deprecated attributes} + +The following attributes were deprecated in v3.2: + +\declareAttributeDEP{PMIX_ARCH}{"pmix.arch"}{uint32_t}{ +Architecture flag. +} +% +\declareAttributeDEP{PMIX_COLLECTIVE_ALGO}{"pmix.calgo"}{char*}{ +Comma-delimited list of algorithms to use for the collective operation. \ac{PMIx} does not impose any requirements on a host environment's collective algorithms. Thus, the acceptable values for this attribute will be environment-dependent - users are encouraged to check their host environment for supported values. +} +% +\declareAttributeDEP{PMIX_DSTPATH}{"pmix.dstpath"}{char*}{ +Path to shared memory data storage (dstore) files. Deprecated from Standard as being implementation specific. +} +% +\declareAttributeDEP{PMIX_HWLOC_HOLE_KIND}{"pmix.hwlocholek"}{char*}{ +Kind of VM ``hole'' HWLOC should use for shared memory +} +% +\declareAttributeDEP{PMIX_HWLOC_SHARE_TOPO}{"pmix.hwlocsh"}{bool}{ +Share the HWLOC topology via shared memory +} +% +\declareAttributeDEP{PMIX_HWLOC_SHMEM_ADDR}{"pmix.hwlocaddr"}{size_t}{ +Address of the HWLOC shared memory segment. +} +% +\declareAttributeDEP{PMIX_HWLOC_SHMEM_FILE}{"pmix.hwlocfile"}{char*}{ +Path to the HWLOC shared memory file. +} +% +\declareAttributeDEP{PMIX_HWLOC_SHMEM_SIZE}{"pmix.hwlocsize"}{size_t}{ +Size of the HWLOC shared memory segment. +} +% +\declareAttributeDEP{PMIX_HWLOC_XML_V1}{"pmix.hwlocxml1"}{char*}{ +\ac{XML} representation of local topology using HWLOC's v1.x format. +} +% +\declareAttributeDEP{PMIX_HWLOC_XML_V2}{"pmix.hwlocxml2"}{char*}{ +\ac{XML} representation of local topology using HWLOC's v2.x format. +} +% +\declareAttributeDEP{PMIX_LOCAL_TOPO}{"pmix.ltopo"}{char*}{ +\ac{XML} representation of local node topology. +} +% +\declareAttributeDEP{PMIX_MAPPER}{"pmix.mapper"}{char*}{ +Mapping mechanism to use for placing spawned processes - when accessed using \refapi{PMIx_Get}, use the \refconst{PMIX_RANK_WILDCARD} value for the rank to discover the mapping mechanism used for the provided namespace. +} +% +\declareAttributeDEP{PMIX_MAP_BLOB}{"pmix.mblob"}{pmix_byte_object_t}{ +Packed blob of process location. +} +% +\declareAttributeDEP{PMIX_NON_PMI}{"pmix.nonpmi"}{bool}{ +Spawned processes will not call \refapi{PMIx_Init}. +} +% +\declareAttributeDEP{PMIX_PROC_BLOB}{"pmix.pblob"}{pmix_byte_object_t}{ +Packed blob of process data. +} +% +\declareAttributeDEP{PMIX_PROC_URI}{"pmix.puri"}{char*}{ +\ac{URI} containing contact information for the specified process. +} +% +\declareAttributeDEP{PMIX_TOPOLOGY_FILE}{"pmix.topo.file"}{char*}{ +Full path to file containing \ac{XML} topology description +} +% +\declareAttributeDEP{PMIX_TOPOLOGY_SIGNATURE}{"pmix.toposig"}{char*}{ +Topology signature string. +} +% +\declareAttributeDEP{PMIX_TOPOLOGY_XML}{"pmix.topo.xml"}{char*}{ +\ac{XML}-based description of topology +} +% + + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%% History: Version 4.0 \section{Version 4.0: Nov. 2020} @@ -717,7 +886,7 @@ \subsection{Deprecated \acp{API}} \declareapiDEP{pmix_evhdlr_reg_cbfunc_t} Renamed to \refapi{pmix_hdlr_reg_cbfunc_t} -The \refapi{pmix_server_client_connected_fn_t} server module entry point has +The \refapiDEP{pmix_server_client_connected_fn_t} server module entry point has been \emph{deprecated} in favor of \refapi{pmix_server_client_connected2_fn_t} @@ -786,80 +955,80 @@ \subsection{Removed constants} as they are internal to a particular \ac{PMIx} implementation. \begin{constantdesc} -% -\declareconstitemDEP{PMIX_ERR_HANDSHAKE_FAILED} +%!TEX encoding = UTF-8 Unicode +\declareconstitemRM{PMIX_ERR_HANDSHAKE_FAILED} Connection handshake failed % -\declareconstitemDEP{PMIX_ERR_READY_FOR_HANDSHAKE} +\declareconstitemRM{PMIX_ERR_READY_FOR_HANDSHAKE} Ready for handshake % -\declareconstitemDEP{PMIX_ERR_IN_ERRNO} +\declareconstitemRM{PMIX_ERR_IN_ERRNO} Error defined in \code{errno} % -\declareconstitemDEP{PMIX_ERR_INVALID_VAL_LENGTH} +\declareconstitemRM{PMIX_ERR_INVALID_VAL_LENGTH} Invalid value length % -\declareconstitemDEP{PMIX_ERR_INVALID_LENGTH} +\declareconstitemRM{PMIX_ERR_INVALID_LENGTH} Invalid argument length % -\declareconstitemDEP{PMIX_ERR_INVALID_NUM_ARGS} +\declareconstitemRM{PMIX_ERR_INVALID_NUM_ARGS} Invalid number of arguments % -\declareconstitemDEP{PMIX_ERR_INVALID_ARGS} +\declareconstitemRM{PMIX_ERR_INVALID_ARGS} Invalid arguments % -\declareconstitemDEP{PMIX_ERR_INVALID_NUM_PARSED} +\declareconstitemRM{PMIX_ERR_INVALID_NUM_PARSED} Invalid number parsed % -\declareconstitemDEP{PMIX_ERR_INVALID_KEYVALP} +\declareconstitemRM{PMIX_ERR_INVALID_KEYVALP} Invalid key/value pair % -\declareconstitemDEP{PMIX_ERR_INVALID_SIZE} +\declareconstitemRM{PMIX_ERR_INVALID_SIZE} Invalid size % -\declareconstitemDEP{PMIX_ERR_PROC_REQUESTED_ABORT} +\declareconstitemRM{PMIX_ERR_PROC_REQUESTED_ABORT} Process is already requested to abort % -\declareconstitemDEP{PMIX_ERR_SERVER_FAILED_REQUEST} +\declareconstitemRM{PMIX_ERR_SERVER_FAILED_REQUEST} Failed to connect to the server % -\declareconstitemDEP{PMIX_ERR_PROC_ENTRY_NOT_FOUND} +\declareconstitemRM{PMIX_ERR_PROC_ENTRY_NOT_FOUND} Process not found % -\declareconstitemDEP{PMIX_ERR_INVALID_ARG} +\declareconstitemRM{PMIX_ERR_INVALID_ARG} Invalid argument % -\declareconstitemDEP{PMIX_ERR_INVALID_KEY} +\declareconstitemRM{PMIX_ERR_INVALID_KEY} Invalid key % -\declareconstitemDEP{PMIX_ERR_INVALID_KEY_LENGTH} +\declareconstitemRM{PMIX_ERR_INVALID_KEY_LENGTH} Invalid key length % -\declareconstitemDEP{PMIX_ERR_INVALID_VAL} +\declareconstitemRM{PMIX_ERR_INVALID_VAL} Invalid value % -\declareconstitemDEP{PMIX_ERR_INVALID_NAMESPACE} +\declareconstitemRM{PMIX_ERR_INVALID_NAMESPACE} Invalid namespace % -\declareconstitemDEP{PMIX_ERR_SERVER_NOT_AVAIL} +\declareconstitemRM{PMIX_ERR_SERVER_NOT_AVAIL} Server is not available % -\declareconstitemDEP{PMIX_ERR_SILENT} +\declareconstitemRM{PMIX_ERR_SILENT} Silent error % -\declareconstitemDEP{PMIX_ERR_PACK_MISMATCH} +\declareconstitemRM{PMIX_ERR_PACK_MISMATCH} Pack mismatch % -\declareconstitemDEP{PMIX_ERR_DATA_VALUE_NOT_FOUND} +\declareconstitemRM{PMIX_ERR_DATA_VALUE_NOT_FOUND} Data value not found % -\declareconstitemDEP{PMIX_ERR_NOT_IMPLEMENTED} +\declareconstitemRM{PMIX_ERR_NOT_IMPLEMENTED} Not implemented % -\declareconstitemDEP{PMIX_GDS_ACTION_COMPLETE} +\declareconstitemRM{PMIX_GDS_ACTION_COMPLETE} The \ac{GDS} action has completed % -\declareconstitemDEP{PMIX_NOTIFY_ALLOC_COMPLETE} +\declareconstitemRM{PMIX_NOTIFY_ALLOC_COMPLETE} Notify that a requested allocation operation is complete - the result of the request will be included in the \refarg{info} array % @@ -931,83 +1100,83 @@ \subsection{Removed attributes} description. % -\declareAttributeDEP{PMIX_LOCAL_TOPO}{"pmix.ltopo"}{char*}{ +\declareAttributeRM{PMIX_LOCAL_TOPO}{"pmix.ltopo"}{char*}{ \ac{XML} representation of local node topology. } % -\declareAttributeDEP{PMIX_TOPOLOGY_XML}{"pmix.topo.xml"}{char*}{ +\declareAttributeRM{PMIX_TOPOLOGY_XML}{"pmix.topo.xml"}{char*}{ \ac{XML}-based description of topology } % -\declareAttributeDEP{PMIX_TOPOLOGY_FILE}{"pmix.topo.file"}{char*}{ +\declareAttributeRM{PMIX_TOPOLOGY_FILE}{"pmix.topo.file"}{char*}{ Full path to file containing \ac{XML} topology description } % -\declareAttributeDEP{PMIX_TOPOLOGY_SIGNATURE}{"pmix.toposig"}{char*}{ +\declareAttributeRM{PMIX_TOPOLOGY_SIGNATURE}{"pmix.toposig"}{char*}{ Topology signature string. } % -\declareAttributeDEP{PMIX_HWLOC_SHMEM_ADDR}{"pmix.hwlocaddr"}{size_t}{ +\declareAttributeRM{PMIX_HWLOC_SHMEM_ADDR}{"pmix.hwlocaddr"}{size_t}{ Address of the HWLOC shared memory segment. } % -\declareAttributeDEP{PMIX_HWLOC_SHMEM_SIZE}{"pmix.hwlocsize"}{size_t}{ +\declareAttributeRM{PMIX_HWLOC_SHMEM_SIZE}{"pmix.hwlocsize"}{size_t}{ Size of the HWLOC shared memory segment. } % -\declareAttributeDEP{PMIX_HWLOC_SHMEM_FILE}{"pmix.hwlocfile"}{char*}{ +\declareAttributeRM{PMIX_HWLOC_SHMEM_FILE}{"pmix.hwlocfile"}{char*}{ Path to the HWLOC shared memory file. } % -\declareAttributeDEP{PMIX_HWLOC_XML_V1}{"pmix.hwlocxml1"}{char*}{ +\declareAttributeRM{PMIX_HWLOC_XML_V1}{"pmix.hwlocxml1"}{char*}{ \ac{XML} representation of local topology using HWLOC's v1.x format. } % -\declareAttributeDEP{PMIX_HWLOC_XML_V2}{"pmix.hwlocxml2"}{char*}{ +\declareAttributeRM{PMIX_HWLOC_XML_V2}{"pmix.hwlocxml2"}{char*}{ \ac{XML} representation of local topology using HWLOC's v2.x format. } % -\declareAttributeDEP{PMIX_HWLOC_SHARE_TOPO}{"pmix.hwlocsh"}{bool}{ +\declareAttributeRM{PMIX_HWLOC_SHARE_TOPO}{"pmix.hwlocsh"}{bool}{ Share the HWLOC topology via shared memory } % -\declareAttributeDEP{PMIX_HWLOC_HOLE_KIND}{"pmix.hwlocholek"}{char*}{ +\declareAttributeRM{PMIX_HWLOC_HOLE_KIND}{"pmix.hwlocholek"}{char*}{ Kind of VM ``hole'' HWLOC should use for shared memory } % -\declareAttributeDEP{PMIX_DSTPATH}{"pmix.dstpath"}{char*}{ +\declareAttributeRM{PMIX_DSTPATH}{"pmix.dstpath"}{char*}{ Path to shared memory data storage (dstore) files. Deprecated from Standard as being implementation specific. } % -\declareAttributeDEP{PMIX_COLLECTIVE_ALGO}{"pmix.calgo"}{char*}{ +\declareAttributeRM{PMIX_COLLECTIVE_ALGO}{"pmix.calgo"}{char*}{ Comma-delimited list of algorithms to use for the collective operation. \ac{PMIx} does not impose any requirements on a host environment's collective algorithms. Thus, the acceptable values for this attribute will be environment-dependent - users are encouraged to check their host environment for supported values. } % -\pasteAttributeItemBegin{PMIX_COLLECTIVE_ALGO_REQD}This attribute was deprecated in v3.0 -\pasteAttributeItemEnd{} +\declareAttributeRM{PMIX_COLLECTIVE_ALGO_REQD}{"pmix.calreqd"}{bool}{ +If \code{true}, indicates that the requested choice of algorithm is mandatory. +} % -\declareAttributeDEP{PMIX_PROC_BLOB}{"pmix.pblob"}{pmix_byte_object_t}{ +\declareAttributeRM{PMIX_PROC_BLOB}{"pmix.pblob"}{pmix_byte_object_t}{ Packed blob of process data. } % -\declareAttributeDEP{PMIX_MAP_BLOB}{"pmix.mblob"}{pmix_byte_object_t}{ +\declareAttributeRM{PMIX_MAP_BLOB}{"pmix.mblob"}{pmix_byte_object_t}{ Packed blob of process location. } % -\declareAttributeDEP{PMIX_MAPPER}{"pmix.mapper"}{char*}{ +\declareAttributeRM{PMIX_MAPPER}{"pmix.mapper"}{char*}{ Mapping mechanism to use for placing spawned processes - when accessed using \refapi{PMIx_Get}, use the \refconst{PMIX_RANK_WILDCARD} value for the rank to discover the mapping mechanism used for the provided namespace. } % -\declareAttributeDEP{PMIX_NON_PMI}{"pmix.nonpmi"}{bool}{ +\declareAttributeRM{PMIX_NON_PMI}{"pmix.nonpmi"}{bool}{ Spawned processes will not call \refapi{PMIx_Init}. } % -\declareAttributeDEP{PMIX_PROC_URI}{"pmix.puri"}{char*}{ +\declareAttributeRM{PMIX_PROC_URI}{"pmix.puri"}{char*}{ \ac{URI} containing contact information for the specified process. } - % -\declareAttributeDEP{PMIX_ARCH}{"pmix.arch"}{uint32_t}{ +\declareAttributeRM{PMIX_ARCH}{"pmix.arch"}{uint32_t}{ Architecture flag. } diff --git a/bin/check-attr-refs.py b/bin/check-attr-refs.py index 1eb68285..44085479 100755 --- a/bin/check-attr-refs.py +++ b/bin/check-attr-refs.py @@ -10,8 +10,11 @@ if __name__ == "__main__": count_not_used = 0 + count_dep_refs = 0 + count_rm_refs = 0 attr_declared = {} deprecated_attr = [] + removed_attr = [] index_files = ["pmix-standard.idx", "index_attribute.idx"] # @@ -27,7 +30,7 @@ # # Verify that we have the necessary files in the current working directory # * pmix-standard.aux - # * pmix-standard.idx + # * index_files - see above # missing_index = False for fname in index_files: @@ -89,7 +92,7 @@ if args.verbose is True: print("Processing Index File: "+fname) - p = subprocess.Popen("grep \"\\|hyperindexformat\" "+fname, + p = subprocess.Popen("grep \"hyperindexformat{\" "+fname+" | sort", stdout=subprocess.PIPE, stderr=subprocess.STDOUT, shell=True, close_fds=True) sout = p.communicate()[0].decode("utf-8").splitlines() @@ -99,6 +102,7 @@ for line in sout: line = line.rstrip() + m = re.match(r'\s*\\indexentry{(\w+)', line) if m is None: print("Error: Failed to extract an attribute on the following line") @@ -107,12 +111,29 @@ else: attr_to_find = m.group(1) + # Some index entries have a prefix on them for sorting order, so + # access the actual printed string not the sorting version of + # the string. + m2 = re.match(r'\s*\\indexentry{(\w+)@(\w+)', line) + if m2 is not None: + attr_to_find = m2.group(2) + else: + m2 = re.match(r'\s*\\indexentry{(\w+)@\\emph\s*{(\w+)', line) + if m2 is not None: + attr_to_find = m2.group(2) + # Check to see if this is deprecated - if re.search("indexdepfmt", line) is not None: + if re.search("Deprecated", line) is not None: if args.verbose is True: print("Found a Deprecated Attribute: "+attr_to_find) deprecated_attr.insert(0, attr_to_find) + # Check to see if this is removed + if re.search("Removed", line) is not None: + if args.verbose is True: + print("Found a Removed Attribute: "+attr_to_find) + removed_attr.insert(0, attr_to_find) + if attr_to_find in attr_declared: attr_declared[attr_to_find] = attr_declared[attr_to_find] + 1 p.wait() @@ -128,6 +149,7 @@ if err_out is True: print("-"*50) print("Number of deprecated attributes: " + str(len(deprecated_attr))) + print("Number of removed attributes : " + str(len(removed_attr))) print("Number of declared attributes : " + str(len(attr_declared))) print("Number of missing attributes : " + str(num_missing)) sys.exit(1) @@ -183,12 +205,51 @@ # for attr in sorted(attr_declared): if attr_declared[attr] <= 0: - if attr not in deprecated_attr and attr != "PMIX_ATTR_UNDEF": + if attr not in deprecated_attr and attr not in removed_attr and attr != "PMIX_ATTR_UNDEF": print("Attribute Missing Reference: "+attr) count_not_used += 1 - elif args.verbose is True and attr != "PMIX_ATTR_UNDEF": - print("=====> Deprecated Attribute Missing Reference: "+attr) + elif attr in deprecated_attr and attr in removed_attr and attr_declared[attr] == 1: + # There is an entry for the deprecation and the removal. This is fine + continue + elif attr in deprecated_attr or attr in removed_attr: + # Allow references within the Chap_Revisions.tex - count them + num_in_chap_revisions = 0 + p = subprocess.Popen("grep \"refattr{"+attr+"}\" Chap_Revisions.tex | wc -l", + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, shell=True, close_fds=True) + sout = p.communicate()[0].decode("utf-8").splitlines() + if p.returncode != 0: + print("Error: Failed to verify declared attribute \""+attr+"\". grep error code "+str(p.returncode)+""); + sys.exit(2) + for line in sout: + line = line.rstrip() + num_in_chap_revisions = int(line) + # Extra increment for deprecated and removed items + if attr in deprecated_attr and attr in removed_attr: + num_in_chap_revisions += 1 + # If there are other references outside of the Revisions chapter then error out + if attr_declared[attr] - num_in_chap_revisions > 0: + if attr in deprecated_attr: + print("Deprecated Attribute: "+attr+" (Referenced "+str(attr_declared[attr]-num_in_chap_revisions)+" times)") + count_dep_refs += 1 + elif attr in removed_attr: + print("Removed Attribute: "+attr+" (Referenced "+str(attr_declared[attr]-num_in_chap_revisions)+" times)") + count_rm_refs += 1 + + # + # Additional analysis for removed, but not deprecated items + # + for attr in sorted(removed_attr): + if attr not in deprecated_attr: + print("Removed attribute that was not deprecated: "+attr); + count_rm_refs += 1 + + # + # Final summary + # print("%3d of %3d Attributes are missing reference" % (count_not_used, len(attr_declared))) - sys.exit(count_not_used) + print("%3d of %3d Deprecated Attributes with references remaining" % (count_dep_refs, len(deprecated_attr))) + print("%3d of %3d Removed Attributes with references remaining" % (count_rm_refs, len(removed_attr))) + + sys.exit(count_not_used + count_dep_refs + count_rm_refs) diff --git a/bin/check-multi-declare.py b/bin/check-multi-declare.py index 9291dd74..584a3f97 100755 --- a/bin/check-multi-declare.py +++ b/bin/check-multi-declare.py @@ -39,7 +39,8 @@ print("-"*50) # subsection.A is Appendix A: Python Bindings - p = subprocess.Popen("grep \"newlabel{"+ref_str+"\" pmix-standard.aux | grep -v subsection.A", + # subsection.B is Appendix B: Revision History + p = subprocess.Popen("grep \"newlabel{"+ref_str+"\" pmix-standard.aux | grep -v \"subsection.A\|subsection.B\"", stdout=subprocess.PIPE, stderr=subprocess.STDOUT, shell=True, close_fds=True) sout = p.communicate()[0].decode("utf-8").splitlines() if p.returncode != 0: diff --git a/pmix-standard.tex b/pmix-standard.tex index b9a515c9..abf0ff98 100644 --- a/pmix-standard.tex +++ b/pmix-standard.tex @@ -69,10 +69,13 @@ \input{pmix.sty} % Watermark for the Unofficial Drafts -% Note: "allpages","evenpages","oddpages" do not work. Likely because of the index. \ifthenelse{\boolean{is_unofficial_draft}} - {\usepackage[printwatermark]{xwatermark} - \newwatermark[firstpage,color=gray!30,angle=45,scale=3,xpos=-5,ypos=0]{Unofficial Draft} + {\usepackage{draftwatermark} + \SetWatermarkText{\textbf{Unofficial Draft}} + \SetWatermarkColor[gray]{0.85} + \SetWatermarkFontSize{90pt} + \SetWatermarkScale{1} + \SetWatermarkAngle{45} }{} %%%%%%%%%%%%%%%%%%% Indices diff --git a/pmix.sty b/pmix.sty index d89b5bef..6081acc5 100644 --- a/pmix.sty +++ b/pmix.sty @@ -138,6 +138,8 @@ \newcommand{\indexfmt}[1]{\textbf{\underline{#1}}} % Formatting for deprecated items in the index \newcommand{\indexdepfmt}[1]{\textbf{\underline{#1}}} +% Formatting for removed items in the index +\newcommand{\indexrmfmt}[1]{\textbf{\underline{#1}}} % \url styled in Roman font. @@ -247,8 +249,12 @@ \newcommand{\declareconstitem}[1]{\item[\code{#1}] \index[index_const]{#1|indexfmt} \label{const:#1} \hspace{1em}} \newcommand{\declareconstitemvalue}[2]{\item[\code{#1}] \index[index_const]{#1|indexfmt} \hspace{0.25em} \code{#2} \hspace{1em}} -\newcommand{\declareconstitemDEP}[1]{\item[\color{green!80!black}\code{#1}] \index[index_const]{#1|indexfmt} \label{const:#1} \hspace{1em}} +% New in this version \newcommand{\declareconstitemNEW}[1]{\item[\color{magenta}\code{#1}] \index[index_const]{#1|indexfmt} \label{const:#1} \hspace{1em}} +% Deprecated +\newcommand{\declareconstitemDEP}[1]{\item[\color{green!80!black}\code{#1}] \index[index_const]{Z_#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{const:#1} \hspace{1em}} +% Removed +\newcommand{\declareconstitemRM}[1]{\item[\color{red!80!black}\code{#1}] \index[index_const]{Z_#1@\emph{#1}!\textbf{Removed}|indexrmfmt} \label{const:#1} \hspace{1em}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -385,7 +391,17 @@ \newcommand{\declareEnvarDEP}[2]{% {\color{green!80!black}\code{#1}}% - \index[index_envars]{#1@#1 \textbf{(Deprecated)}|indexdepfmt} \label{envar:#1}% + \index[index_envars]{Z_#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{envar:#1}% + \vspace{-1.3ex}% + \expandafter\begin{adjustwidth}{.95cm}{}% + \StdCopyEcho{#1}{#2}% + \end{adjustwidth}% + \vspace{-1.3ex}% +} + +\newcommand{\declareEnvarRM}[2]{% + {\color{green!80!black}\code{#1}}% + \index[index_envars]{Z_#1@\emph{#1}!\textbf{Removed}|indexrmfmt} \label{envar:#1}% \vspace{-1.3ex}% \expandafter\begin{adjustwidth}{.95cm}{}% \StdCopyEcho{#1}{#2}% @@ -428,7 +444,19 @@ \newcommand{\declareAttributeDEP}[4]{% {\color{green!80!black}\code{#1}} ~~\code{#2}~~(\code{#3})% - \index[index_attribute]{#1@#1 \textbf{(Deprecated)}|indexdepfmt} \label{attr:#1}% + \index[index_attribute]{Z_#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{attr:#1}% + \StdCopy{str:#1}{\code{#2}}% + \StdCopy{attr:#1}{\code{#3}}% + \vspace{-1.3ex}% + \expandafter\begin{adjustwidth}{.95cm}{}% + \StdCopyEcho{#1}{#4}% + \end{adjustwidth}% + \vspace{-1.3ex}% +} + +\newcommand{\declareAttributeRM}[4]{% + {\color{red!80!black}\code{#1}} ~~\code{#2}~~(\code{#3})% + \index[index_attribute]{Z_#1@\emph{#1}!\textbf{Removed}|indexrmfmt} \label{attr:#1}% \StdCopy{str:#1}{\code{#2}}% \StdCopy{attr:#1}{\code{#3}}% \vspace{-1.3ex}% @@ -707,14 +735,16 @@ \newcommand{\refapi}[1]{\index[index_api]{#1}\hyperref[apifn:#1]{\code{#1}}} \newcommand{\argapi}[1] {\refapi{#1}} + \newcommand{\declareapiDEP}[1]{% {\color{green!80!black}\code{#1}}% - \index[index_api]{#1@#1 \textbf{(Deprecated)}|indexdepfmt} \label{apifn:#1}% + \index[index_api]{Z_#1@#1!\textbf{(Deprecated)}|indexdepfmt} \label{apifn:#1}% } \newcommand{\declareapiDEPNODISP}[1]{% - \index[index_api]{#1@#1|indexdepfmt} \label{apifn:#1}% + \index[index_api]{Z_#1@#1!\textbf{(Deprecated)}|indexdepfmt} \label{apifn:#1}% } +\newcommand{\refapiDEP}[1]{\index[index_api]{Z_#1@#1!\textbf{(Deprecated)}}\hyperref[apifn:#1]{\code{#1}}} % API references for language bindings (e.g., Python) % {Language specific function}{Primary C PMIx function}{Language Classification}