root/ompi/mca/coll/base/base.h

INCLUDED FROM

   1 /*
   2  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
   3  *                         University Research and Technology
   4  *                         Corporation.  All rights reserved.
   5  * Copyright (c) 2004-2005 The University of Tennessee and The University
   6  *                         of Tennessee Research Foundation.  All rights
   7  *                         reserved.
   8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
   9  *                         University of Stuttgart.  All rights reserved.
  10  * Copyright (c) 2004-2005 The Regents of the University of California.
  11  *                         All rights reserved.
  12  * $COPYRIGHT$
  13  *
  14  * Additional copyrights may follow
  15  *
  16  * $HEADER$
  17  *
  18  */
  19 
  20 /** @file
  21  * MCA coll base framework public interface functions.
  22  *
  23  * These functions are normally invoked by the back-ends of:
  24  *
  25  * - The back-ends of MPI_Init() and MPI_Finalize()
  26  * - Communicator constructors (e.g., MPI_Comm_split()) and
  27  *   destructors (e.g., MPI_Comm_free())
  28  * - The laminfo command
  29  */
  30 
  31 #ifndef MCA_COLL_BASE_H
  32 #define MCA_COLL_BASE_H
  33 
  34 #include "ompi_config.h"
  35 
  36 #include "mpi.h"
  37 #include "opal/class/opal_list.h"
  38 #include "opal/mca/base/base.h"
  39 
  40 /*
  41  * Global functions for MCA overall collective open and close
  42  */
  43 
  44 BEGIN_C_DECLS
  45 
  46 /**
  47  * Create list of available coll components.
  48  *
  49  * @param allow_multi_user_threads Will be set to true if any of the
  50  * available components will allow multiple user threads
  51  * @param have_hidden_threads Will be set to true if any of the
  52  * available components have hidden threads.
  53  *
  54  * @retval OMPI_SUCCESS If one or more coll components are available.
  55  * @retval OMPI_ERROR If no coll components are found to be available.
  56  *
  57  * This function is invoked during ompi_mpi_init() to query all
  58  * successfully opened coll components and create a list of all
  59  * available coll components.
  60  *
  61  * This function traverses the (internal global variable) framework components
  62  * list and queries each component to see if it ever might want to run during
  63  * this MPI process.  If a component does not want to run it is closed and
  64  * removed from the framework components list.
  65  */
  66 int mca_coll_base_find_available(bool enable_progress_threads,
  67                                  bool enable_mpi_threads);
  68 
  69 /**
  70  * Select an available component for a new communicator.
  71  *
  72  * @param comm Communicator that the component will be selected for.
  73  * @param preferred The component that is preferred for this
  74  * communicator (or NULL).
  75  *
  76  * @return OMPI_SUCCESS Upon success.
  77  * @return OMPI_ERROR Upon failure.
  78  *
  79  * Note that the types of the parameters have "struct" in them
  80  * (e.g., ompi_communicator_t" vs. a plain "ompi_communicator_t") to
  81  * avoid an include file loop.  All similar types (e.g., "struct
  82  * ompi_communicator_t *", "ompi_communicator_t *", and "MPI_Comm")
  83  * are all typedef'ed to be the same, so the fact that we use struct
  84  * here in the prototype is ok.
  85  *
  86  * This function is invoked when a new communicator is created and a
  87  * coll component needs to be selected for it.  It should be invoked
  88  * near the end of the communicator creation process such that
  89  * almost everything else is functional on the communicator (e.g.,
  90  * point-to-point communication).
  91  *
  92  * Note that new communicators may be created as a result of
  93  * invoking this function.  Specifically: this function is called in
  94  * the depths of communicator creation, but during the execution of
  95  * this function, new communicators may be created, and therefore
  96  * communicator creation functions may be re-entered (albiet with
  97  * different arguments).
  98  */
  99 int mca_coll_base_comm_select(struct ompi_communicator_t *comm);
 100 
 101 /**
 102  * Finalize a coll component on a specific communicator.
 103  *
 104  * @param comm The communicator that is being destroyed.
 105  *
 106  * @retval OMPI_SUCCESS Always.
 107  *
 108  * Note that the type of the parameter is only a "struct
 109  * ompi_communicator_t" (vs. a plain "ompi_communicator_t") to avoid
 110  * an include file loop.  The types "struct ompi_communicator_t *",
 111  * "ompi_communicator_t *", and "MPI_Comm" are all typedef'ed to be
 112  * the same, so the fact that we use struct here in the prototype is
 113  * ok.
 114  *
 115  * This function is invoked near the beginning of the destruction of
 116  * a communicator.  It finalizes the coll component associated with the
 117  * communicator (e.g., allowing the component to clean up and free any
 118  * resources allocated for that communicator).  Note that similar to
 119  * mca_coll_base_select(), as result of this function, other
 120  * communicators may also be destroyed.
 121  */
 122 int mca_coll_base_comm_unselect(struct ompi_communicator_t *comm);
 123 
 124 /*
 125  * Globals
 126  */
 127 OMPI_DECLSPEC extern mca_base_framework_t ompi_coll_base_framework;
 128 
 129 END_C_DECLS
 130 #endif /* MCA_BASE_COLL_H */