EIC code displayed by LXR master/​include/​pmix.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-17 09:55:55

 /*
  * Copyright (c) 2013-2020 Intel, Inc.  All rights reserved.
  * Copyright (c) 2016      Research Organization for Information Science
  *                         and Technology (RIST). All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met:
  *
  * - Redistributions of source code must retain the above copyright
  *   notice, this list of conditions and the following disclaimer.
  *
  * - Redistributions in binary form must reproduce the above copyright
  *   notice, this list of conditions and the following disclaimer listed
  *   in this license in the documentation and/or other materials
  *   provided with the distribution.
  *
  * - Neither the name of the copyright holders nor the names of its
  *   contributors may be used to endorse or promote products derived from
  *   this software without specific prior written permission.
  *
  * The copyright holders provide no reassurances that the source code
  * provided does not infringe any patent, copyright, or any other
  * intellectual property rights of third parties.  The copyright holders
  * disclaim any liability to any recipient for claims brought against
  * recipient by any third party for infringement of that parties
  * intellectual property rights.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
  * Copyright (c) 2021-2023 Nanook Consulting.  All rights reserved.
  * $COPYRIGHT$
  *
  * Additional copyrights may follow
  *
  * $HEADER$
  */
 
 #ifndef PMIx_H
 #define PMIx_H
 
 /* Structure and constant definitions */
 #include <pmix_common.h>
 
 #if defined(c_plusplus) || defined(__cplusplus)
 extern "C" {
 #endif
 
 /****    PMIX API    ****/
 
 /* Initialize the PMIx client, returning the process identifier assigned
  * to this client's application in the provided pmix_proc_t struct.
  * Passing a parameter of _NULL_ for this parameter is allowed if the user
  * wishes solely to initialize the PMIx system and does not require
  * return of the identifier at that time.
  *
  * When called the PMIx client will check for the required connection
  * information of the local PMIx server and will establish the connection.
  * If the information is not found, or the server connection fails, then
  * an appropriate error constant will be returned.
  *
  * If successful, the function will return PMIX_SUCCESS and will fill the
  * provided structure with the server-assigned namespace and rank of the
  * process within the application.
  *
  * Note that the PMIx client library is referenced counted, and so multiple
  * calls to PMIx_Init are allowed. Thus, one way to obtain the namespace and
  * rank of the process is to simply call PMIx_Init with a non-NULL parameter.
  *
  * The info array is used to pass user requests pertaining to the init
  * and subsequent operations. Pass a _NULL_ value for the array pointer
  * is supported if no directives are desired.
  */
 PMIX_EXPORT pmix_status_t PMIx_Init(pmix_proc_t *proc,
                                     pmix_info_t info[], size_t ninfo);
 
 /* Finalize the PMIx client, closing the connection to the local server.
  * An error code will be returned if, for some reason, the connection
  * cannot be closed.
  *
  * The info array is used to pass user requests regarding the finalize
  * operation. This can include:
  *
  * (a) PMIX_EMBED_BARRIER - By default, PMIx_Finalize does not include an
  * internal barrier operation. This attribute directs PMIx_Finalize to
  * execute a barrier as part of the finalize operation.
  */
 PMIX_EXPORT pmix_status_t PMIx_Finalize(const pmix_info_t info[], size_t ninfo);
 
 
 /* Returns _true_ if the PMIx client has been successfully initialized,
  * returns _false_ otherwise. Note that the function only reports the
  * internal state of the PMIx client - it does not verify an active
  * connection with the server, nor that the server is functional. */
 PMIX_EXPORT int PMIx_Initialized(void);
 
 
 /* Request that the provided array of procs be aborted, returning the
  * provided _status_ and printing the provided message. A _NULL_
  * for the proc array indicates that all processes in the caller's
  * nspace are to be aborted.
  *
  * The response to this request is somewhat dependent on the specific resource
  * manager and its configuration (e.g., some resource managers will
  * not abort the application if the provided _status_ is zero unless
  * specifically configured to do so), and thus lies outside the control
  * of PMIx itself. However, the client will inform the RM of
  * the request that the application be aborted, regardless of the
  * value of the provided _status_.
  *
  * Passing a _NULL_ msg parameter is allowed. Note that race conditions
  * caused by multiple processes calling PMIx_Abort are left to the
  * server implementation to resolve with regard to which status is
  * returned and what messages (if any) are printed. */
 PMIX_EXPORT pmix_status_t PMIx_Abort(int status, const char msg[],
                                      pmix_proc_t procs[], size_t nprocs);
 
 
 /* Push a value into the client's namespace. The client library will cache
  * the information locally until _PMIx_Commit_ is called. The provided scope
  * value is passed to the local PMIx server, which will distribute the data
  * as directed. */
 PMIX_EXPORT pmix_status_t PMIx_Put(pmix_scope_t scope,
                                    const char key[],
                                    pmix_value_t *val);
 
 
 /* Push all previously _PMIx_Put_ values to the local PMIx server.
  * This is an asynchronous operation - the library will immediately
  * return to the caller while the data is transmitted to the local
  * server in the background */
 PMIX_EXPORT pmix_status_t PMIx_Commit(void);
 
 
 /* Execute a blocking barrier across the processes identified in the
  * specified array. Passing a _NULL_ pointer as the _procs_ parameter
  * indicates that the barrier is to span all processes in the client's
  * namespace. Each provided pmix_proc_t struct can pass PMIX_RANK_WILDCARD to
  * indicate that all processes in the given namespace are
  * participating.
  *
  * The info array is used to pass user requests regarding the fence
  * operation. This can include:
  *
  * (a) PMIX_COLLECT_DATA - a boolean indicating whether or not the barrier
  *     operation is to return the _put_ data from all participating processes.
  *     A value of _false_ indicates that the callback is just used as a release
  *     and no data is to be returned at that time. A value of _true_ indicates
  *     that all _put_ data is to be collected by the barrier. Returned data is
  *     cached at the server to reduce memory footprint, and can be retrieved
  *     as needed by calls to PMIx_Get(nb).
  *
  *     Note that for scalability reasons, the default behavior for PMIx_Fence
  *     is to _not_ collect the data.
  *
  * (b) PMIX_COLLECTIVE_ALGO - a comma-delimited string indicating the algos
  *     to be used for executing the barrier, in priority order.
  *
  * (c) PMIX_COLLECTIVE_ALGO_REQD - instructs the host RM that it should return
  *     an error if none of the specified algos are available. Otherwise, the RM
  *     is to use one of the algos if possible, but is otherwise free to use any
  *     of its available methods to execute the operation.
  *
  * (d) PMIX_TIMEOUT - maximum time for the fence to execute before declaring
  *     an error. By default, the RM shall terminate the operation and notify participants
  *     if one or more of the indicated procs fails during the fence. However,
  *     the timeout parameter can help avoid "hangs" due to programming errors
  *     that prevent one or more procs from reaching the "fence".
  */
 PMIX_EXPORT pmix_status_t PMIx_Fence(const pmix_proc_t procs[], size_t nprocs,
                                      const pmix_info_t info[], size_t ninfo);
 
 /* Non-blocking version of PMIx_Fence. Note that the function will return
  * an error if a _NULL_ callback function is given. */
 PMIX_EXPORT pmix_status_t PMIx_Fence_nb(const pmix_proc_t procs[], size_t nprocs,
                                         const pmix_info_t info[], size_t ninfo,
                                         pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Retrieve information for the specified _key_ as published by the process
  * identified in the given pmix_proc_t, returning a pointer to the value in the
  * given address.
  *
  * This is a blocking operation - the caller will block until
  * the specified data has been _PMIx_Put_ by the specified rank. The caller is
  * responsible for freeing all memory associated with the returned value when
  * no longer required.
  *
  * The info array is used to pass user requests regarding the get
  * operation. This can include:
  *
  * (a) PMIX_TIMEOUT - maximum time for the get to execute before declaring
  *     an error. The timeout parameter can help avoid "hangs" due to programming
  *     errors that prevent the target proc from ever exposing its data.
  */
 PMIX_EXPORT pmix_status_t PMIx_Get(const pmix_proc_t *proc, const char key[],
                                    const pmix_info_t info[], size_t ninfo,
                                    pmix_value_t **val);
 
 /* A non-blocking operation version of PMIx_Get - the callback function will
  * be executed once the specified data has been _PMIx_Put_
  * by the identified process and retrieved by the local server. The info
  * array is used as described above for the blocking form of this call. */
 PMIX_EXPORT pmix_status_t PMIx_Get_nb(const pmix_proc_t *proc, const char key[],
                                       const pmix_info_t info[], size_t ninfo,
                                       pmix_value_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Publish the data in the info array for lookup. By default,
  * the data will be published into the PMIX_SESSION range and
  * with PMIX_PERSIST_APP persistence. Changes to those values,
  * and any additional directives, can be included in the pmix_info_t
  * array.
  *
  * Note that the keys must be unique within the specified
  * data range or else an error will be returned (first published
  * wins). Attempts to access the data by procs outside of
  * the provided data range will be rejected.
  *
  * The persistence parameter instructs the server as to how long
  * the data is to be retained.
  *
  * The blocking form will block until the server confirms that the
  * data has been posted and is available. The non-blocking form will
  * return immediately, executing the callback when the server confirms
  * availability of the data.
  */
 PMIX_EXPORT pmix_status_t PMIx_Publish(const pmix_info_t info[], size_t ninfo);
 PMIX_EXPORT pmix_status_t PMIx_Publish_nb(const pmix_info_t info[], size_t ninfo,
                                           pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Lookup information published by this or another process. By default,
  * the search will be conducted across the PMIX_SESSION range. Changes
  * to the range, and any additional directives, can be provided
  * in the pmix_info_t array. Note that the search is also constrained
  * to only data published by the current user ID - i.e., the search
  * will not return data published by an application being executed
  * by another user. There currently is no option to override this
  * behavior - such an option may become available later via an
  * appropriate pmix_info_t directive.
  *
  * The "data" parameter consists of an array of pmix_pdata_t struct with the
  * keys specifying the requested information. Data will be returned
  * for each key in the associated info struct - any key that cannot
  * be found will return with a data type of "PMIX_UNDEF". The function
  * will return SUCCESS if _any_ values can be found, so the caller
  * must check each data element to ensure it was returned.
  *
  * The proc field in each pmix_pdata_t struct will contain the
  * nspace/rank of the process that published the data.
  *
  * Note: although this is a blocking function, it will _not_ wait
  * by default for the requested data to be published. Instead, it
  * will block for the time required by the server to lookup its current
  * data and return any found items. Thus, the caller is responsible for
  * ensuring that data is published prior to executing a lookup, or
  * for retrying until the requested data is found
  *
  * Optionally, the info array can be used to modify this behavior
  * by including:
  *
  * (a) PMIX_WAIT - wait for the requested data to be published. The
  *     server is to wait until all data has become available.
  *
  * (b) PMIX_TIMEOUT - max time to wait for data to become available.
  *
  */
 PMIX_EXPORT pmix_status_t PMIx_Lookup(pmix_pdata_t data[], size_t ndata,
                                       const pmix_info_t info[], size_t ninfo);
 
 /* Non-blocking form of the _PMIx_Lookup_ function. Data for
  * the provided NULL-terminated keys array will be returned
  * in the provided callback function. As above, the default
  * behavior is to _not_ wait for data to be published. The
  * info keys can be used to modify the behavior as previously
  * described */
 PMIX_EXPORT pmix_status_t PMIx_Lookup_nb(char **keys, const pmix_info_t info[], size_t ninfo,
                                          pmix_lookup_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Unpublish data posted by this process using the given keys.
  * The function will block until the data has been removed by
  * the server. A value of _NULL_ for the keys parameter instructs
  * the server to remove _all_ data published by this process.
  *
  * By default, the range is assumed to be PMIX_SESSION. Changes
  * to the range, and any additional directives, can be provided
  * in the pmix_info_t array */
 PMIX_EXPORT pmix_status_t PMIx_Unpublish(char **keys,
                                          const pmix_info_t info[], size_t ninfo);
 
 /* Non-blocking form of the _PMIx_Unpublish_ function. The
  * callback function will be executed once the server confirms
  * removal of the specified data. */
 PMIX_EXPORT pmix_status_t PMIx_Unpublish_nb(char **keys,
                                             const pmix_info_t info[], size_t ninfo,
                                             pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Spawn a new job. The assigned namespace of the spawned applications
  * is returned in the nspace parameter - a _NULL_ value in that
  * location indicates that the caller doesn't wish to have the
  * namespace returned. The nspace array must be at least of size
  * PMIX_MAX_NSLEN+1. Behavior of individual resource managers
  * may differ, but it is expected that failure of any application
  * process to start will result in termination/cleanup of _all_
  * processes in the newly spawned job and return of an error
  * code to the caller.
  *
  * By default, the spawned processes will be PMIx "connected" to
  * the parent process upon successful launch (see PMIx_Connect
  * description for details). Note that this only means that the
  * parent process (a) will be given a copy of the  new job's
  * information so it can query job-level info without
  * incurring any communication penalties, and (b) will receive
  * notification of errors from process in the child job.
  *
  * Job-level directives can be specified in the job_info array. This
  * can include:
  *
  * (a) PMIX_NON_PMI - processes in the spawned job will
  *     not be calling PMIx_Init
  *
  * (b) PMIX_TIMEOUT - declare the spawn as having failed if the launched
  *     procs do not call PMIx_Init within the specified time
  *
  * (c) PMIX_NOTIFY_COMPLETION - notify the parent process when the
  *     child job terminates, either normally or with error
  */
 PMIX_EXPORT pmix_status_t PMIx_Spawn(const pmix_info_t job_info[], size_t ninfo,
                                      const pmix_app_t apps[], size_t napps,
                                      pmix_nspace_t nspace);
 
 
 /* Non-blocking form of the _PMIx_Spawn_ function. The callback
  * will be executed upon launch of the specified applications,
  * or upon failure to launch any of them. */
 PMIX_EXPORT pmix_status_t PMIx_Spawn_nb(const pmix_info_t job_info[], size_t ninfo,
                                         const pmix_app_t apps[], size_t napps,
                                         pmix_spawn_cbfunc_t cbfunc, void *cbdata);
 
 /* Record the specified processes as "connected". Both blocking and non-blocking
  * versions are provided. This means that the resource manager should treat the
  * failure of any process in the specified group as a reportable event, and take
  * appropriate action. Note that different resource managers may respond to
  * failures in different manners.
  *
  * The callback function is to be called once all participating processes have
  * called connect. The server is required to return any job-level info for the
  * connecting processes that might not already have - i.e., if the connect
  * request involves procs from different nspaces, then each proc shall receive
  * the job-level info from those nspaces other than their own.
  *
  * Note: a process can only engage in _one_ connect operation involving the identical
  * set of processes at a time. However, a process _can_ be simultaneously engaged
  * in multiple connect operations, each involving a different set of processes
  *
  * As in the case of the fence operation, the info array can be used to pass
  * user-level directives regarding the algorithm to be used for the collective
  * operation involved in the "connect", timeout constraints, and other options
  * available from the host RM */
 PMIX_EXPORT pmix_status_t PMIx_Connect(const pmix_proc_t procs[], size_t nprocs,
                                        const pmix_info_t info[], size_t ninfo);
 
 PMIX_EXPORT pmix_status_t PMIx_Connect_nb(const pmix_proc_t procs[], size_t nprocs,
                                           const pmix_info_t info[], size_t ninfo,
                                           pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Disconnect a previously connected set of processes. An error will be returned
  * if the specified set of procs was not previously "connected". As above, a process
  * may be involved in multiple simultaneous disconnect operations. However, a process
  * is not allowed to reconnect to a set of procs that has not fully completed
  * disconnect - i.e., you have to fully disconnect before you can reconnect to the
  * _same_ group of processes. The info array is used as above. */
 PMIX_EXPORT pmix_status_t PMIx_Disconnect(const pmix_proc_t procs[], size_t nprocs,
                                           const pmix_info_t info[], size_t ninfo);
 
 PMIX_EXPORT pmix_status_t PMIx_Disconnect_nb(const pmix_proc_t ranges[], size_t nprocs,
                                              const pmix_info_t info[], size_t ninfo,
                                              pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Given a node name, return an array of processes within the specified nspace
  * on that node. If the nspace is NULL, then all processes on the node will
  * be returned. If the specified node does not currently host any processes,
  * then the returned array will be NULL, and nprocs=0. The caller is responsible
  * for releasing the array when done with it - the PMIX_PROC_FREE macro is
  * provided for this purpose.
  */
 PMIX_EXPORT pmix_status_t PMIx_Resolve_peers(const char *nodename,
                                              const pmix_nspace_t nspace,
                                              pmix_proc_t **procs, size_t *nprocs);
 
 
 /* Given an nspace, return the list of nodes hosting processes within
  * that nspace. The returned string will contain a comma-delimited list
  * of nodenames. The caller is responsible for releasing the string
  * when done with it */
 PMIX_EXPORT pmix_status_t PMIx_Resolve_nodes(const pmix_nspace_t nspace, char **nodelist);
 
 /* Query information about the system in general - can include
  * a list of active nspaces, network topology, etc. Also can be
  * used to query node-specific info such as the list of peers
  * executing on a given node. We assume that the host RM will
  * exercise appropriate access control on the information.
  *
  * The following return status codes are provided in the callback:
  *
  * PMIX_SUCCESS - all data has been returned
  * PMIX_ERR_NOT_FOUND - none of the requested data was available
  * PMIX_ERR_PARTIAL_SUCCESS - some of the data has been returned
  * PMIX_ERR_NOT_SUPPORTED - the host RM does not support this function
  */
 PMIX_EXPORT pmix_status_t PMIx_Query_info(pmix_query_t queries[], size_t nqueries,
                                           pmix_info_t **results, size_t *nresults);
 
 PMIX_EXPORT pmix_status_t PMIx_Query_info_nb(pmix_query_t queries[], size_t nqueries,
                                              pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Log data to a central data service/store, subject to the
  * services offered by the host resource manager. The data to
  * be logged is provided in the data array. The (optional) directives
  * can be used to request specific storage options and direct
  * the choice of storage option.
  *
  * The callback function will be executed when the log operation
  * has been completed. The data array must be maintained until
  * the callback is provided
  */
 PMIX_EXPORT pmix_status_t PMIx_Log(const pmix_info_t data[], size_t ndata,
                                    const pmix_info_t directives[], size_t ndirs);
 
 PMIX_EXPORT pmix_status_t PMIx_Log_nb(const pmix_info_t data[], size_t ndata,
                                       const pmix_info_t directives[], size_t ndirs,
                                       pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Request an allocation operation from the host scheduler.
  * Several broad categories are envisioned, including the ability to:
  *
  * - request allocation of additional resources, including memory,
  *   bandwidth, and compute. This should be accomplished in a
  *   non-blocking manner so that the application can continue to
  *   progress while waiting for resources to become available. Note
  *   that the new allocation will be disjoint from (i.e., not
  *   affiliated with) the allocation of the requestor - thus the
  *   termination of one allocation will not impact the other.
  *
  * - extend the reservation on currently allocated resources, subject
  *   to scheduling availability and priorities. This includes extending
  *   the time limit on current resources, and/or requesting additional
  *   resources be allocated to the requesting job. Any additional
  *   allocated resources will be considered as part of the current
  *   allocation, and thus will be released at the same time.
  *
  * - release currently allocated resources that are no longer required.
  *   This is intended to support partial release of resources since all
  *   resources are normally released upon termination of the job. The
  *   identified use-cases include resource variations across discrete steps
  *   of a workflow, as well as applications that spawn sub-jobs and/or
  *   dynamically grow/shrink over time
  *
  * - "lend" resources back to the scheduler with an expectation of getting
  *   them back at some later time in the job. This can be a proactive
  *   operation (e.g., to save on computing costs when resources are
  *   temporarily not required), or in response to scheduler requests in
  *   lieue of preemption. A corresponding ability to "reacquire" resources
  *   previously released is included.
  */
 PMIX_EXPORT pmix_status_t PMIx_Allocation_request(pmix_alloc_directive_t directive,
                                                   pmix_info_t *info, size_t ninfo,
                                                   pmix_info_t **results, size_t *nresults);
 
 PMIX_EXPORT pmix_status_t PMIx_Allocation_request_nb(pmix_alloc_directive_t directive,
                                                      pmix_info_t *info, size_t ninfo,
                                                      pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Request a session control action. The sessionID identifies the session
  * to which the specified control action is to be applied. A NULL
  * value can be used to indicate all sessions under the caller's control.
  *
  * The directives are provided as pmix_info_t structs in the directives
  * array. The callback function provides a status to indicate whether or
  * not the request was granted, and to provide some information as to the
  * reason for any denial in the pmix_info_cbfunc_t' array of pmix_info_t
  * structures. If non-NULL, then the specified release_fn must be called
  * when the callback function completes - this will be used to release any
  * provided pmix_info_t array.
 
  * Passing NULL as the cbfunc to this call indicates that it shall be treated
  * as a blocking operation, with the return status indicative of the overall
  * operation's completion.
  */
 PMIX_EXPORT pmix_status_t PMIx_Session_control(uint32_t sessionID,
                                                const pmix_info_t directives[], size_t ndirs,
                                                pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Request a job control action. The targets array identifies the
  * processes to which the requested job control action is to be applied.
  * A NULL value can be used to indicate all processes in the caller's
  * nspace. The use of PMIX_RANK_WILDARD can also be used to indicate
  * that all processes in the given nspace are to be included.
  *
  * The directives are provided as pmix_info_t structs in the directives
  * array. The callback function provides a status to indicate whether or
  * not the request was granted, and to provide some information as to
  * the reason for any denial in the pmix_info_cbfunc_t array of pmix_info_t
  * structures. If non-NULL, then the specified release_fn must be called
  * when the callback function completes - this will be used to release
  * any provided pmix_info_t array.
  */
 PMIX_EXPORT pmix_status_t PMIx_Job_control(const pmix_proc_t targets[], size_t ntargets,
                                            const pmix_info_t directives[], size_t ndirs,
                                            pmix_info_t **results, size_t *nresults);
 
 PMIX_EXPORT pmix_status_t PMIx_Job_control_nb(const pmix_proc_t targets[], size_t ntargets,
                                               const pmix_info_t directives[], size_t ndirs,
                                               pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Request that something be monitored - e.g., that the server monitor
  * this process for periodic heartbeats as an indication that the process
  * has not become "wedged". When a monitor detects the specified alarm
  * condition, it will generate an event notification using the provided
  * error code and passing along any available relevant information. It is
  * up to the caller to register a corresponding event handler.
  *
  * Params:
  *
  * monitor: attribute indicating the type of monitor being requested - e.g.,
  *          PMIX_MONITOR_FILE to indicate that the requestor is asking that
  *          a file be monitored.
  *
  * error: the status code to be used when generating an event notification
  *        alerting that the monitor has been triggered. The range of the
  *        notification defaults to PMIX_RANGE_NAMESPACE - this can be
  *        changed by providing a PMIX_RANGE directive
  *
  * directives: characterize the monitoring request (e.g., monitor file size)
  *             and frequency of checking to be done
  *
  * cbfunc: provides a status to indicate whether or not the request was granted,
  *         and to provide some information as to the reason for any denial in
  *         the pmix_info_cbfunc_t array of pmix_info_t structures.
  *
  * Note: a process can send a heartbeat to the server using the PMIx_Heartbeat
  * macro provided below*/
 PMIX_EXPORT pmix_status_t PMIx_Process_monitor(const pmix_info_t *monitor, pmix_status_t error,
                                                const pmix_info_t directives[], size_t ndirs,
                                                pmix_info_t **results, size_t *nresults);
 
 PMIX_EXPORT pmix_status_t PMIx_Process_monitor_nb(const pmix_info_t *monitor, pmix_status_t error,
                                                   const pmix_info_t directives[], size_t ndirs,
                                                   pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* define a special macro to simplify sending of a heartbeat */
 #define PMIx_Heartbeat()                                                    \
     do {                                                                    \
         pmix_info_t _in;                                                    \
         PMIX_INFO_CONSTRUCT(&_in);                                          \
         PMIX_INFO_LOAD(&_in, PMIX_SEND_HEARTBEAT, NULL, PMIX_POINTER);      \
         PMIx_Process_monitor_nb(&_in, PMIX_SUCCESS, NULL, 0, NULL, NULL);   \
         PMIX_INFO_DESTRUCT(&_in);                                           \
     } while(0)
 
 /* Request a credential from the PMIx server/SMS.
  * Input values include:
  *
  * info - an array of pmix_info_t structures containing any directives the
  *        caller may wish to pass. Typical usage might include:
  *            PMIX_TIMEOUT - how long to wait (in seconds) for a credential
  *                           before timing out and returning an error
  *            PMIX_CRED_TYPE - a prioritized, comma-delimited list of desired
  *                             credential types for use in environments where
  *                             multiple authentication mechanisms may be
  *                             available
  *
  * ninfo - number of elements in the info array
  *
  * cbfunc - the pmix_credential_cbfunc_t function to be called upon completion
  *          of the request
  *
  * cbdata - pointer to an object to be returned when cbfunc is called
  *
  * Returned values:
  * PMIX_SUCCESS - indicates that the request has been successfully communicated to
  *                the local PMIx server. The response will be coming in the provided
  *                callback function.
  *
  * Any other value indicates an appropriate error condition. The callback function
  * will _not_ be called in such cases.
  */
 PMIX_EXPORT pmix_status_t PMIx_Get_credential(const pmix_info_t info[], size_t ninfo,
                                               pmix_byte_object_t *credential);
 
 PMIX_EXPORT pmix_status_t PMIx_Get_credential_nb(const pmix_info_t info[], size_t ninfo,
                                                  pmix_credential_cbfunc_t cbfunc, void *cbdata);
 
 /* Request validation of a credential by the PMIx server/SMS
  * Input values include:
  *
  * cred - pointer to a pmix_byte_object_t containing the credential
  *
  * info - an array of pmix_info_t structures containing any directives the
  *        caller may wish to pass. Typical usage might include:
  *            PMIX_TIMEOUT - how long to wait (in seconds) for validation
  *                           before timing out and returning an error
  *            PMIX_USERID - the expected effective userid of the credential
  *                          to be validated
  *            PMIX_GROUPID - the expected effective group id of the credential
  *                          to be validated
  *
  * ninfo - number of elements in the info array
  *
  * cbfunc - the pmix_validation_cbfunc_t function to be called upon completion
  *          of the request
  *
  * cbdata - pointer to an object to be returned when cbfunc is called
  *
  * Returned values:
  * PMIX_SUCCESS - indicates that the request has been successfully communicated to
  *                the local PMIx server. The response will be coming in the provided
  *                callback function.
  *
  * Any other value indicates an appropriate error condition. The callback function
  * will _not_ be called in such cases.
  */
 PMIX_EXPORT pmix_status_t PMIx_Validate_credential(const pmix_byte_object_t *cred,
                                                    const pmix_info_t info[], size_t ninfo,
                                                    pmix_info_t **results, size_t *nresults);
 
 PMIX_EXPORT pmix_status_t PMIx_Validate_credential_nb(const pmix_byte_object_t *cred,
                                                       const pmix_info_t info[], size_t ninfo,
                                                       pmix_validation_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Construct a new group composed of the specified processes and identified with
  * the provided group identifier. Both blocking and non-blocking versions
  * are provided (the callback function for the non-blocking form will be called
  * once all specified processes have joined the group). The group identifier is
  * a user-defined, NULL-terminated character array of length less than or equal
  * to PMIX_MAX_NSLEN. Only characters accepted by standard string comparison
  * functions (e.g., strncmp) are supported.
  *
  * Processes may engage in multiple simultaneous group construct operations as
  * desired so long as each is provided with a unique group ID. The info array
  * can be used to pass user-level directives regarding timeout constraints and
  * other options available from the PMIx server.
  *
  * The construct leader (if PMIX_GROUP_LEADER is provided) or all participants
  * will receive events (if registered for the PMIX_GROUP_MEMBER_FAILED event)
  * whenever a process fails or terminates prior to calling
  * PMIx_Group_construct(_nb) – the events will contain the identifier of the
  * process that failed to join plus any other information that the resource
  * manager provided. This provides an opportunity for the leader to react to
  * the event – e.g., to invite an alternative member to the group or to decide
  * to proceed with a smaller group. The decision to proceed with a smaller group
  * is communicated to the PMIx library in the results array at the end of the
  * event handler. This allows PMIx to properly adjust accounting for procedure
  * completion. When construct is complete, the participating PMIx servers will
  * be alerted to any change in participants and each group member will (if
  * registered) receive a PMIX_GROUP_MEMBERSHIP_UPDATE event updating the group
  * membership.
  *
  * Processes in a group under construction are not allowed to leave the group
  * until group construction is complete. Upon completion of the construct
  * procedure, each group member will have access to the job-level information
  * of all nspaces represented in the group and the contact information for
  * every group member.
  *
  * Failure of the leader at any time will cause a PMIX_GROUP_LEADER_FAILED event
  * to be delivered to all participants so they can optionally declare a new leader.
  * A new leader is identified by providing the PMIX_GROUP_LEADER attribute in
  * the results array in the return of the event handler. Only one process is
  * allowed to return that attribute, declaring itself as the new leader. Results
  * of the leader selection will be communicated to all participants via a
  * PMIX_GROUP_LEADER_SELECTED event identifying the new leader. If no leader
  * was selected, then the status code provided in the event handler will provide
  * an error value so the participants can take appropriate action.
  *
  * Any participant that returns PMIX_GROUP_CONSTRUCT_ABORT from the leader failed
  * event handler will cause the construct process to abort. Those processes
  * engaged in the blocking construct will return from the call with the
  * PMIX_GROUP_CONSTRUCT_ABORT status. Non-blocking participants will have
  * their callback function executed with that status.
  *
  * Some relevant attributes for this operation:
  *    PMIX_GROUP_LEADER - declare this process to be the leader of the construction
  *                        procedure. If a process provides this attribute, then
  *                        failure notification for any participating process will
  *                        go only to that one process. In the absence of a
  *                        declared leader, failure events go to all participants.
  *    PMIX_GROUP_OPTIONAL - participation is optional - do not return an error if
  *                          any of the specified processes terminate
  *                          without having joined (default=false)
  *    PMIX_GROUP_NOTIFY_TERMINATION - notify remaining members when another member
  *                                    terminates without first leaving the
  *                                    group (default=false)
  *    PMIX_GROUP_ASSIGN_CONTEXT_ID - requests that the RM assign a unique context
  *                                   ID (size_t) to the group. The value is returned
  *                                   in the PMIX_GROUP_CONSTRUCT_COMPLETE event
  *    PMIX_TIMEOUT - return an error if the group doesn't assemble within the
  *                   specified number of seconds. Targets the scenario where a
  *                   process fails to call PMIx_Group_connect due to hanging
  *
  */
 PMIX_EXPORT pmix_status_t PMIx_Group_construct(const char grp[],
                                                const pmix_proc_t procs[], size_t nprocs,
                                                const pmix_info_t directives[], size_t ndirs,
                                                pmix_info_t **results, size_t *nresults);
 
 PMIX_EXPORT pmix_status_t PMIx_Group_construct_nb(const char grp[],
                                                   const pmix_proc_t procs[], size_t nprocs,
                                                   const pmix_info_t info[], size_t ninfo,
                                                   pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Explicitly invite specified processes to join a group.
  *
  * Each invited process will be notified of the invitation via the PMIX_GROUP_INVITED
  * event. The processes being invited must have registered for the PMIX_GROUP_INVITED
  * event in order to be notified of the invitation. When ready to respond, each invited
  * process provides a response using the appropriate form of PMIx_Group_join. This will
  * notify the inviting process that the invitation was either accepted (via the
  * PMIX_GROUP_INVITE_ACCEPTED event) or declined (via the PMIX_GROUP_INVITE_DECLINED event).
  * The inviting process will also receive PMIX_GROUP_MEMBER_FAILED events whenever a
  * process fails or terminates prior to responding to the invitation.
  *
  * Upon accepting the invitation, both the inviting and invited process will receive
  * access to the job-level information of each other’s nspaces and the contact
  * information of the other process.
  *
  * Some relevant attributes for this operation:
  *    PMIX_GROUP_ASSIGN_CONTEXT_ID - requests that the RM assign a unique context
  *                                   ID (size_t) to the group. The value is returned
  *                                   in the PMIX_GROUP_CONSTRUCT_COMPLETE event
  *    PMIX_TIMEOUT (int): return an error if the group doesn’t assemble within the
  *                        specified number of seconds. Targets the scenario where a
  *                        process fails to call PMIx_Group_connect due to hanging
  *
  * The inviting process is automatically considered the leader of the asynchronous
  * group construction procedure and will receive all failure or termination events
  * for invited members prior to completion. The inviting process is required to
  * provide a PMIX_GROUP_CONSTRUCT_COMPLETE event once the group has been fully
  * assembled – this event will be distributed to all participants along with the
  * final membership.
  *
  * Failure of the leader at any time will cause a PMIX_GROUP_LEADER_FAILED event
  * to be delivered to all participants so they can optionally declare a new leader.
  * A new leader is identified by providing the PMIX_GROUP_LEADER attribute in
  * the results array in the return of the event handler. Only one process is
  * allowed to return that attribute, declaring itself as the new leader. Results
  * of the leader selection will be communicated to all participants via a
  * PMIX_GROUP_LEADER_SELECTED event identifying the new leader. If no leader
  * was selected, then the status code provided in the event handler will provide
  * an error value so the participants can take appropriate action.
  *
  * Any participant that returns PMIX_GROUP_CONSTRUCT_ABORT from the event
  * handler will cause all participants to receive an event notifying them
  * of that status.
  */
 PMIX_EXPORT pmix_status_t PMIx_Group_invite(const char grp[],
                                             const pmix_proc_t procs[], size_t nprocs,
                                             const pmix_info_t info[], size_t ninfo,
                                             pmix_info_t **results, size_t *nresult);
 
 PMIX_EXPORT pmix_status_t PMIx_Group_invite_nb(const char grp[],
                                                const pmix_proc_t procs[], size_t nprocs,
                                                const pmix_info_t info[], size_t ninfo,
                                                pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Respond to an invitation to join a group that is being asynchronously constructed.
  *
  * The process must have registered for the PMIX_GROUP_INVITED event in order to be
  * notified of the invitation. When ready to respond, the process provides a response
  * using the appropriate form of PMIx_Group_join.
  *
  * Critical Note: Since the process is alerted to the invitation in a PMIx event handler,
  * the process must not use the blocking form of this call unless it first “thread shifts”
  * out of the handler and into its own thread context. Likewise, while it is safe to call
  * the non-blocking form of the API from the event handler, the process must not block
  * in the handler while waiting for the callback function to be called.
  *
  * Calling this function causes the group “leader” to be notified that the process has
  * either accepted or declined the request. The blocking form of the API will return
  * once the group has been completely constructed or the group’s construction has failed
  * (as determined by the leader) – likewise, the callback function of the non-blocking
  * form will be executed upon the same conditions.
  *
  * Failure of the leader at any time will cause a PMIX_GROUP_LEADER_FAILED event
  * to be delivered to all participants so they can optionally declare a new leader.
  * A new leader is identified by providing the PMIX_GROUP_LEADER attribute in
  * the results array in the return of the event handler. Only one process is
  * allowed to return that attribute, declaring itself as the new leader. Results
  * of the leader selection will be communicated to all participants via a
  * PMIX_GROUP_LEADER_SELECTED event identifying the new leader. If no leader
  * was selected, then the status code provided in the event handler will provide
  * an error value so the participants can take appropriate action.
  *
  * Any participant that returns PMIX_GROUP_CONSTRUCT_ABORT from the leader failed
  * event handler will cause all participants to receive an event notifying them
  * of that status. Similarly, the leader may elect to abort the procedure
  * by either returning PMIX_GROUP_CONSTRUCT_ABORT from the handler assigned
  * to the PMIX_GROUP_INVITE_ACCEPTED or PMIX_GROUP_INVITE_DECLINED codes, or
  * by generating an event for the abort code. Abort events will be sent to
  * all invited participants.
  */
 PMIX_EXPORT pmix_status_t PMIx_Group_join(const char grp[],
                                           const pmix_proc_t *leader,
                                           pmix_group_opt_t opt,
                                           const pmix_info_t info[], size_t ninfo,
                                           pmix_info_t **results, size_t *nresult);
 
 PMIX_EXPORT pmix_status_t PMIx_Group_join_nb(const char grp[],
                                              const pmix_proc_t *leader,
                                              pmix_group_opt_t opt,
                                              const pmix_info_t info[], size_t ninfo,
                                              pmix_info_cbfunc_t cbfunc, void *cbdata);
 
 /* Leave a PMIx Group. Calls to PMIx_Group_leave (or its non-blocking form) will cause
  * a PMIX_GROUP_LEFT event to be generated notifying all members of the group of the
  * caller’s departure. The function will return (or the non-blocking function will
  * execute the specified callback function) once the event has been locally generated
  * and is not indicative of remote receipt. All PMIx-based collectives such as
  * PMIx_Fence in action across the group will automatically be adjusted if the
  * collective was called with the PMIX_GROUP_FT_COLLECTIVE attribute (default is
  * false) – otherwise, the standard error return behavior will be provided.
  *
  * Critical Note: The PMIx_Group_leave API is intended solely for asynchronous
  * departures of individual processes from a group as it is not a scalable
  * operation – i.e., when a process determines it should no longer be a part of a
  * defined group, but the remainder of the group retains a valid reason to continue
  * in existence. Developers are advised to use PMIx_Group_destruct (or its
  * non-blocking form) for all other scenarios as it represents a more scalable
  * operation.
  */
 PMIX_EXPORT pmix_status_t PMIx_Group_leave(const char grp[],
                                            const pmix_info_t info[], size_t ninfo);
 
 PMIX_EXPORT pmix_status_t PMIx_Group_leave_nb(const char grp[],
                                               const pmix_info_t info[], size_t ninfo,
                                               pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /* Destruct a group identified by the provided group identifier. Both blocking and
  * non-blocking versions are provided (the callback function for the non-blocking
  * form will be called once all members of the group have called “destruct”).
  * Processes may engage in multiple simultaneous group destruct operations as
  * desired so long as each involves a unique group ID. The info array can be used
  * to pass user-level directives regarding timeout constraints and other options
  * available from the PMIx server.
  *
  * Some relevant attributes for this operation:
  *
  *    PMIX_TIMEOUT (int): return an error if the group doesn’t destruct within the
  *                        specified number of seconds. Targets the scenario where
  *                        a process fails to call PMIx_Group_destruct due to hanging
  *
  * The destruct API will return an error if any group process fails or terminates
  * prior to calling PMIx_Group_destruct or its non-blocking version unless the
  * PMIX_GROUP_NOTIFY_TERMINATION attribute was provided (with a value of true) at
  * time of group construction. If notification was requested, then a event will
  * be delivered (using PMIX_GROUP_MEMBER_FAILED) for each process that fails to
  * call destruct and the destruct tracker updated to account for the lack of
  * participation. The PMIx_Group_destruct operation will subsequently return
  * PMIX_SUCCESS when the remaining processes have all called destruct – i.e., the
  * event will serve in place of return of an error.
  */
 PMIX_EXPORT pmix_status_t PMIx_Group_destruct(const char grp[],
                                               const pmix_info_t info[], size_t ninfo);
 
 PMIX_EXPORT pmix_status_t PMIx_Group_destruct_nb(const char grp[],
                                                  const pmix_info_t info[], size_t ninfo,
                                                  pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 /****************************************/
 /****    COMMON SUPPORT FUNCTIONS    ****/
 /****************************************/
 
 /******     EVENT NOTIFICATION SUPPORT      ******/
 /* Register an event handler to report events. Three types of events
  * can be reported:
  *
  * (a) those that occur within the client library, but are not
  *     reportable via the API itself (e.g., loss of connection to
  *     the server). These events typically occur during behind-the-scenes
  *     non-blocking operations.
  *
  * (b) job-related events such as the failure of another process in
  *     the job or in any connected job, impending failure of hardware
  *     within the job's usage footprint, etc.
  *
  * (c) system notifications that are made available by the local
  *     administrators
  *
  * By default, only events that directly affect the process and/or
  * any process to which it is connected (via the PMIx_Connect call)
  * will be reported. Options to modify that behavior can be provided
  * in the info array
  *
  * Both the client application and the resource manager can register
  * err handlers for specific events. PMIx client/server calls the registered
  * err handler upon receiving event notify notification (via PMIx_Notify_event)
  * from the other end (Resource Manager/Client application).
  *
  * Multiple err handlers can be registered for different events. PMIX returns
  * an integer reference to each register handler in the callback fn. The caller
  * must retain the reference in order to deregister the evhdlr.
  * Modification of the notification behavior can be accomplished by
  * deregistering the current evhdlr, and then registering it
  * using a new set of info values.
  *
  * If cbfunc is NULL, then this is treated as a BLOCKING call - a positive
  * return value represents the reference ID for the request, while
  * negative values indicate the corresponding error
  *
  * See pmix_common.h for a description of the notification function */
 PMIX_EXPORT pmix_status_t PMIx_Register_event_handler(pmix_status_t codes[], size_t ncodes,
                                                       pmix_info_t info[], size_t ninfo,
                                                       pmix_notification_fn_t evhdlr,
                                                       pmix_hdlr_reg_cbfunc_t cbfunc,
                                                       void *cbdata);
 
 /* Deregister an event handler
  * evhdlr_ref is the reference returned by PMIx from the call to
  * PMIx_Register_event_handler. If non-NULL, the provided cbfunc
  * will be called to confirm removal of the designated handler */
 PMIX_EXPORT pmix_status_t PMIx_Deregister_event_handler(size_t evhdlr_ref,
                                                         pmix_op_cbfunc_t cbfunc,
                                                         void *cbdata);
 
 /* Report an event for notification via any
  * registered evhdlr.
  *
  * This function allows the host server to direct the server
  * convenience library to notify all registered local procs of
  * an event. The event can be local, or anywhere in the cluster.
  * The status indicates the event being reported.
  *
  * The client application can also call this function to notify the
  * resource manager and/or other processes of an event it encountered.
  * It can also be used to asynchronously notify other parts of its
  * own internal process - e.g., for one library to notify another
  * when initialized inside the process.
  *
  * status - status code indicating the event being reported
  *
  * source - the process that generated the event
  *
  * range - the range in which the event is to be reported. For example,
  *         a value of PMIX_RANGE_LOCAL would instruct the system
  *         to only notify procs on the same local node as the
  *         event generator.
  *
  * info - an array of pmix_info_t structures provided by the event
  *        generator to pass any additional information about the
  *        event. This can include an array of pmix_proc_t structs
  *        describing the processes impacted by the event, the nature
  *        of the event and its severity, etc. The precise contents
  *        of the array will depend on the event generator.
  *
  * ninfo - number of elements in the info array
  *
  * cbfunc - callback function to be called upon completion of the
  *          notify_event function's actions. Note that any messages
  *          will have been queued, but may not have been transmitted
  *          by this time. Note that the caller is required to maintain
  *          the input data until the callback function has been executed!
  *          If cbfunc is NULL, then this is treated as a BLOCKING call and
  *          the result of the operation is provided in the returned
  *          status
  *
  * cbdata - the caller's provided void* object
  */
 PMIX_EXPORT pmix_status_t PMIx_Notify_event(pmix_status_t status,
                                             const pmix_proc_t *source,
                                             pmix_data_range_t range,
                                             const pmix_info_t info[], size_t ninfo,
                                             pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /******    FABRIC-RELATED APIS    ******/
 /* Register for access to fabric-related information, including
  * communication cost matrix. This call must be made prior to
  * requesting information from a fabric.
  *
  * fabric - address of a pmix_fabric_t (backed by storage). User
  *          may populate the "name" field at will - PMIx does not
  *          utilize this field
  *
  * directives - an optional array of values indicating desired
  *              behaviors and/or fabric to be accessed. If NULL,
  *              then the highest priority available fabric will
  *              be used
  *
  * ndirs - number of elements in the directives array
  *
  * Return values include:
  *
  * PMIX_SUCCESS - indicates success
  */
 PMIX_EXPORT pmix_status_t PMIx_Fabric_register(pmix_fabric_t *fabric,
                                                const pmix_info_t directives[],
                                                size_t ndirs);
 
 PMIX_EXPORT pmix_status_t PMIx_Fabric_register_nb(pmix_fabric_t *fabric,
                                                   const pmix_info_t directives[],
                                                   size_t ndirs,
                                                   pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Update fabric-related information. This call can be made at any time to request an update of the
  * fabric information contained in the provided pmix_fabric_t object. The caller is not allowed
  * to access the provided pmix_fabric_t until the call has returned.
  *
  * fabric - pointer to the pmix_fabric_t struct provided to
  *          the registration function
  *
  * Return values include:
  *
  * PMIX_SUCCESS - indicates successful update
  */
 PMIX_EXPORT pmix_status_t PMIx_Fabric_update(pmix_fabric_t *fabric);
 
 PMIX_EXPORT pmix_status_t PMIx_Fabric_update_nb(pmix_fabric_t *fabric,
                                                 pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Deregister a fabric object, providing an opportunity for
  * the PMIx server library to cleanup any information
  * (e.g., cost matrix) associated with it
  *
  * fabric - pointer to the pmix_fabric_t struct provided
  *          to the registration function
  */
 PMIX_EXPORT pmix_status_t PMIx_Fabric_deregister(pmix_fabric_t *fabric);
 
 PMIX_EXPORT pmix_status_t PMIx_Fabric_deregister_nb(pmix_fabric_t *fabric,
                                                     pmix_op_cbfunc_t cbfunc, void *cbdata);
 
 
 /* Compute the distance information for the current process
  * Returns an array of distances from the current process
  * location to each of the local devices of the specified type(s)
  *
  * distances - pointer to location where the array of
  *             distances is to be returned
  *
  * ndist - number of elements in the distances array
  *
  * Return values include:
  *
  * PMIX_SUCCESS - distance array was successfully returned
  * Other error
  */
 PMIX_EXPORT pmix_status_t PMIx_Compute_distances(pmix_topology_t *topo,
                                                  pmix_cpuset_t *cpuset,
                                                  pmix_info_t info[], size_t ninfo,
                                                  pmix_device_distance_t *distances[],
                                                  size_t *ndist);
 
 PMIX_EXPORT pmix_status_t PMIx_Compute_distances_nb(pmix_topology_t *topo,
                                                     pmix_cpuset_t *cpuset,
                                                     pmix_info_t info[], size_t ninfo,
                                                     pmix_device_dist_cbfunc_t cbfunc,
                                                     void *cbdata);
 
 /* Load the local hwardware topology description
  *
  * topo - pointer to a pmix_topology_t object. This object
  *        must be initialized! If the a particular "source"
  *        for the topology is required (e.g., "hwloc"), then
  *        the "source" field of the object must be set to
  *        that value
  *
  * Return values include:
  * PMIX_SUCCESS - indicates return of a valid value
  * PMIX_ERR_NOT_FOUND - provided source is not available
  * PMIX_ERR_NOT_SUPPORTED - current implementation does not support this option
  */
 PMIX_EXPORT pmix_status_t PMIx_Load_topology(pmix_topology_t *topo);
 
 /* Get the PU binding bitmap from its string representation
  *
  * cpuset_string - string representation of the binding bitmap
  *                 (as returned by PMIx_Get using the PMIX_CPUSET key)
  *
  * cpuset - pointer to a pmix_cpuset_t object where the result
  *          is to be stored
  *
  * Return values include:
  * PMIX_SUCCESS - indicates return of a valid value
  * PMIX_ERR_NOT_FOUND - provided source is not available
  * PMIX_ERR_NOT_SUPPORTED - current implementation does not support this option
  */
 PMIX_EXPORT pmix_status_t PMIx_Parse_cpuset_string(const char *cpuset_string,
                                                    pmix_cpuset_t *cpuset);
 
 PMIX_EXPORT pmix_status_t PMIx_Get_cpuset(pmix_cpuset_t *cpuset, pmix_bind_envelope_t ref);
 
 /* Get the relative locality of two local processes given their locality strings.
  *
  * locality1 - String returned by the PMIx_server_generate_locality_string API
  *
  * locality2 - String returned by the PMIx_server_generate_locality_string API
  *
  * locality - Pointer to the location where the relative locality bitmask is
  *            to be constructed
  *
  * Return values include:
  * PMIX_SUCCESS - indicates return of a valid value
  * other error constant
  */
 PMIX_EXPORT pmix_status_t PMIx_Get_relative_locality(const char *locality1,
                                                      const char *locality2,
                                                      pmix_locality_t *locality);
 
 PMIX_EXPORT void PMIx_Progress(void);
 
 /******    PRETTY-PRINT DEFINED VALUE TYPES     ******/
 /* Provide a string representation for several types of value. Note
  * that the provided string is statically defined and must NOT be
  * free'd. Supported value types:
  *
  * - pmix_status_t (PMIX_STATUS)
  * - pmix_scope_t   (PMIX_SCOPE)
  * - pmix_persistence_t  (PMIX_PERSIST)
  * - pmix_data_range_t   (PMIX_DATA_RANGE)
  * - pmix_info_directives_t   (PMIX_INFO_DIRECTIVES)
  * - pmix_data_type_t   (PMIX_DATA_TYPE)
  * - pmix_alloc_directive_t  (PMIX_ALLOC_DIRECTIVE)
  * - pmix_iof_channel_t  (PMIX_IOF_CHANNEL)
  * - pmix_job_state_t  (PMIX_JOB_STATE)
  * - pmix_proc_state_t  (PMIX_PROC_STATE)
  * - attribute string value of provided name
  * - attribute name corresponding to provided string
  * - pmix_link_state_t (PMIX_LINK_STATE)
  * - pmix_device_type_t (PMIX_DEVTYPE)
  * - pmix_value_cmp_t (enum)
  * - pmix_info_t (PMIX_INFO)
  * - pmix_value_t (PMIX_VALUE)
  * - pmix_info_directives_t (PMIX_INFO_DIRECTIVES)
  * - pmix_app_t (PMIX_APP)
  */
 PMIX_EXPORT const char* PMIx_Error_string(pmix_status_t status);
 PMIX_EXPORT pmix_status_t PMIx_Error_code(const char *errname);
 PMIX_EXPORT const char* PMIx_Proc_state_string(pmix_proc_state_t state);
 PMIX_EXPORT const char* PMIx_Scope_string(pmix_scope_t scope);
 PMIX_EXPORT const char* PMIx_Persistence_string(pmix_persistence_t persist);
 PMIX_EXPORT const char* PMIx_Data_range_string(pmix_data_range_t range);
 PMIX_EXPORT const char* PMIx_Data_type_string(pmix_data_type_t type);
 PMIX_EXPORT const char* PMIx_Alloc_directive_string(pmix_alloc_directive_t directive);
 PMIX_EXPORT const char* PMIx_IOF_channel_string(pmix_iof_channel_t channel);
 PMIX_EXPORT const char* PMIx_Job_state_string(pmix_job_state_t state);
 PMIX_EXPORT const char* PMIx_Get_attribute_string(const char *attribute);
 PMIX_EXPORT const char* PMIx_Get_attribute_name(const char *attrstring);
 PMIX_EXPORT const char* PMIx_Link_state_string(pmix_link_state_t state);
 PMIX_EXPORT const char* PMIx_Device_type_string(pmix_device_type_t type);
 PMIX_EXPORT const char* PMIx_Value_comparison_string(pmix_value_cmp_t cmp);
 
 /* the following print statements return ALLOCATED strings
  * that the user must release when done */
 PMIX_EXPORT char* PMIx_Info_string(const pmix_info_t *info);
 PMIX_EXPORT char* PMIx_Value_string(const pmix_value_t *value);
 PMIX_EXPORT char* PMIx_Info_directives_string(pmix_info_directives_t directives);
 PMIX_EXPORT char* PMIx_App_string(const pmix_app_t *app);
 PMIX_EXPORT char* PMIx_Proc_string(const pmix_proc_t *proc);
 
 /* Get the PMIx version string. Note that the provided string is
  * statically defined and must NOT be free'd  */
 PMIX_EXPORT const char* PMIx_Get_version(void);
 
 /* Store some data locally for retrieval by other areas of the
  * proc. This is data that has only internal scope - it will
  * never be "pushed" externally */
 PMIX_EXPORT pmix_status_t PMIx_Store_internal(const pmix_proc_t *proc,
                                               const char key[], pmix_value_t *val);
 
 
 /* Compute and return the size (in bytes) of the data
  * payload in a pmix_value_t structure. Returns:
  *
  * - PMIX_SUCCESS if the value could be computed
  *
  * - an appropriate error value (e.g., PMIX_ERR_UNKNOWN_DATA_TYPE
  *   if the data type is unknown) if the value could not be computed.
  */
 PMIX_EXPORT pmix_status_t PMIx_Value_get_size(const pmix_value_t *val,
                                               size_t *size);
 
 /* Compute and return the size (in bytes) of the data
  * payload in a pmix_info_t structure. Returns:
  *
  * - PMIX_SUCCESS if the value could be computed
  *
  * - an appropriate error value (e.g., PMIX_ERR_UNKNOWN_DATA_TYPE
  *   if the data type is unknown) if the value could not be computed.
  */
 PMIX_EXPORT pmix_status_t PMIx_Info_get_size(const pmix_info_t *val,
                                              size_t *size);
 
 
 /******    DATA BUFFER PACK/UNPACK SUPPORT    ******/
 /**
  * Top-level interface function to pack one or more values into a
  * buffer.
  *
  * The pack function packs one or more values of a specified type into
  * the specified buffer.  The buffer must have already been
  * initialized via the PMIX_DATA_BUFFER_CREATE or PMIX_DATA_BUFFER_CONSTRUCT
  * call - otherwise, the pack_value function will return an error.
  * Providing an unsupported type flag will likewise be reported as an error.
  *
  * Note that any data to be packed that is not hard type cast (i.e.,
  * not type cast to a specific size) may lose precision when unpacked
  * by a non-homogeneous recipient.  The PACK function will do its best to deal
  * with heterogeneity issues between the packer and unpacker in such
  * cases. Sending a number larger than can be handled by the recipient
  * will return an error code (generated upon unpacking) -
  * the error cannot be detected during packing.
  *
  * The identity of the intended recipient of the packed buffer (i.e., the
  * process that will be unpacking it) is used solely to resolve any data type
  * differences between PMIx versions. The recipient must, therefore, be
  * known to the user prior to calling the pack function so that the
  * PMIx library is aware of the version the recipient is using.
  *
  * @param *target Pointer to a pmix_proc_t structure containing the
  * nspace/rank of the process that will be unpacking the final buffer.
  * A NULL value may be used to indicate that the target is based on
  * the same PMIx version as the caller.
  *
  * @param *buffer A pointer to the buffer into which the value is to
  * be packed.
  *
  * @param *src A void* pointer to the data that is to be packed. Note
  * that strings are to be passed as (char **) - i.e., the caller must
  * pass the address of the pointer to the string as the void*. This
  * allows PMIx to use a single pack function, but still allow
  * the caller to pass multiple strings in a single call.
  *
  * @param num_values An int32_t indicating the number of values that are
  * to be packed, beginning at the location pointed to by src. A string
  * value is counted as a single value regardless of length. The values
  * must be contiguous in memory. Arrays of pointers (e.g., string
  * arrays) should be contiguous, although (obviously) the data pointed
  * to need not be contiguous across array entries.
  *
  * @param type The type of the data to be packed - must be one of the
  * PMIX defined data types.
  *
  * @retval PMIX_SUCCESS The data was packed as requested.
  *
  * @retval PMIX_ERROR(s) An appropriate PMIX error code indicating the
  * problem encountered. This error code should be handled
  * appropriately.
  *
  * @code
  * pmix_data_buffer_t *buffer;
  * int32_t src;
  *
  * PMIX_DATA_BUFFER_CREATE(buffer);
  * status_code = PMIx_Data_pack(buffer, &src, 1, PMIX_INT32);
  * @endcode
  */
 PMIX_EXPORT pmix_status_t PMIx_Data_pack(const pmix_proc_t *target,
                                          pmix_data_buffer_t *buffer,
                                          void *src, int32_t num_vals,
                                          pmix_data_type_t type);
 
 /**
  * Unpack values from a buffer.
  *
  * The unpack function unpacks the next value (or values) of a
  * specified type from the specified buffer.
  *
  * The buffer must have already been initialized via an PMIX_DATA_BUFFER_CREATE or
  * PMIX_DATA_BUFFER_CONSTRUCT call (and assumedly filled with some data) -
  * otherwise, the unpack_value function will return an
  * error. Providing an unsupported type flag will likewise be reported
  * as an error, as will specifying a data type that DOES NOT match the
  * type of the next item in the buffer. An attempt to read beyond the
  * end of the stored data held in the buffer will also return an
  * error.
  *
  * NOTE: it is possible for the buffer to be corrupted and that
  * PMIx will *think* there is a proper variable type at the
  * beginning of an unpack region - but that the value is bogus (e.g., just
  * a byte field in a string array that so happens to have a value that
  * matches the specified data type flag). Therefore, the data type error check
  * is NOT completely safe. This is true for ALL unpack functions.
  *
  *
  * Unpacking values is a "nondestructive" process - i.e., the values are
  * not removed from the buffer. It is therefore possible for the caller
  * to re-unpack a value from the same buffer by resetting the unpack_ptr.
  *
  * Warning: The caller is responsible for providing adequate memory
  * storage for the requested data. As noted below, the user
  * must provide a parameter indicating the maximum number of values that
  * can be unpacked into the allocated memory. If more values exist in the
  * buffer than can fit into the memory storage, then the function will unpack
  * what it can fit into that location and return an error code indicating
  * that the buffer was only partially unpacked.
  *
  * Note that any data that was not hard type cast (i.e., not type cast
  * to a specific size) when packed may lose precision when unpacked by
  * a non-homogeneous recipient.  PMIx will do its best to deal with
  * heterogeneity issues between the packer and unpacker in such
  * cases. Sending a number larger than can be handled by the recipient
  * will return an error code generated upon unpacking - these errors
  * cannot be detected during packing.
  *
  * The identity of the source of the packed buffer (i.e., the
  * process that packed it) is used solely to resolve any data type
  * differences between PMIx versions. The source must, therefore, be
  * known to the user prior to calling the unpack function so that the
  * PMIx library is aware of the version the source used.
  *
  * @param *source Pointer to a pmix_proc_t structure containing the
  * nspace/rank of the process that packed the provided buffer.
  * A NULL value may be used to indicate that the source is based on
  * the same PMIx version as the caller.
  *
  * @param *buffer A pointer to the buffer from which the value will be
  * extracted.
  *
  * @param *dest A void* pointer to the memory location into which the
  * data is to be stored. Note that these values will be stored
  * contiguously in memory. For strings, this pointer must be to (char
  * **) to provide a means of supporting multiple string
  * operations. The unpack function will allocate memory for each
  * string in the array - the caller must only provide adequate memory
  * for the array of pointers.
  *
  * @param type The type of the data to be unpacked - must be one of
  * the BFROP defined data types.
  *
  * @retval *max_num_values The number of values actually unpacked. In
  * most cases, this should match the maximum number provided in the
  * parameters - but in no case will it exceed the value of this
  * parameter.  Note that if you unpack fewer values than are actually
  * available, the buffer will be in an unpackable state - the function will
  * return an error code to warn of this condition.
  *
  * @note The unpack function will return the actual number of values
  * unpacked in this location.
  *
  * @retval PMIX_SUCCESS The next item in the buffer was successfully
  * unpacked.
  *
  * @retval PMIX_ERROR(s) The unpack function returns an error code
  * under one of several conditions: (a) the number of values in the
  * item exceeds the max num provided by the caller; (b) the type of
  * the next item in the buffer does not match the type specified by
  * the caller; or (c) the unpack failed due to either an error in the
  * buffer or an attempt to read past the end of the buffer.
  *
  * @code
  * pmix_data_buffer_t *buffer;
  * int32_t dest;
  * char **string_array;
  * int32_t num_values;
  *
  * num_values = 1;
  * status_code = PMIx_Data_unpack(buffer, (void*)&dest, &num_values, PMIX_INT32);
  *
  * num_values = 5;
  * string_array = pmix_malloc(num_values*sizeof(char *));
  * status_code = PMIx_Data_unpack(buffer, (void*)(string_array), &num_values, PMIX_STRING);
  *
  * @endcode
  */
 PMIX_EXPORT pmix_status_t PMIx_Data_unpack(const pmix_proc_t *source,
                                            pmix_data_buffer_t *buffer, void *dest,
                                            int32_t *max_num_values,
                                            pmix_data_type_t type);
 
 /**
  * Copy a data value from one location to another.
  *
  * Since registered data types can be complex structures, the system
  * needs some way to know how to copy the data from one location to
  * another (e.g., for storage in the registry). This function, which
  * can call other copy functions to build up complex data types, defines
  * the method for making a copy of the specified data type.
  *
  * @param **dest The address of a pointer into which the
  * address of the resulting data is to be stored.
  *
  * @param *src A pointer to the memory location from which the
  * data is to be copied.
  *
  * @param type The type of the data to be copied - must be one of
  * the PMIx defined data types.
  *
  * @retval PMIX_SUCCESS The value was successfully copied.
  *
  * @retval PMIX_ERROR(s) An appropriate error code.
  *
  */
 PMIX_EXPORT pmix_status_t PMIx_Data_copy(void **dest, void *src,
                                          pmix_data_type_t type);
 
 /**
  * Print a data value.
  *
  * Since registered data types can be complex structures, the system
  * needs some way to know how to print them (i.e., convert them to a string
  * representation). Provided for debug purposes.
  *
  * @retval PMIX_SUCCESS The value was successfully printed.
  *
  * @retval PMIX_ERROR(s) An appropriate error code.
  */
 PMIX_EXPORT pmix_status_t PMIx_Data_print(char **output, char *prefix,
                                           void *src, pmix_data_type_t type);
 
 /**
  * Copy a payload from one buffer to another
  *
  * This function will append a copy of the payload in one buffer into
  * another buffer.
  * NOTE: This is NOT a destructive procedure - the
  * source buffer's payload will remain intact, as will any pre-existing
  * payload in the destination's buffer.
  */
 PMIX_EXPORT pmix_status_t PMIx_Data_copy_payload(pmix_data_buffer_t *dest,
                                                  pmix_data_buffer_t *src);
 
 /**
  * Unload a buffer into a byte object
  *
  * The unload function provides the caller with a pointer to the data
  * payload within the buffer and the size of that payload. This allows
  * the user to directly access the payload.
  *
  * @note This is a destructive operation. While the payload is
  * undisturbed, the function will clear the buffer's pointers to the
  * payload. Thus, the buffer and the payload are completely separated,
  * leaving the caller free to release the buffer.
  *
  * @param buffer A pointer to the buffer whose payload is to be
  * unloaded.
  *
  * @param payload The address of a pmix_byte_object_t into which
  * the buffer is to be unloaded
  *
  * @retval PMIX_SUCCESS The request was successfully completed.
  *
  * @retval PMIX_ERROR(s) An appropriate error code indicating the
  * problem will be returned. This should be handled appropriately by
  * the caller.
  *
  * @code
  * pmix_data_buffer_t *buffer;
  * pmix_byte_object_t payload;
  *
  * status_code = PMIx_Data_unload(buffer, &payload);
  * @endcode
  */
 PMIX_EXPORT pmix_status_t PMIx_Data_unload(pmix_data_buffer_t *buffer,
                                            pmix_byte_object_t *payload);
 
 /**
  * Load a data payload into a buffer.
  *
  * The load function allows the caller to replace the payload in a
  * buffer with one provided by the caller. If a payload already exists
  * in the buffer, the function will "free" the existing data to
  * release it, and then replace the data payload with the one provided
  * by the caller.
  *
  * @note The buffer must be allocated in advance - failing to do so
  * will cause the load function to return an error code.
  *
  * @note The caller is responsible for pre-packing the provided
  * payload - the load function cannot convert to network byte order
  * any data contained in the provided payload.
  *
  * @note The "payload" object will be empty upon completion of
  * this operation.
  *
  * @param buffer A pointer to the buffer into which the payload is to
  * be loaded.
  *
  * @param payload A pointer to the pmix_byte_object_t .containing the
  * desired payload
  *
  * @retval PMIX_SUCCESS The request was successfully completed
  *
  * @retval PMIX_ERROR(s) An appropriate error code indicating the
  * problem will be returned. This should be handled appropriately by
  * the caller.
  *
  * @code
  * pmix_data_buffer_t *buffer;
  * pmix_byte_object_t payload;
  *
  * PMIX_DATA_BUFFER_CREATE(buffer);
  * status_code = PMIx_Data_load(buffer, &payload);
  * @endcode
  */
 PMIX_EXPORT pmix_status_t PMIx_Data_load(pmix_data_buffer_t *buffer,
                                          pmix_byte_object_t *payload);
 
 /**
 * Embed a data payload into a buffer.
 *
 * The embed function is identical in operation to PMIx_Data_load
 * except that it does NOT "clear" the payload upon completion.
 *
 * @note The buffer must be allocated in advance - failing to do so
 * will cause the function to return an error code.
 *
 * @note The caller is responsible for pre-packing the provided
 * payload - the load function cannot convert to network byte order
 * any data contained in the provided payload.
 *
 * @note The "payload" object is unaltered by this operation.
 *
 * @param buffer A pointer to the buffer into which the payload is to
 * be loaded.
 *
 * @param payload A pointer to the pmix_byte_object_t .containing the
 * desired payload
 *
 * @retval PMIX_SUCCESS The request was successfully completed
 *
 * @retval PMIX_ERROR(s) An appropriate error code indicating the
 * problem will be returned. This should be handled appropriately by
 * the caller.
 *
 * @code
 * pmix_data_buffer_t *buffer;
 * pmix_byte_object_t payload;
 *
 * PMIX_DATA_BUFFER_CREATE(buffer);
 * status_code = PMIx_Data_embed(buffer, &payload);
 * @endcode
 */
 PMIX_EXPORT pmix_status_t PMIx_Data_embed(pmix_data_buffer_t *buffer,
                                           const pmix_byte_object_t *payload);
 
 /**
 * Compress data using loss-less compression algorithm.
 *
 * Compress the provided data block. Destination memory
 * will be allocated if successful operation is concluded. Caller
 * is responsible for release of the allocated region. The input
 * data block will remain unaltered.
 *
 * Note: the compress function will return "false" if the operation
 * would not result in a smaller data block.
 *
 * @param inbytes A pointer to the data to be compressed
 *
 * @param size Number of bytes in the input data region
 *
 * @param outbytes Address where a pointer to the compressed
 * data region is to be returned
 *
 * @param nbytes Address where the number of bytes in the
 * compressed data region is to be returned
 *
 * @retval true The input data was compressed.
 *
 * @retval false The input data was not compressed
 *
 */
 PMIX_EXPORT bool PMIx_Data_compress(const uint8_t *inbytes,
                                     size_t size,
                                     uint8_t **outbytes,
                                     size_t *nbytes);
 
 /**
 * Decompress data.
 *
 * Decompress the provided data block. Destination memory
 * will be allocated if successful operation is concluded. Caller
 * is responsible for release of the allocated region. The input
 * data block will remain unaltered.
 *
 * note: only data compressed using PMIx_Data_compress can
 * be input to this function
 *
 * @param inbytes A pointer to the data to be decompressed
 *
 * @param size Number of bytes in the input data region
 *
 * @param outbytes Address where a pointer to the decompressed
 * data region is to be returned
 *
 * @param nbytes Address where the number of bytes in the
 * decompressed data region is to be returned
 *
 * @retval true The input data was decompressed
 *
 * @retval false The input data was not decompressed
 *
 */
 PMIX_EXPORT bool PMIx_Data_decompress(const uint8_t *inbytes,
                                       size_t size,
                                       uint8_t **outbytes,
                                       size_t *nbytes);
 
 
 /* We had to put some function definitions into pmix_deprecated.h for
  * now-deprecated macros that utilize them as there are people who only
  * included pmix_common.h if they were using macros but not APIs.
  * However, we really want those APIs here so people will
  * see them and know they exist. So include them here as well. */
 
 #ifndef PMIx_DEPRECATED_H
 
 /* load a key */
 PMIX_EXPORT void PMIx_Load_key(pmix_key_t key, const char *src);
 
 /* check a key */
 PMIX_EXPORT bool PMIx_Check_key(const char *key, const char *str);
 
 /* check to see if a key is a "reserved" key */
 PMIX_EXPORT bool PMIx_Check_reserved_key(const char *key);
 
 /* load a string into a pmix_nspace_t struct */
 PMIX_EXPORT void PMIx_Load_nspace(pmix_nspace_t nspace, const char *str);
 
 /* check two nspace structs for equality */
 PMIX_EXPORT bool PMIx_Check_nspace(const char *key1, const char *key2);
 
 /* check if a namespace is invalid */
 PMIX_EXPORT bool PMIx_Nspace_invalid(const char *nspace);
 
 /* load a process ID struct */
 PMIX_EXPORT void PMIx_Load_procid(pmix_proc_t *p, 
                                   const char *ns,
                                   pmix_rank_t rk);
 
 /* transfer a process ID struct (non-destructive) */
 PMIX_EXPORT void PMIx_Xfer_procid(pmix_proc_t *dst,
                                   const pmix_proc_t *src);
 
 /* check two procIDs for equality */
 PMIX_EXPORT bool PMIx_Check_procid(const pmix_proc_t *a,
                                    const pmix_proc_t *b);
 
 /* check two ranks for equality */
 PMIX_EXPORT bool PMIx_Check_rank(pmix_rank_t a,
                                  pmix_rank_t b);
 
 /* check if procID is invalid */
 PMIX_EXPORT bool PMIx_Procid_invalid(const pmix_proc_t *p);
 
 PMIX_EXPORT int PMIx_Argv_count(char **a);
 PMIX_EXPORT pmix_status_t PMIx_Argv_append_nosize(char ***argv, const char *arg);
 PMIX_EXPORT pmix_status_t PMIx_Argv_prepend_nosize(char ***argv, const char *arg);
 PMIX_EXPORT pmix_status_t PMIx_Argv_append_unique_nosize(char ***argv, const char *arg);
 PMIX_EXPORT void PMIx_Argv_free(char **argv);
 PMIX_EXPORT char **PMIx_Argv_split_inter(const char *src_string,
                                          int delimiter,
                                          bool include_empty);
 PMIX_EXPORT char **PMIx_Argv_split_with_empty(const char *src_string, int delimiter);
 PMIX_EXPORT char **PMIx_Argv_split(const char *src_string, int delimiter);
 PMIX_EXPORT char *PMIx_Argv_join(char **argv, int delimiter);
 PMIX_EXPORT char **PMIx_Argv_copy(char **argv);
 PMIX_EXPORT pmix_status_t PMIx_Setenv(const char *name,
                                       const char *value,
                                       bool overwrite,
                                       char ***env);
 
 /* initialize a value struct */
 PMIX_EXPORT void PMIx_Value_construct(pmix_value_t *val);
 
 /* free memory stored inside a value struct */
 PMIX_EXPORT void PMIx_Value_destruct(pmix_value_t *val);
 
 /* create and initialize an array of value structs */
 PMIX_EXPORT pmix_value_t* PMIx_Value_create(size_t n);
 
 /* free memory stored inside an array of coord structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Value_free(pmix_value_t *v, size_t n);
 
 /* Check the given value struct to determine if it includes
  * a boolean value (includes strings for "true" and "false",
  * including abbreviations such as "t" or "f"), and if so,
  * then its value. A value type of PMIX_UNDEF is taken to imply
  * a boolean "true". */
 PMIX_EXPORT pmix_boolean_t PMIx_Value_true(const pmix_value_t *v);
 
 /* Load data into a pmix_value_t structure. The data can be of any
  * PMIx data type - which means the load can be somewhat complex
  * to implement (e.g., in the case of a pmix_data_array_t). The
  * data is COPIED into the value struct
  */
 PMIX_EXPORT pmix_status_t PMIx_Value_load(pmix_value_t *val,
                                           const void *data,
                                           pmix_data_type_t type);
 
 /* Unload data from a pmix_value_t structure. */
 PMIX_EXPORT pmix_status_t PMIx_Value_unload(pmix_value_t *val,
                                             void **data,
                                             size_t *sz);
 
 /* Transfer data from one pmix_value_t to another - this is actually
  * executed as a COPY operation, so the original data is not altered.
  */
 PMIX_EXPORT pmix_status_t PMIx_Value_xfer(pmix_value_t *dest,
                                           const pmix_value_t *src);
 
 /* Compare the contents of two pmix_value_t structures */
 PMIX_EXPORT pmix_value_cmp_t PMIx_Value_compare(pmix_value_t *v1,
                                                 pmix_value_t *v2);
 
 
 
 PMIX_EXPORT void PMIx_Data_array_init(pmix_data_array_t *p,
                                       pmix_data_type_t type);
 PMIX_EXPORT void PMIx_Data_array_construct(pmix_data_array_t *p,
                                            size_t num, pmix_data_type_t type);
 PMIX_EXPORT void PMIx_Data_array_destruct(pmix_data_array_t *d);
 PMIX_EXPORT pmix_data_array_t* PMIx_Data_array_create(size_t n, pmix_data_type_t type);
 PMIX_EXPORT void PMIx_Data_array_free(pmix_data_array_t *p);
 
 
 /* initialize an info struct */
 PMIX_EXPORT void PMIx_Info_construct(pmix_info_t *p);
 
 /* free memory stored inside an info struct */
 PMIX_EXPORT void PMIx_Info_destruct(pmix_info_t *p);
 
 /* create and initialize an array of info structs */
 PMIX_EXPORT pmix_info_t* PMIx_Info_create(size_t n);
 
 /* free memory stored inside an array of coord structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Info_free(pmix_info_t *p, size_t n);
 
 /* Check the given info struct to determine if it includes
  * a boolean value (includes strings for "true" and "false",
  * including abbreviations such as "t" or "f"), and if so,
  * then its value. A value type of PMIX_UNDEF is taken to imply
  * a boolean "true" as the presence of the key defaults to
  * indicating "true". */
 PMIX_EXPORT pmix_boolean_t PMIx_Info_true(const pmix_info_t *p);
 
 /* Load key/value data into a pmix_info_t struct. Note that this
  * effectively is a PMIX_LOAD_KEY operation to copy the key,
  * followed by a PMIx_Value_load to COPY the data into the
  * pmix_value_t in the provided info struct */
 PMIX_EXPORT pmix_status_t PMIx_Info_load(pmix_info_t *info,
                                          const char *key,
                                          const void *data,
                                          pmix_data_type_t type);
 
 /* Transfer data from one pmix_info_t to another - this is actually
  * executed as a COPY operation, so the original data is not altered */
 PMIX_EXPORT pmix_status_t PMIx_Info_xfer(pmix_info_t *dest,
                                          const pmix_info_t *src);
 
 /* mark the info struct as required */
 PMIX_EXPORT void PMIx_Info_required(pmix_info_t *p);
 
 /* mark the info struct as optional */
 PMIX_EXPORT void PMIx_Info_optional(pmix_info_t *p);
 
 /* check if the info struct is required */
 PMIX_EXPORT bool PMIx_Info_is_required(const pmix_info_t *p);
 
 /* check if the info struct is optional */
 PMIX_EXPORT bool PMIx_Info_is_optional(const pmix_info_t *p);
 
 /* mark the info struct as processed */
 PMIX_EXPORT void PMIx_Info_processed(pmix_info_t *p);
 
 /* check if the info struct has been processed */
 PMIX_EXPORT bool PMIx_Info_was_processed(const pmix_info_t *p);
 
 /* mark the info struct as the end of an array */
 PMIX_EXPORT void PMIx_Info_set_end(pmix_info_t *p);
 
 /* check if the info struct is the end of an array */
 PMIX_EXPORT bool PMIx_Info_is_end(const pmix_info_t *p);
 
 /* mark the info as a qualifier */
 PMIX_EXPORT void PMIx_Info_qualifier(pmix_info_t *p);
 
 /* check if the info struct is a qualifier */
 PMIX_EXPORT bool PMIx_Info_is_qualifier(const pmix_info_t *p);
 
 /* mark the info struct as persistent - do NOT release its contents */
 PMIX_EXPORT void PMIx_Info_persistent(pmix_info_t *p);
 
 /* check if the info struct is persistent */
 PMIX_EXPORT bool PMIx_Info_is_persistent(const pmix_info_t *p);
 
 
 /* initialize a coord struct */
 PMIX_EXPORT void PMIx_Coord_construct(pmix_coord_t *m);
 
 /* free memory stored inside a coord struct */
 PMIX_EXPORT void PMIx_Coord_destruct(pmix_coord_t *m);
 
 /* create and initialize an array of coord structs */
 PMIX_EXPORT pmix_coord_t* PMIx_Coord_create(size_t dims,
                                             size_t number);
 
 /* free memory stored inside an array of coord structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Coord_free(pmix_coord_t *m, size_t number);
 
 
 /* initialize a topology struct */
 PMIX_EXPORT void PMIx_Topology_construct(pmix_topology_t *t);
 
 /* free memory stored inside a topology struct */
 PMIX_EXPORT void PMIx_Topology_destruct(pmix_topology_t *topo);
 
 /* create and initialize an array of topology structs */
 PMIX_EXPORT pmix_topology_t* PMIx_Topology_create(size_t n);
 
 /* free memory stored inside an array of topology structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Topology_free(pmix_topology_t *t, size_t n);
 
 /* initialize a cpuset struct */
 PMIX_EXPORT void PMIx_Cpuset_construct(pmix_cpuset_t *cpuset);
 
 /* free memory stored inside a cpuset struct */
 PMIX_EXPORT void PMIx_Cpuset_destruct(pmix_cpuset_t *cpuset);
 
 /* create and initialize an array of cpuset structs */
 PMIX_EXPORT pmix_cpuset_t* PMIx_Cpuset_create(size_t n);
 
 /* free memory stored inside an array of cpuset structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Cpuset_free(pmix_cpuset_t *c, size_t n);
 
 /* initialize a geometry struct */
 PMIX_EXPORT void PMIx_Geometry_construct(pmix_geometry_t *g);
 
 /* free memory stored inside a cpuset struct */
 PMIX_EXPORT void PMIx_Geometry_destruct(pmix_geometry_t *g);
 
 /* create and initialize an array of cpuset structs */
 PMIX_EXPORT pmix_geometry_t* PMIx_Geometry_create(size_t n);
 
 /* free memory stored inside an array of cpuset structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Geometry_free(pmix_geometry_t *g, size_t n);
 
 /* initialize a device distance struct */
 PMIX_EXPORT void PMIx_Device_distance_construct(pmix_device_distance_t *d);
 
 /* free memory stored inside a device distance struct */
 PMIX_EXPORT void PMIx_Device_distance_destruct(pmix_device_distance_t *d);
 
 /* create and initialize an array of device distance structs */
 PMIX_EXPORT pmix_device_distance_t* PMIx_Device_distance_create(size_t n);
 
 /* free memory stored inside an array of device distance structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Device_distance_free(pmix_device_distance_t *d, size_t n);
 
 
 /* initialize a byte object struct */
 PMIX_EXPORT void PMIx_Byte_object_construct(pmix_byte_object_t *b);
 
 /* free memory stored inside a byte object struct */
 PMIX_EXPORT void PMIx_Byte_object_destruct(pmix_byte_object_t *g);
 
 /* create and initialize an array of byte object structs */
 PMIX_EXPORT pmix_byte_object_t* PMIx_Byte_object_create(size_t n);
 
 /* free memory stored inside an array of byte object structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Byte_object_free(pmix_byte_object_t *g, size_t n);
 
 /* load a byte object */
 PMIX_EXPORT void PMIx_Byte_object_load(pmix_byte_object_t *b,
                                        char *d, size_t sz);
 
 /* initialize an endpoint struct */
 PMIX_EXPORT void PMIx_Endpoint_construct(pmix_endpoint_t *e);
 
 /* free memory stored inside an endpoint struct */
 PMIX_EXPORT void PMIx_Endpoint_destruct(pmix_endpoint_t *e);
 
 /* create and initialize an array of endpoint structs */
 PMIX_EXPORT pmix_endpoint_t* PMIx_Endpoint_create(size_t n);
 
 /* free memory stored inside an array of endpoint structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Endpoint_free(pmix_endpoint_t *e, size_t n);
 
 
 /* initialize an envar struct */
 PMIX_EXPORT void PMIx_Envar_construct(pmix_envar_t *e);
 
 /* free memory stored inside an envar struct */
 PMIX_EXPORT void PMIx_Envar_destruct(pmix_envar_t *e);
 
 /* create and initialize an array of envar structs */
 PMIX_EXPORT pmix_envar_t* PMIx_Envar_create(size_t n);
 
 /* free memory stored inside an array of envar structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Envar_free(pmix_envar_t *e, size_t n);
 
 /* load an envar struct */
 PMIX_EXPORT void PMIx_Envar_load(pmix_envar_t *e,
                                  char *var,
                                  char *value,
                                  char separator);
 
 /* initialize a data buffer struct */
 PMIX_EXPORT void PMIx_Data_buffer_construct(pmix_data_buffer_t *b);
 
 /* free memory stored inside a data buffer struct */
 PMIX_EXPORT void PMIx_Data_buffer_destruct(pmix_data_buffer_t *b);
 
 /* create a data buffer struct */
 PMIX_EXPORT pmix_data_buffer_t* PMIx_Data_buffer_create(void);
 
 /* free memory stored inside a data buffer struct */
 PMIX_EXPORT void PMIx_Data_buffer_release(pmix_data_buffer_t *b);
 
 /* load a data buffer struct */
 PMIX_EXPORT void PMIx_Data_buffer_load(pmix_data_buffer_t *b,
                                        char *bytes, size_t sz);
 
 /* unload a data buffer struct */
 PMIX_EXPORT void PMIx_Data_buffer_unload(pmix_data_buffer_t *b,
                                          char **bytes, size_t *sz);
 
 
 /* initialize a proc struct */
 PMIX_EXPORT void PMIx_Proc_construct(pmix_proc_t *p);
 
 /* clear memory inside a proc struct */
 PMIX_EXPORT void PMIx_Proc_destruct(pmix_proc_t *p);
 
 /* create and initialize an array of proc structs */
 PMIX_EXPORT pmix_proc_t* PMIx_Proc_create(size_t n);
 
 /* free memory stored inside an array of proc structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Proc_free(pmix_proc_t *p, size_t n);
 
 /* load a proc struct */
 PMIX_EXPORT void PMIx_Proc_load(pmix_proc_t *p,
                                 char *nspace, pmix_rank_t rank);
 
 /* construct a multicluster nspace struct from cluster and nspace values */
 PMIX_EXPORT void PMIx_Multicluster_nspace_construct(pmix_nspace_t target,
                                                     pmix_nspace_t cluster,
                                                     pmix_nspace_t nspace);
 
 /* parse a multicluster nspace struct to separate out the cluster
  * and nspace portions */
 PMIX_EXPORT void PMIx_Multicluster_nspace_parse(pmix_nspace_t target,
                                                 pmix_nspace_t cluster,
                                                 pmix_nspace_t nspace);
 
 
 /* initialize a proc info struct */
 PMIX_EXPORT void PMIx_Proc_info_construct(pmix_proc_info_t *p);
 
 /* clear memory inside a proc info struct */
 PMIX_EXPORT void PMIx_Proc_info_destruct(pmix_proc_info_t *p);
 
 /* create and initialize an array of proc info structs */
 PMIX_EXPORT pmix_proc_info_t* PMIx_Proc_info_create(size_t n);
 
 /* free memory stored inside an array of proc info structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Proc_info_free(pmix_proc_info_t *p, size_t n);
 
 
 /* initialize a proc stats struct */
 PMIX_EXPORT void PMIx_Proc_stats_construct(pmix_proc_stats_t *p);
 
 /* clear memory inside a proc stats struct */
 PMIX_EXPORT void PMIx_Proc_stats_destruct(pmix_proc_stats_t *p);
 
 /* create and initialize an array of proc stats structs */
 PMIX_EXPORT pmix_proc_stats_t* PMIx_Proc_stats_create(size_t n);
 
 /* free memory stored inside an array of proc stats structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Proc_stats_free(pmix_proc_stats_t *p, size_t n);
 
 
 /* initialize a disk stats struct */
 PMIX_EXPORT void PMIx_Disk_stats_construct(pmix_disk_stats_t *p);
 
 /* clear memory inside a disk stats struct */
 PMIX_EXPORT void PMIx_Disk_stats_destruct(pmix_disk_stats_t *p);
 
 /* create and initialize an array of disk stats structs */
 PMIX_EXPORT pmix_disk_stats_t* PMIx_Disk_stats_create(size_t n);
 
 /* free memory stored inside an array of disk stats structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Disk_stats_free(pmix_disk_stats_t *p, size_t n);
 
 
 /* initialize a net stats struct */
 PMIX_EXPORT void PMIx_Net_stats_construct(pmix_net_stats_t *p);
 
 /* clear memory inside a net stats struct */
 PMIX_EXPORT void PMIx_Net_stats_destruct(pmix_net_stats_t *p);
 
 /* create and initialize an array of net stats structs */
 PMIX_EXPORT pmix_net_stats_t* PMIx_Net_stats_create(size_t n);
 
 /* free memory stored inside an array of net stats structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Net_stats_free(pmix_net_stats_t *p, size_t n);
 
 
 /* initialize a pdata struct */
 PMIX_EXPORT void PMIx_Pdata_construct(pmix_pdata_t *p);
 
 /* clear memory inside a pdata struct */
 PMIX_EXPORT void PMIx_Pdata_destruct(pmix_pdata_t *p);
 
 /* create and initialize an array of pdata structs */
 PMIX_EXPORT pmix_pdata_t* PMIx_Pdata_create(size_t n);
 
 /* free memory stored inside an array of pdata structs (does
  * not free the struct memory itself */
 PMIX_EXPORT void PMIx_Pdata_free(pmix_pdata_t *p, size_t n);
 
 
 PMIX_EXPORT void PMIx_App_construct(pmix_app_t *p);
 PMIX_EXPORT void PMIx_App_destruct(pmix_app_t *p);
 PMIX_EXPORT pmix_app_t* PMIx_App_create(size_t n);
 PMIX_EXPORT void PMIx_App_info_create(pmix_app_t *p, size_t n);
 PMIX_EXPORT void PMIx_App_free(pmix_app_t *p, size_t n);
 PMIX_EXPORT void PMIx_App_release(pmix_app_t *p);
 
 /* Constructing arrays of pmix_info_t for passing to an API can
  * be tedious since the pmix_info_t itself is not a "list object".
  * Since this is a very frequent operation, a set of APIs has been
  * provided that opaquely manipulates internal PMIx list structures
  * for this purpose. The user only need provide a void* pointer to
  * act as the caddy for the internal list object.
  */
 
 /* Initialize a list of pmix_info_t structures */
 PMIX_EXPORT void* PMIx_Info_list_start(void);
 
 /* Add data to a list of pmix_info_t structs. The "ptr" passed
  * here is the pointer returned by PMIx_Info_list_start.
  */
 PMIX_EXPORT pmix_status_t PMIx_Info_list_add(void *ptr,
                                              const char *key,
                                              const void *value,
                                              pmix_data_type_t type);
 
 PMIX_EXPORT pmix_status_t PMIx_Info_list_prepend(void *ptr,
                                                  const char *key,
                                                  const void *value,
                                                  pmix_data_type_t type);
 
 PMIX_EXPORT pmix_status_t PMIx_Info_list_insert(void *ptr, pmix_info_t *info);
 
 /* Transfer the data in an existing pmix_info_t struct to a list. This
  * is executed as a COPY operation, so the original data is not altered.
  * The "ptr" passed here is the pointer returned by PMIx_Info_list_start
  */
 PMIX_EXPORT pmix_status_t PMIx_Info_list_xfer(void *ptr,
                                               const pmix_info_t *info);
 
 /* Convert the constructed list of pmix_info_t structs to a pmix_data_array_t
  * of pmix_info_t. Data on the list is COPIED to the array elements.
  */
 PMIX_EXPORT pmix_status_t PMIx_Info_list_convert(void *ptr, pmix_data_array_t *par);
 
 /* Release all data on the list and destruct all internal tracking */
 PMIX_EXPORT void PMIx_Info_list_release(void *ptr);
 
 /* retrieve the next info on the list - passing a NULL
  * to the "prev" parameter will return the first pmix_info_t
  * on the list. A return of NULL indicates the end of the list
  */
 PMIX_EXPORT pmix_info_t* PMIx_Info_list_get_info(void *ptr, void *prev, void **next);
 
 #endif
 
 #if defined(c_plusplus) || defined(__cplusplus)
 }
 #endif
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team