diff --git a/Chap_API_Storage.tex b/Chap_API_Storage.tex index 2e2600de..499bac4c 100644 --- a/Chap_API_Storage.tex +++ b/Chap_API_Storage.tex @@ -4,6 +4,8 @@ \chapter{Storage Support Definitions} \label{chap:api_storage} +\provisionalMarker{} + Distributed and parallel computing systems are increasingly embracing storage hierarchies to meet the diverse data management needs of applications and other systems software in a cost-effective manner. These hierarchies provide access to a number of distinct storage layers, with each potentially composed of different storage hardware (e.g., HDD, SSD, tape, PMEM), deployed at different locations (e.g., on-node, on-switch, on-site, WAN), and designed using different storage paradigms (e.g., file-based, object-based). Each of these systems offers unique performance and usage characteristics that storage system users should carefully consider to ensure the most efficient use of storage resources. @@ -15,30 +17,31 @@ \chapter{Storage Support Definitions} \section{Storage support constants} \declarestruct{pmix_storage_medium_t} +\provisionalMarker{} The \refstruct{pmix_storage_medium_t} 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. \begin{constantdesc} % -\declareconstitemNEW{PMIX_STORAGE_MEDIUM_UNKNOWN} +\declareconstitemProvisional{PMIX_STORAGE_MEDIUM_UNKNOWN} The storage medium type is unknown. % -\declareconstitemNEW{PMIX_STORAGE_MEDIUM_TAPE} +\declareconstitemProvisional{PMIX_STORAGE_MEDIUM_TAPE} The storage system uses tape media. % -\declareconstitemNEW{PMIX_STORAGE_MEDIUM_HDD} +\declareconstitemProvisional{PMIX_STORAGE_MEDIUM_HDD} The storage system uses HDDs with traditional SAS, SATA interfaces. % -\declareconstitemNEW{PMIX_STORAGE_MEDIUM_SSD} +\declareconstitemProvisional{PMIX_STORAGE_MEDIUM_SSD} The storage system uses SSDs with traditional SAS, SATA interfaces. % -\declareconstitemNEW{PMIX_STORAGE_MEDIUM_NVME} +\declareconstitemProvisional{PMIX_STORAGE_MEDIUM_NVME} The storage system uses SSDs with NVMe interface. % -\declareconstitemNEW{PMIX_STORAGE_MEDIUM_PMEM} +\declareconstitemProvisional{PMIX_STORAGE_MEDIUM_PMEM} The storage system uses persistent memory. % -\declareconstitemNEW{PMIX_STORAGE_MEDIUM_RAM} +\declareconstitemProvisional{PMIX_STORAGE_MEDIUM_RAM} The storage system is volatile (e.g., tmpfs). % \end{constantdesc} @@ -50,73 +53,76 @@ \section{Storage support constants} \adviceimplend \declarestruct{pmix_storage_accessibility_t} +\provisionalMarker{} The \refstruct{pmix_storage_accessibility_t} 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. \begin{constantdesc} % -\declareconstitemNEW{PMIX_STORAGE_ACCESSIBILITY_NODE} +\declareconstitemProvisional{PMIX_STORAGE_ACCESSIBILITY_NODE} The storage system resources are accessible within the same node. % -\declareconstitemNEW{PMIX_STORAGE_ACCESSIBILITY_SESSION} +\declareconstitemProvisional{PMIX_STORAGE_ACCESSIBILITY_SESSION} The storage system resources are accessible within the same session. % -\declareconstitemNEW{PMIX_STORAGE_ACCESSIBILITY_JOB} +\declareconstitemProvisional{PMIX_STORAGE_ACCESSIBILITY_JOB} The storage system resources are accessible within the same job. % -\declareconstitemNEW{PMIX_STORAGE_ACCESSIBILITY_RACK} +\declareconstitemProvisional{PMIX_STORAGE_ACCESSIBILITY_RACK} The storage system resources are accessible within the same rack. % -\declareconstitemNEW{PMIX_STORAGE_ACCESSIBILITY_CLUSTER} +\declareconstitemProvisional{PMIX_STORAGE_ACCESSIBILITY_CLUSTER} The storage system resources are accessible within the same cluster. % -\declareconstitemNEW{PMIX_STORAGE_ACCESSIBILITY_REMOTE} +\declareconstitemProvisional{PMIX_STORAGE_ACCESSIBILITY_REMOTE} The storage system resources are remote. % \end{constantdesc} \declarestruct{pmix_storage_persistence_t} +\provisionalMarker{} The \refstruct{pmix_storage_persistence_t} type specifies different levels of persistence for a particular storage system. \begin{constantdesc} % -\declareconstitemNEW{PMIX_STORAGE_PERSISTENCE_TEMPORARY} +\declareconstitemProvisional{PMIX_STORAGE_PERSISTENCE_TEMPORARY} Data on the storage system is persisted only temporarily (i.e, it does not survive across sessions or node reboots). % -\declareconstitemNEW{PMIX_STORAGE_PERSISTENCE_NODE} +\declareconstitemProvisional{PMIX_STORAGE_PERSISTENCE_NODE} Data on the storage system is persisted on the node. % -\declareconstitemNEW{PMIX_STORAGE_PERSISTENCE_SESSION} +\declareconstitemProvisional{PMIX_STORAGE_PERSISTENCE_SESSION} Data on the storage system is persisted for the duration of the session. % -\declareconstitemNEW{PMIX_STORAGE_PERSISTENCE_JOB} +\declareconstitemProvisional{PMIX_STORAGE_PERSISTENCE_JOB} Data on the storage system is persisted for the duration of the job. % -\declareconstitemNEW{PMIX_STORAGE_PERSISTENCE_SCRATCH} +\declareconstitemProvisional{PMIX_STORAGE_PERSISTENCE_SCRATCH} Data on the storage system is persisted according to scratch storage policies (short-term storage, typically persisted for days to weeks). % -\declareconstitemNEW{PMIX_STORAGE_PERSISTENCE_PROJECT} +\declareconstitemProvisional{PMIX_STORAGE_PERSISTENCE_PROJECT} Data on the storage system is persisted according to project storage policies (long-term storage, typically persisted for the duration of a project). % -\declareconstitemNEW{PMIX_STORAGE_PERSISTENCE_ARCHIVE} +\declareconstitemProvisional{PMIX_STORAGE_PERSISTENCE_ARCHIVE} Data on the storage system is persisted according to archive storage policies (long-term storage, typically persisted indefinitely). % \end{constantdesc} \declarestruct{pmix_storage_access_type_t} +\provisionalMarker{} The \refstruct{pmix_storage_access_type_t} type specifies different storage system access types. \begin{constantdesc} % -\declareconstitemNEW{PMIX_STORAGE_ACCESS_RD} +\declareconstitemProvisional{PMIX_STORAGE_ACCESS_RD} Provide information on storage system read operations. % -\declareconstitemNEW{PMIX_STORAGE_ACCESS_WR} +\declareconstitemProvisional{PMIX_STORAGE_ACCESS_WR} Provide information on storage system write operations. % -\declareconstitemNEW{PMIX_STORAGE_ACCESS_RDWR} +\declareconstitemProvisional{PMIX_STORAGE_ACCESS_RDWR} Provide information on storage system read and write operations. % \end{constantdesc} @@ -129,97 +135,97 @@ \section{Storage support attributes} The following attributes may be returned in response to queries (e.g., \refapi{PMIx_Get} or \refapi{PMIx_Query_info}) made by processes or tools. % -\declareAttributeNEW{PMIX_STORAGE_ID}{"pmix.strg.id"}{char*}{ +\declareAttributeProvisional{PMIX_STORAGE_ID}{"pmix.strg.id"}{char*}{ An identifier for the storage system (e.g., lustre-fs1, daos-oss1, home-fs) } % -\declareAttributeNEW{PMIX_STORAGE_PATH}{"pmix.strg.path"}{char*}{ +\declareAttributeProvisional{PMIX_STORAGE_PATH}{"pmix.strg.path"}{char*}{ Mount point path for the storage system (valid only for file-based storage systems) } % -\declareAttributeNEW{PMIX_STORAGE_TYPE}{"pmix.strg.type"}{char*}{ +\declareAttributeProvisional{PMIX_STORAGE_TYPE}{"pmix.strg.type"}{char*}{ Type of storage system (i.e., "lustre", "gpfs", "daos", "ext4") } % -\declareAttributeNEW{PMIX_STORAGE_VERSION}{"pmix.strg.ver"}{char*}{ +\declareAttributeProvisional{PMIX_STORAGE_VERSION}{"pmix.strg.ver"}{char*}{ Version string for the storage system } % -\declareAttributeNEW{PMIX_STORAGE_MEDIUM}{"pmix.strg.medium"}{pmix_storage_medium_t}{ +\declareAttributeProvisional{PMIX_STORAGE_MEDIUM}{"pmix.strg.medium"}{pmix_storage_medium_t}{ Types of storage mediums utilized by the storage system (e.g., SSDs, HDDs, tape) } % -\declareAttributeNEW{PMIX_STORAGE_ACCESSIBILITY}{"pmix.strg.access"}{pmix_storage_accessibility_t}{ +\declareAttributeProvisional{PMIX_STORAGE_ACCESSIBILITY}{"pmix.strg.access"}{pmix_storage_accessibility_t}{ Accessibility level of the storage system (e.g., within same node, within same session) } % -\declareAttributeNEW{PMIX_STORAGE_PERSISTENCE}{"pmix.strg.persist"}{pmix_storage_persistence_t}{ +\declareAttributeProvisional{PMIX_STORAGE_PERSISTENCE}{"pmix.strg.persist"}{pmix_storage_persistence_t}{ Persistence level of the storage system (e.g., sratch storage or achive storage) } % -\declareAttributeNEW{PMIX_QUERY_STORAGE_LIST}{"pmix.strg.list"}{char*}{ +\declareAttributeProvisional{PMIX_QUERY_STORAGE_LIST}{"pmix.strg.list"}{char*}{ Comma-delimited list of storage identifiers (i.e., \refattr{PMIX_STORAGE_ID} types) for available storage systems } % -\declareAttributeNEW{PMIX_STORAGE_CAPACITY_LIMIT}{"pmix.strg.caplim"}{double}{ +\declareAttributeProvisional{PMIX_STORAGE_CAPACITY_LIMIT}{"pmix.strg.caplim"}{double}{ Overall limit on capacity (in bytes) for the storage system } % -\declareAttributeNEW{PMIX_STORAGE_CAPACITY_USED}{"pmix.strg.capuse"}{double}{ +\declareAttributeProvisional{PMIX_STORAGE_CAPACITY_USED}{"pmix.strg.capuse"}{double}{ Overall used capacity (in bytes) for the storage system } % -\declareAttributeNEW{PMIX_STORAGE_OBJECT_LIMIT}{"pmix.strg.objlim"}{uint64_t}{ +\declareAttributeProvisional{PMIX_STORAGE_OBJECT_LIMIT}{"pmix.strg.objlim"}{uint64_t}{ Overall limit on number of objects (e.g., inodes) for the storage system } % -\declareAttributeNEW{PMIX_STORAGE_OBJECTS_USED}{"pmix.strg.objuse"}{uint64_t}{ +\declareAttributeProvisional{PMIX_STORAGE_OBJECTS_USED}{"pmix.strg.objuse"}{uint64_t}{ Overall used number of objects (e.g., inodes) for the storage system } % -\declareAttributeNEW{PMIX_STORAGE_MINIMAL_XFER_SIZE}{"pmix.strg.minxfer"}{double}{ +\declareAttributeProvisional{PMIX_STORAGE_MINIMAL_XFER_SIZE}{"pmix.strg.minxfer"}{double}{ Minimal transfer size (in bytes) for the storage system - this is the storage system's atomic unit of transfer (e.g., block size) } % -\declareAttributeNEW{PMIX_STORAGE_SUGGESTED_XFER_SIZE}{"pmix.strg.sxfer"}{double}{ +\declareAttributeProvisional{PMIX_STORAGE_SUGGESTED_XFER_SIZE}{"pmix.strg.sxfer"}{double}{ Suggested transfer size (in bytes) for the storage system } % -\declareAttributeNEW{PMIX_STORAGE_BW_MAX}{"pmix.strg.bwmax"}{double}{ +\declareAttributeProvisional{PMIX_STORAGE_BW_MAX}{"pmix.strg.bwmax"}{double}{ Maximum bandwidth (in bytes/sec) for storage system - provided as the theoretical maximum or the maximum observed bandwidth value } % -\declareAttributeNEW{PMIX_STORAGE_BW_CUR}{"pmix.strg.bwcur"}{double}{ +\declareAttributeProvisional{PMIX_STORAGE_BW_CUR}{"pmix.strg.bwcur"}{double}{ Observed bandwidth (in bytes/sec) for storage system - provided as a recently observed bandwidth value, with the exact measurement interval depending on the storage system and/or PMIx library implementation } % -\declareAttributeNEW{PMIX_STORAGE_IOPS_MAX}{"pmix.strg.iopsmax"}{double}{ +\declareAttributeProvisional{PMIX_STORAGE_IOPS_MAX}{"pmix.strg.iopsmax"}{double}{ Maximum IOPS (in I/O operations per second) for storage system - provided as the theoretical maximum or the maximum observed IOPS value } % -\declareAttributeNEW{PMIX_STORAGE_IOPS_CUR}{"pmix.strg.iopscur"}{double}{ +\declareAttributeProvisional{PMIX_STORAGE_IOPS_CUR}{"pmix.strg.iopscur"}{double}{ Observed IOPS (in I/O operations per second) for storage system - provided as a recently observed IOPS value, with the exact measurement interval depending on the storage system and/or PMIx library implementation } % -\declareAttributeNEW{PMIX_STORAGE_ACCESS_TYPE}{"pmix.strg.atype"}{pmix_storage_access_type_t}{ +\declareAttributeProvisional{PMIX_STORAGE_ACCESS_TYPE}{"pmix.strg.atype"}{pmix_storage_access_type_t}{ Qualifier describing the type of storage access to return information for (e.g., for qualifying \refattr{PMIX_STORAGE_BW_CUR}, \refattr{PMIX_STORAGE_IOPS_CUR}, or \refattr{PMIX_STORAGE_SUGGESTED_XFER_SIZE} attributes) } diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index 0c60d203..55f6214a 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -1192,4 +1192,78 @@ \subsection{Removed attributes} Architecture flag. } +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%% History: Version 4.1 +\section{Version 4.1: TBD} + +The v4.1 update includes clarifications and corrections from the v4.0 document: + +\begin{compactitemize} + \item Provisional Items: + \begin{compactitemize} + \item Storage \chapterref{chap:api_storage} + \end{compactitemize} +\end{compactitemize} + +\subsection{Added Data Structures (Provisional)} + +\begin{compactitemize} + \item \refstruct{pmix_storage_medium_t} + \item \refstruct{pmix_storage_accessibility_t} + \item \refstruct{pmix_storage_persistence_t} + \item \refstruct{pmix_storage_access_type_t} +\end{compactitemize} + + +\subsection{Added Constants (Provisional)} + +\littleheader{Storage constants} +\refconst{PMIX_STORAGE_MEDIUM_UNKNOWN} \\ +\refconst{PMIX_STORAGE_MEDIUM_TAPE} \\ +\refconst{PMIX_STORAGE_MEDIUM_HDD} \\ +\refconst{PMIX_STORAGE_MEDIUM_SSD} \\ +\refconst{PMIX_STORAGE_MEDIUM_NVME} \\ +\refconst{PMIX_STORAGE_MEDIUM_PMEM} \\ +\refconst{PMIX_STORAGE_MEDIUM_RAM} \\ +\refconst{PMIX_STORAGE_ACCESSIBILITY_NODE} \\ +\refconst{PMIX_STORAGE_ACCESSIBILITY_SESSION} \\ +\refconst{PMIX_STORAGE_ACCESSIBILITY_JOB} \\ +\refconst{PMIX_STORAGE_ACCESSIBILITY_RACK} \\ +\refconst{PMIX_STORAGE_ACCESSIBILITY_CLUSTER} \\ +\refconst{PMIX_STORAGE_ACCESSIBILITY_REMOTE} \\ +\refconst{PMIX_STORAGE_PERSISTENCE_TEMPORARY} \\ +\refconst{PMIX_STORAGE_PERSISTENCE_NODE} \\ +\refconst{PMIX_STORAGE_PERSISTENCE_SESSION} \\ +\refconst{PMIX_STORAGE_PERSISTENCE_JOB} \\ +\refconst{PMIX_STORAGE_PERSISTENCE_SCRATCH} \\ +\refconst{PMIX_STORAGE_PERSISTENCE_PROJECT} \\ +\refconst{PMIX_STORAGE_PERSISTENCE_ARCHIVE} \\ +\refconst{PMIX_STORAGE_ACCESS_RD} \\ +\refconst{PMIX_STORAGE_ACCESS_WR} \\ +\refconst{PMIX_STORAGE_ACCESS_RDWR} + +\subsection{Added Attributes (Provisional)} + +\littleheader{Storage attributes} +\pasteAttributeItem{PMIX_STORAGE_ID} +\pasteAttributeItem{PMIX_STORAGE_PATH} +\pasteAttributeItem{PMIX_STORAGE_TYPE} +\pasteAttributeItem{PMIX_STORAGE_VERSION} +\pasteAttributeItem{PMIX_STORAGE_MEDIUM} +\pasteAttributeItem{PMIX_STORAGE_ACCESSIBILITY} +\pasteAttributeItem{PMIX_STORAGE_PERSISTENCE} +\pasteAttributeItem{PMIX_QUERY_STORAGE_LIST} +\pasteAttributeItem{PMIX_STORAGE_CAPACITY_LIMIT} +\pasteAttributeItem{PMIX_STORAGE_CAPACITY_USED} +\pasteAttributeItem{PMIX_STORAGE_OBJECT_LIMIT} +\pasteAttributeItem{PMIX_STORAGE_OBJECTS_USED} +\pasteAttributeItem{PMIX_STORAGE_MINIMAL_XFER_SIZE} +\pasteAttributeItem{PMIX_STORAGE_SUGGESTED_XFER_SIZE} +\pasteAttributeItem{PMIX_STORAGE_BW_MAX} +\pasteAttributeItem{PMIX_STORAGE_BW_CUR} +\pasteAttributeItem{PMIX_STORAGE_IOPS_MAX} +\pasteAttributeItem{PMIX_STORAGE_IOPS_CUR} +\pasteAttributeItem{PMIX_STORAGE_ACCESS_TYPE} + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%