Elevate Provisional from v5 to non-provisional

[abouteiller]

Overview

We are thinking about marking non-controversial provisional items created during v5.0 to non-provisional.

Motivation

Many of these are pretty simple and have been introduced to support ABI compatibility, which we are adamant about, so there is not really a reason to have them remain provisional.

List of provisionals we are unsure about

Many of these are pretty simple and non-controversial, it is expected that after a quick review they will be transitioning to the PROMOTE category DONE

Remaining in this list are some macros that remain provisional. Plan is

1. we remove these from the standard
2. keep them deprecated in the implementation
3. introduce function forms as provisional

• Chap_API_Struct.tex

  • 341:\versionMarkerProvisional{4.1} PMIX_NSPACE_INVALID(a):
  • 437:\versionMarkerProvisional{4.1} PMIX_RANK_IS_VALID(a)
  • 597:\versionMarkerProvisional{4.1} PMIX_PROCID_INVALID(a)
  • 630:\versionMarkerProvisional{4.1} PMIX_PROCID_XFER

• check implementation for existing function signatures of replacements, add if needed

• check ABI .h for replacements functions, add if needed

• check "drift items" issues, these may be in there already

List of provisionals that we want to promote

• Chap_API_Server.tex

  • 233:\declareAttributeProvisional{PMIX_SINGLETON}{"pmix.singleton"}{char*}{

• Chap_API_Sync.tex

  • 184:\declareAttributeProvisional{PMIX_LOCAL_COLLECTIVE_STATUS}{"pmix.loc.col.st"}{pmix_status_t}{

• Chap_API_Reserved_Keys.tex

  • 529:\declareAttributeProvisional{PMIX_NODE_OVERSUBSCRIBED}{"pmix.ndosub"}{bool}{

• Chap_API_Tools.tex

  • 702:\declareAttributeProvisional{PMIX_IOF_LOCAL_OUTPUT}{"pmix.iof.local"}{bool}{
  • 706:\declareAttributeProvisional{PMIX_IOF_MERGE_STDERR_STDOUT}{"pmix.iof.mrg"}{bool}{
  • 730:\declareAttributeProvisional{PMIX_IOF_OUTPUT_RAW}{"pmix.iof.raw"}{bool}{
  • 746:\declareAttributeProvisional{PMIX_IOF_RANK_OUTPUT}{"pmix.iof.rank"}{bool}{
  • 766:\declareAttributeProvisional{PMIX_IOF_OUTPUT_TO_FILE}{"pmix.iof.file"}{char*}{
  • 770:\declareAttributeProvisional{PMIX_IOF_OUTPUT_TO_DIRECTORY}{"pmix.iof.dir"}{char*}{
  • 774:\declareAttributeProvisional{PMIX_IOF_FILE_PATTERN}{"pmix.iof.fpt"}{bool}{
  • 778:\declareAttributeProvisional{PMIX_IOF_FILE_ONLY}{"pmix.iof.fonly"}{bool}{

• Chap_API_Proc_Mgmt.tex

  • 345:\declareconstitemvalueProvisional{PMIX_ERR_JOB_EXE_NOT_FOUND}{-190}
  • 348:\declareconstitemvalueProvisional{PMIX_ERR_JOB_INSUFFICIENT_RESOURCES}{-234}
  • 351:\declareconstitemvalueProvisional{PMIX_ERR_JOB_SYS_OP_FAILED}{-235}
  • 354:\declareconstitemvalueProvisional{PMIX_ERR_JOB_WDIR_NOT_FOUND}{-233}
  • 567:\declareAttributeProvisional{PMIX_ENVARS_HARVESTED}{"pmix.evar.hvstd"}{bool}{
  • 572:\declareAttributeProvisional{PMIX_JOB_TIMEOUT}{"pmix.job.time"}{int}{
  • 576:\declareAttributeProvisional{PMIX_SPAWN_TIMEOUT}{"pmix.sp.time"}{int}{

• Chap_API_Struct.tex

  • 1063:\declareapiProvisional{PMIx_Value_get_size}
  • 1307:\declareapiProvisional{PMIx_Info_get_size}
  • 1498:\declareapiProvisional{PMIx_Info_list_get_info}
  • 1532:\declareapiProvisional{PMIx_Info_list_prepend}
  • 2490:\declareconstitemvalueProvisional{PMIX_COMPRESSED_BYTE_OBJECT}{59}

• Chap_API_Data_Mgmt.tex

  • 407:\versionMarkerProvisional{4.1}PMIx_Data_unload
  • 458:\versionMarkerProvisional{4.1}PMIx_Data_load
  • 510:\versionMarkerProvisional{4.1}PMIx_Data_compress
  • 558:\versionMarkerProvisional{4.1}PMIx_Data_decompress
  • 597:\declareapiProvisional{PMIx_Data_embed}

• Chap_API_Server.tex

  • 1416:\declaremacroProvisional{PMIX_REGATTR_STATIC_INIT}
  • 1784:\declaremacroProvisional{PMIX_CPUSET_STATIC_INIT}

• Chap_API_Query.tex

  • 150:\item \refattr{PMIX_QUERY_PROVISIONAL_ABI_VERSION}
  • 363:\declareAttribute{PMIX_QUERY_PROVISIONAL_ABI_VERSION}{"pmix.qry.prabiver"}{char *}{Query the PMIx Standard Provisional \ac{ABI} version(s) supported by the \ac{PMIx} library. The version returned will be of the form \code{"MAJOR.MINOR"}. If multiple versions are supported then a comma-separated list of version numbers will be returned.
  • 462:\declaremacroProvisional{PMIX_QUERY_STATIC_INIT}

• Chap_API_Publish.tex

  • 420:\declaremacroProvisional{PMIX_LOOKUP_STATIC_INIT}

• Chap_API_Proc_Mgmt.tex

  • 642:\declaremacroProvisional{PMIX_APP_STATIC_INIT}
  • 1210:\declaremacroProvisional{PMIX_TOPOLOGY_STATIC_INIT}
  • 1631:\declaremacroProvisional{PMIX_DEVICE_DIST_STATIC_INIT}

• Chap_Introduction.tex

  • 287:The \textit{PMIx Standard Provisional ABI} represents the Provisional PMIx Standard elements (see the PMIx Governance document).

• Chap_API_Fabric.tex

  • 128:\declaremacroProvisional{PMIX_ENDPOINT_STATIC_INIT}
  • 229:\declaremacroProvisional{PMIX_COORD_STATIC_INIT}
  • 33 3:\declaremacroProvisional{PMIX_GEOMETRY_STATIC_INIT}
  • 540:\declaremacroProvisional{PMIX_FABRIC_STATIC_INIT}

• Chap_API_Struct.tex

  • 470:\declaremacroProvisional{PMIX_PROC_STATIC_INIT}
  • 794:\declaremacroProvisional{PMIX_PROC_INFO_STATIC_INIT}
  • 978:\declaremacroProvisional{PMIX_VALUE_STATIC_INIT}
  • 1236:\declaremacroProvisional{PMIX_INFO_STATIC_INIT}
  • 1863:\declaremacroProvisional{PMIX_ENVAR_STATIC_INIT}
  • 1967:\declaremacroProvisional{PMIX_BYTE_OBJECT_STATIC_INIT}
  • 2069:\declaremacroProvisional{PMIX_DATA_ARRAY_STATIC_INIT}

• Chap_API_Data_Mgmt.tex

  • 47:\declaremacroProvisional{PMIX_DATA_BUFFER_STATIC_INIT}

List of provisionals that will remain provisional for the time being

The Storage chapter does not have a full implementation yet, and there is no clamor for the feature at this point. A quick review didn't identify things that look "wrong" and that we would like to phase-out/deprecate. Our stance is to leave it as provisional for the time being.

• Chap_API_Storage.tex
  • 4:\provisionalChapter{Storage Support Definitions}
  • 15:\provisionalSection{Storage support constants}
  • 18:The \refstruct{pmix_storage_medium_t}~\provisionalMarker{} is a \code{uint64_t} type that defines a set of bit-mask flags for specifying different types of storage mediums. These can be bitwise OR'd together to accommodate storage systems that mix storage medium types.
  • 22:\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_UNKNOWN}{0x0000000000000001}
  • 25:\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_TAPE}{0x0000000000000002}
  • 28:\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_HDD}{0x0000000000000004}
  • 31:\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_SSD}{0x0000000000000008}
  • 34:\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_NVME}{0x0000000000000010}
  • 37:\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_PMEM}{0x0000000000000020}
  • 40:\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_RAM}{0x0000000000000040}
  • 53:The \refstruct{pmix_storage_accessibility_t}~\provisionalMarker{} is a \code{uint64_t} type that defines a set of bit-mask flags for specifying different levels of storage accessibility (i.e,. from where a storage system may be accessed). These can be bitwise OR'd together to accommodate storage systems that are accessibile in multiple ways.
  • 57:\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_NODE}{0x0000000000000001}
  • 60:\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_SESSION}{0x0000000000000002}
  • 63:\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_JOB}{0x0000000000000004}
  • 66:\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_RACK}{0x0000000000000008}
  • 69:\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_CLUSTER}{0x0000000000000010}
  • 72:\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_REMOTE}{0x0000000000000020}
  • 79:The \refstruct{pmix_storage_persistence_t}~\provisionalMarker{} is a \code{uint64_t} type that defines a set of bit-mask flags for specifying different levels of persistence for a particular storage system.
  • 83:\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_TEMPORARY}{0x0000000000000001}
  • 86:\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_NODE}{0x0000000000000002}
  • 89:\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_SESSION}{0x0000000000000004}
  • 92:\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_JOB}{0x0000000000000008}
  • 95:\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_SCRATCH}{0x0000000000000010}
  • 98:\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_PROJECT}{0x0000000000000020}
  • 101:\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_ARCHIVE}{0x0000000000000040}
  • 108:The \refstruct{pmix_storage_access_type_t}~\provisionalMarker{} is a \code{uint16_t} type that defines a set of bit-mask flags for specifying different storage system access types.
  • 112:\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESS_RD}{0x0001}
  • 115:\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESS_WR}{0x0002}
  • 118:\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESS_RDWR}{0x0003}
  • 125:\provisionalSection{Storage support attributes}
  • 131:\declareAttributeProvisional{PMIX_STORAGE_ID}{"pmix.strg.id"}{char*}{
  • 136:\declareAttributeProvisional{PMIX_STORAGE_PATH}{"pmix.strg.path"}{char*}{
  • 141:\declareAttributeProvisional{PMIX_STORAGE_TYPE}{"pmix.strg.type"}{char*}{
  • 146:\declareAttributeProvisional{PMIX_STORAGE_VERSION}{"pmix.strg.ver"}{char*}{
  • 151:\declareAttributeProvisional{PMIX_STORAGE_MEDIUM}{"pmix.strg.medium"}{pmix_storage_medium_t}{
  • 156:\declareAttributeProvisional{PMIX_STORAGE_ACCESSIBILITY}{"pmix.strg.access"}{pmix_storage_accessibility_t}{
  • 161:\declareAttributeProvisional{PMIX_STORAGE_PERSISTENCE}{"pmix.strg.persist"}{pmix_storage_persistence_t}{
  • 166:\declareAttributeProvisional{PMIX_QUERY_STORAGE_LIST}{"pmix.strg.list"}{char*}{
  • 171:\declareAttributeProvisional{PMIX_STORAGE_CAPACITY_LIMIT}{"pmix.strg.caplim"}{double}{
  • 176:\declareAttributeProvisional{PMIX_STORAGE_CAPACITY_USED}{"pmix.strg.capuse"}{double}{
  • 181:\declareAttributeProvisional{PMIX_STORAGE_OBJECT_LIMIT}{"pmix.strg.objlim"}{uint64_t}{
  • 186:\declareAttributeProvisional{PMIX_STORAGE_OBJECTS_USED}{"pmix.strg.objuse"}{uint64_t}{
  • 191:\declareAttributeProvisional{PMIX_STORAGE_MINIMAL_XFER_SIZE}{"pmix.strg.minxfer"}{double}{
  • 196:\declareAttributeProvisional{PMIX_STORAGE_SUGGESTED_XFER_SIZE}{"pmix.strg.sxfer"}{double}{
  • 201:\declareAttributeProvisional{PMIX_STORAGE_BW_MAX}{"pmix.strg.bwmax"}{double}{
  • 206:\declareAttributeProvisional{PMIX_STORAGE_BW_CUR}{"pmix.strg.bwcur"}{double}{
  • 211:\declareAttributeProvisional{PMIX_STORAGE_IOPS_MAX}{"pmix.strg.iopsmax"}{double}{
  • 216:\declareAttributeProvisional{PMIX_STORAGE_IOPS_CUR}{"pmix.strg.iopscur"}{double}{
  • 221:\declareAttributeProvisional{PMIX_STORAGE_ACCESS_TYPE}{"pmix.strg.atype"}{pmix_storage_access_type_t}{

[rhc54]

I would recommend also promoting the ones you list as "unsure about" - they are either truly simple (e.g., the "get_size" functions), are IOF directives supported by the library for a long time, or atomistic error return codes. I've never heard any disagreement or concerns raised over any of them.

I agree with the plans for the storage stuff - just let it sit for awhile.

[abouteiller]

Yes, the plan is to review and ideally transition all 'maybes' to 'yes'. They are pretty simple and a quick review should get us there.

[abouteiller]

We did a review and are now ready to create a PR that promotes as needed