1 /*
2 * Copyright (c) 2013-2018 Intel, Inc. All rights reserved.
3 * Copyright (c) 2015 Artem Y. Polyakov <artpol84@gmail.com>.
4 * All rights reserved.
5 * Copyright (c) 2015 Research Organization for Information Science
6 * and Technology (RIST). All rights reserved.
7 * $COPYRIGHT$
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions are
11 * met:
12 *
13 * - Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 *
16 * - Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer listed
18 * in this license in the documentation and/or other materials
19 * provided with the distribution.
20 *
21 * - Neither the name of the copyright holders nor the names of its
22 * contributors may be used to endorse or promote products derived from
23 * this software without specific prior written permission.
24 *
25 * The copyright holders provide no reassurances that the source code
26 * provided does not infringe any patent, copyright, or any other
27 * intellectual property rights of third parties. The copyright holders
28 * disclaim any liability to any recipient for claims brought against
29 * recipient by any third party for infringement of that parties
30 * intellectual property rights.
31 *
32 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
33 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
34 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
35 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
36 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
37 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
38 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
39 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
40 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
41 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
42 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
43 *
44 * $HEADER$
45 *
46 * PMIx provides a "function-shipping" approach to support for
47 * implementing the server-side of the protocol. This method allows
48 * resource managers to implement the server without being burdened
49 * with PMIx internal details. Accordingly, each PMIx API is mirrored
50 * here in a function call to be provided by the server. When a
51 * request is received from the client, the corresponding server function
52 * will be called with the information.
53 *
54 * Any functions not supported by the RM can be indicated by a NULL for
55 * the function pointer. Client calls to such functions will have a
56 * "not supported" error returned.
57 */
58
59 #ifndef PMIx_TOOL_API_H
60 #define PMIx_TOOL_API_H
61
62 /* provide access to the rest of the client functions */
63 #include <pmix.h>
64
65 #if defined(c_plusplus) || defined(__cplusplus)
66 extern "C" {
67 #endif
68
69 /**** TOOL INIT/FINALIZE FUNCTIONS ****/
70
71 /* Initialize the PMIx tool, returning the process identifier assigned
72 * to this tool in the provided pmix_proc_t struct.
73 *
74 * When called the PMIx tool library will check for the required connection
75 * information of the local PMIx server and will establish the connection.
76 * If the information is not found, or the server connection fails, then
77 * an appropriate error constant will be returned.
78 *
79 * If successful, the function will return PMIX_SUCCESS and will fill the
80 * provided structure with the server-assigned namespace and rank of the tool.
81 *
82 * Note that the PMIx tool library is referenced counted, and so multiple
83 * calls to PMIx_tool_init are allowed. Thus, one way to obtain the namespace and
84 * rank of the process is to simply call PMIx_tool_init with a non-NULL parameter.
85 *
86 * The info array is used to pass user requests pertaining to the init
87 * and subsequent operations. Passing a _NULL_ value for the array pointer
88 * is supported if no directives are desired.
89 */
90 PMIX_EXPORT pmix_status_t PMIx_tool_init(pmix_proc_t *proc,
91 pmix_info_t info[], size_t ninfo);
92
93 /* Finalize the PMIx tool library, closing the connection to the local server.
94 * An error code will be returned if, for some reason, the connection
95 * cannot be closed.
96 *
97 * The info array is used to pass user requests regarding the finalize
98 * operation. */
99 PMIX_EXPORT pmix_status_t PMIx_tool_finalize(void);
100
101 /* Switch server connection. Closes the connection, if existing, to a server
102 * and establishes a connection to the specified server. The target server can
103 * be given as:
104 *
105 * - PMIX_CONNECT_TO_SYSTEM: connect solely to the system server
106 *
107 * - PMIX_CONNECT_SYSTEM_FIRST: a request to use the system server first,
108 * if existing, and then look for the server specified in a different
109 * attribute
110 *
111 * - PMIX_SERVER_URI: connect to the server at the given URI
112 *
113 * - PMIX_SERVER_NSPACE: connect to the server of a given nspace
114 *
115 * - PMIX_SERVER_PIDINFO: connect to a server embedded in the process with
116 * the given pid
117 *
118 * Passing a _NULL_ value for the info array pointer is not allowed and will
119 * result in return of an error.
120 *
121 * NOTE: PMIx does not currently support on-the-fly changes to the tool's
122 * identifier. Thus, the new server must be under the same nspace manager
123 * (e.g., host RM) as the prior server so that the original nspace remains
124 * a unique assignment. The proc parameter is included here for obsolence
125 * protection in case this constraint is someday removed. Meantime, the
126 * proc parameter will be filled with the tool's existing nspace/rank, and
127 * the caller is welcome to pass _NULL_ in that location
128 */
129 PMIX_EXPORT pmix_status_t PMIx_tool_connect_to_server(pmix_proc_t *proc,
130 pmix_info_t info[], size_t ninfo);
131
132 #if defined(c_plusplus) || defined(__cplusplus)
133 }
134 #endif
135
136 #endif