2103 lines
96 KiB
C
2103 lines
96 KiB
C
/*
|
||
* 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
|