root/ompi/mca/osc/osc.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   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 */

/* [<][>][^][v][top][bottom][index][help] */