1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2004-2005 The Trustees of Indiana University.
4 * All rights reserved.
5 * Copyright (c) 2004-2011 The Trustees of the University of Tennessee.
6 * All rights reserved.
7 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
8 * University of Stuttgart. All rights reserved.
9 * Copyright (c) 2004-2005 The Regents of the University of California.
10 * All rights reserved.
11 * Copyright (c) 2007-2015 Los Alamos National Security, LLC. All rights
12 * reserved.
13 * Copyright (c) 2010 Cisco Systems, Inc. All rights reserved.
14 * Copyright (c) 2015-2017 Research Organization for Information Science
15 * and Technology (RIST). All rights reserved.
16 * Copyright (c) 2016-2017 IBM Corporation. All rights reserved.
17 * $COPYRIGHT$
18 *
19 * Additional copyrights may follow
20 *
21 * $HEADER$
22 */
23 /**
24 * @file
25 *
26 * One-sided Communication interface
27 *
28 * Interface for implementing the one-sided communication chapter of
29 * the MPI-2 standard. Similar in scope to the PML for point-to-point
30 * communication from MPI-1.
31 */
32
33 #ifndef OMPI_MCA_OSC_OSC_H
34 #define OMPI_MCA_OSC_OSC_H
35
36 #include "opal_config.h"
37
38 #include <stddef.h>
39
40 #include "ompi/mca/mca.h"
41
42 BEGIN_C_DECLS
43
44
45 /* ******************************************************************** */
46
47
48 struct ompi_win_t;
49 struct opal_info_t;
50 struct ompi_communicator_t;
51 struct ompi_group_t;
52 struct ompi_datatype_t;
53 struct ompi_op_t;
54 struct ompi_request_t;
55
56 /* ******************************************************************** */
57
58
59 /**
60 * OSC component initialization
61 *
62 * Initialize the given one-sided component. This function should
63 * initialize any component-level data.
64
65 * @note The component framework is not lazily opened, so attempts
66 * should be made to minimize the amount of memory allocated during
67 * this function.
68 *
69 * @param[in] enable_progress_threads True if the component needs to
70 * support progress threads
71 * @param[in] enable_mpi_threads True if the component needs to
72 * support MPI_THREAD_MULTIPLE
73 *
74 * @retval OMPI_SUCCESS Component successfully initialized
75 * @retval OMPI_ERROR An unspecified error occurred
76 */
77 typedef int (*ompi_osc_base_component_init_fn_t)(bool enable_progress_threads,
78 bool enable_mpi_threads);
79
80
81 /**
82 * OSC component finalization
83 *
84 * Finalize the given one-sided component. This function should clean
85 * up any component-level data allocated during component_init(). It
86 * should also clean up any data created during the lifetime of the
87 * component, including any modules that are outstanding.
88 *
89 * @retval OMPI_SUCCESS Component successfully finalized
90 * @retval OMPI_ERROR An unspecified error occurred
91 */
92 typedef int (*ompi_osc_base_component_finalize_fn_t)(void);
93
94
95 /**
96 * OSC component query
97 *
98 * Query whether, given the info and comm, the component can be used
99 * for one-sided support. The ability to use the component for the
100 * window does not mean that the component will be selected. The win
101 * argument should not be modified during this call and no memory
102 * should be allocated that is associated with this window.
103 *
104 * @return The selection priority of the component
105 *
106 * @param[in] win The window handle, already filled in by MPI_WIN_CREATE()
107 * @param[in] info An info structure with hints from the user
108 * regarding the usage of the component
109 * @param[in] comm The communicator specified by the user for the
110 * basis of the group membership for the Window.
111 *
112 * @retval -1 The component can not be used for this window
113 * @retval >= 0 The priority of the component for this window
114 */
115 typedef int (*ompi_osc_base_component_query_fn_t)(struct ompi_win_t *win,
116 void **base,
117 size_t size,
118 int disp_unit,
119 struct ompi_communicator_t *comm,
120 struct opal_info_t *info,
121 int flavor);
122
123 /**
124 * OSC component select
125 *
126 * This component has been selected to provide one-sided services for
127 * the given window. The win->w_osc_module field can be updated and
128 * memory can be associated with this window. The module should be
129 * ready for use immediately upon return of this function, and the
130 * module is responsible for providing any required collective
131 * synchronization before the end of the call.
132 *
133 * @note The comm is the communicator specified from the user, so
134 * normal internal usage rules apply. In other words, if you need
135 * communication for the life of the window, you should call
136 * comm_dup() during this function.
137 *
138 * @param[in/out] win The window handle, already filled in by MPI_WIN_CREATE()
139 * @param[in] info An info structure with hints from the user
140 * regarding the usage of the component
141 * @param[in] comm The communicator specified by the user for the
142 * basis of the group membership for the Window.
143 *
144 * @retval OMPI_SUCCESS Component successfully selected
145 * @retval OMPI_ERROR An unspecified error occurred
146 */
147 typedef int (*ompi_osc_base_component_select_fn_t)(struct ompi_win_t *win,
148 void **base,
149 size_t size,
150 int disp_unit,
151 struct ompi_communicator_t *comm,
152 struct opal_info_t *info,
153 int flavor,
154 int *model);
155
156 /**
157 * OSC component interface
158 *
159 * Component interface for the OSC framework. A public instance of
160 * this structure, called mca_osc_[component_name]_component, must
161 * exist in any OSC component.
162 */
163 struct ompi_osc_base_component_2_0_0_t {
164 /** Base component description */
165 mca_base_component_t osc_version;
166 /** Base component data block */
167 mca_base_component_data_t osc_data;
168 /** Component initialization function */
169 ompi_osc_base_component_init_fn_t osc_init;
170 /** Query whether component is useable for give comm/info */
171 ompi_osc_base_component_query_fn_t osc_query;
172 /** Create module for the given window */
173 ompi_osc_base_component_select_fn_t osc_select;
174 /* Finalize the component infrastructure */
175 ompi_osc_base_component_finalize_fn_t osc_finalize;
176 };
177 typedef struct ompi_osc_base_component_2_0_0_t ompi_osc_base_component_2_0_0_t;
178 typedef ompi_osc_base_component_2_0_0_t ompi_osc_base_component_t;
179
180
181 /* ******************************************************************** */
182
183 typedef int (*ompi_osc_base_module_win_shared_query_fn_t)(struct ompi_win_t *win, int rank,
184 size_t *size, int *disp_unit, void *baseptr);
185
186 typedef int (*ompi_osc_base_module_win_attach_fn_t)(struct ompi_win_t *win, void *base, size_t size);
187 typedef int (*ompi_osc_base_module_win_detach_fn_t)(struct ompi_win_t *win, const void *base);
188
189 /**
190 * Free resources associated with win
191 *
192 * Free all resources associated with \c win. The component must
193 * provide the barrier semantics required by MPI-2 6.2.1. The caller
194 * will guarantee that no new calls into the module are made after the
195 * start of this call. It is possible that the window is locked by
196 * remote processes. win->w_flags will have OMPI_WIN_FREED set before
197 * this function is called.
198 *
199 * @param[in] win Window to free
200 *
201 * @retval OMPI_SUCCESS Component successfully selected
202 * @retval OMPI_ERROR An unspecified error occurred
203 */
204 typedef int (*ompi_osc_base_module_free_fn_t)(struct ompi_win_t *win);
205
206
207 typedef int (*ompi_osc_base_module_put_fn_t)(const void *origin_addr,
208 int origin_count,
209 struct ompi_datatype_t *origin_dt,
210 int target,
211 ptrdiff_t target_disp,
212 int target_count,
213 struct ompi_datatype_t *target_dt,
214 struct ompi_win_t *win);
215
216
217 typedef int (*ompi_osc_base_module_get_fn_t)(void *origin_addr,
218 int origin_count,
219 struct ompi_datatype_t *origin_dt,
220 int target,
221 ptrdiff_t target_disp,
222 int target_count,
223 struct ompi_datatype_t *target_dt,
224 struct ompi_win_t *win);
225
226
227 typedef int (*ompi_osc_base_module_accumulate_fn_t)(const void *origin_addr,
228 int origin_count,
229 struct ompi_datatype_t *origin_dt,
230 int target,
231 ptrdiff_t target_disp,
232 int target_count,
233 struct ompi_datatype_t *target_dt,
234 struct ompi_op_t *op,
235 struct ompi_win_t *win);
236
237 typedef int (*ompi_osc_base_module_compare_and_swap_fn_t)(const void *origin_addr,
238 const void *compare_addr,
239 void *result_addr,
240 struct ompi_datatype_t *dt,
241 int target,
242 ptrdiff_t target_disp,
243 struct ompi_win_t *win);
244
245 typedef int (*ompi_osc_base_module_fetch_and_op_fn_t)(const void *origin_addr,
246 void *result_addr,
247 struct ompi_datatype_t *dt,
248 int target,
249 ptrdiff_t target_disp,
250 struct ompi_op_t *op,
251 struct ompi_win_t *win);
252
253 typedef int (*ompi_osc_base_module_get_accumulate_fn_t)(const void *origin_addr,
254 int origin_count,
255 struct ompi_datatype_t *origin_datatype,
256 void *result_addr,
257 int result_count,
258 struct ompi_datatype_t *result_datatype,
259 int target_rank,
260 ptrdiff_t target_disp,
261 int target_count,
262 struct ompi_datatype_t *target_datatype,
263 struct ompi_op_t *op,
264 struct ompi_win_t *win);
265
266 typedef int (*ompi_osc_base_module_rput_fn_t)(const void *origin_addr,
267 int origin_count,
268 struct ompi_datatype_t *origin_dt,
269 int target,
270 ptrdiff_t target_disp,
271 int target_count,
272 struct ompi_datatype_t *target_dt,
273 struct ompi_win_t *win,
274 struct ompi_request_t **request);
275
276 typedef int (*ompi_osc_base_module_rget_fn_t)(void *origin_addr,
277 int origin_count,
278 struct ompi_datatype_t *origin_dt,
279 int target,
280 ptrdiff_t target_disp,
281 int target_count,
282 struct ompi_datatype_t *target_dt,
283 struct ompi_win_t *win,
284 struct ompi_request_t **request);
285
286
287 typedef int (*ompi_osc_base_module_raccumulate_fn_t)(const void *origin_addr,
288 int origin_count,
289 struct ompi_datatype_t *origin_dt,
290 int target,
291 ptrdiff_t target_disp,
292 int target_count,
293 struct ompi_datatype_t *target_dt,
294 struct ompi_op_t *op,
295 struct ompi_win_t *win,
296 struct ompi_request_t **request);
297
298 typedef int (*ompi_osc_base_module_rget_accumulate_fn_t)(const void *origin_addr,
299 int origin_count,
300 struct ompi_datatype_t *origin_datatype,
301 void *result_addr,
302 int result_count,
303 struct ompi_datatype_t *result_datatype,
304 int target_rank,
305 ptrdiff_t target_disp,
306 int target_count,
307 struct ompi_datatype_t *target_datatype,
308 struct ompi_op_t *op,
309 struct ompi_win_t *win,
310 struct ompi_request_t **request);
311
312 typedef int (*ompi_osc_base_module_fence_fn_t)(int assert, struct ompi_win_t *win);
313
314
315 typedef int (*ompi_osc_base_module_start_fn_t)(struct ompi_group_t *group,
316 int assert,
317 struct ompi_win_t *win);
318
319
320 typedef int (*ompi_osc_base_module_complete_fn_t)(struct ompi_win_t *win);
321
322
323 typedef int (*ompi_osc_base_module_post_fn_t)(struct ompi_group_t *group,
324 int assert,
325 struct ompi_win_t *win);
326
327
328 typedef int (*ompi_osc_base_module_wait_fn_t)(struct ompi_win_t *win);
329
330
331 typedef int (*ompi_osc_base_module_test_fn_t)(struct ompi_win_t *win,
332 int *flag);
333
334
335 typedef int (*ompi_osc_base_module_lock_fn_t)(int lock_type,
336 int target,
337 int assert,
338 struct ompi_win_t *win);
339
340 typedef int (*ompi_osc_base_module_unlock_fn_t)(int target,
341 struct ompi_win_t *win);
342
343 typedef int (*ompi_osc_base_module_lock_all_fn_t)(int assert,
344 struct ompi_win_t *win);
345
346 typedef int (*ompi_osc_base_module_unlock_all_fn_t)(struct ompi_win_t *win);
347
348 typedef int (*ompi_osc_base_module_sync_fn_t)(struct ompi_win_t *win);
349 typedef int (*ompi_osc_base_module_flush_fn_t)(int target,
350 struct ompi_win_t *win);
351 typedef int (*ompi_osc_base_module_flush_all_fn_t)(struct ompi_win_t *win);
352 typedef int (*ompi_osc_base_module_flush_local_fn_t)(int target,
353 struct ompi_win_t *win);
354 typedef int (*ompi_osc_base_module_flush_local_all_fn_t)(struct ompi_win_t *win);
355
356
357
358 /* ******************************************************************** */
359
360
361 /**
362 * OSC module instance
363 *
364 * Module interface to the OSC system. An instance of this module is
365 * attached to each window. The window contains a pointer to the base
366 * module instead of a base module itself so that the component is
367 * free to create a structure that inherits this one for use as the
368 * module structure.
369 */
370 struct ompi_osc_base_module_3_0_0_t {
371 ompi_osc_base_module_win_shared_query_fn_t osc_win_shared_query;
372
373 ompi_osc_base_module_win_attach_fn_t osc_win_attach;
374 ompi_osc_base_module_win_detach_fn_t osc_win_detach;
375 ompi_osc_base_module_free_fn_t osc_free;
376
377 ompi_osc_base_module_put_fn_t osc_put;
378 ompi_osc_base_module_get_fn_t osc_get;
379 ompi_osc_base_module_accumulate_fn_t osc_accumulate;
380 ompi_osc_base_module_compare_and_swap_fn_t osc_compare_and_swap;
381 ompi_osc_base_module_fetch_and_op_fn_t osc_fetch_and_op;
382 ompi_osc_base_module_get_accumulate_fn_t osc_get_accumulate;
383
384 ompi_osc_base_module_rput_fn_t osc_rput;
385 ompi_osc_base_module_rget_fn_t osc_rget;
386 ompi_osc_base_module_raccumulate_fn_t osc_raccumulate;
387 ompi_osc_base_module_rget_accumulate_fn_t osc_rget_accumulate;
388
389 ompi_osc_base_module_fence_fn_t osc_fence;
390
391 ompi_osc_base_module_start_fn_t osc_start;
392 ompi_osc_base_module_complete_fn_t osc_complete;
393 ompi_osc_base_module_post_fn_t osc_post;
394 ompi_osc_base_module_wait_fn_t osc_wait;
395 ompi_osc_base_module_test_fn_t osc_test;
396
397 ompi_osc_base_module_lock_fn_t osc_lock;
398 ompi_osc_base_module_unlock_fn_t osc_unlock;
399 ompi_osc_base_module_lock_all_fn_t osc_lock_all;
400 ompi_osc_base_module_unlock_all_fn_t osc_unlock_all;
401
402 ompi_osc_base_module_sync_fn_t osc_sync;
403 ompi_osc_base_module_flush_fn_t osc_flush;
404 ompi_osc_base_module_flush_all_fn_t osc_flush_all;
405 ompi_osc_base_module_flush_local_fn_t osc_flush_local;
406 ompi_osc_base_module_flush_local_all_fn_t osc_flush_local_all;
407 };
408 typedef struct ompi_osc_base_module_3_0_0_t ompi_osc_base_module_3_0_0_t;
409 typedef ompi_osc_base_module_3_0_0_t ompi_osc_base_module_t;
410
411
412 /* ******************************************************************** */
413
414
415 /** Macro for use in components that are of type osc */
416 #define OMPI_OSC_BASE_VERSION_3_0_0 \
417 OMPI_MCA_BASE_VERSION_2_1_0("osc", 3, 0, 0)
418
419
420 /* ******************************************************************** */
421
422
423 END_C_DECLS
424
425
426 #endif /* OMPI_OSC_H */