include/thread_mpi/collective.h

   1 /*
   2 This source code file is part of thread_mpi.
   3 Written by Sander Pronk, Erik Lindahl, and possibly others.
   4
   5 Copyright (c) 2009, Sander Pronk, Erik Lindahl.
   6 All rights reserved.
   7
   8 Redistribution and use in source and binary forms, with or without
   9 modification, are permitted provided that the following conditions are met:
  10 1) Redistributions of source code must retain the above copyright
  11    notice, this list of conditions and the following disclaimer.
  12 2) Redistributions in binary form must reproduce the above copyright
  13    notice, this list of conditions and the following disclaimer in the
  14    documentation and/or other materials provided with the distribution.
  15 3) Neither the name of the copyright holders nor the
  16    names of its contributors may be used to endorse or promote products
  17    derived from this software without specific prior written permission.
  18
  19 THIS SOFTWARE IS PROVIDED BY US ''AS IS'' AND ANY
  20 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  21 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  22 DISCLAIMED. IN NO EVENT SHALL WE BE LIABLE FOR ANY
  23 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  26 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  28 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30 If you want to redistribute modifications, please consider that
  31 scientific software is very special. Version control is crucial -
  32 bugs must be traceable. We will be happy to consider code for
  33 inclusion in the official distribution, but derived work should not
  34 be called official thread_mpi. Details are found in the README & COPYING
  35 files.
  36 */
  37
  38 #ifndef _THREAD_MPI_COLLECTIVE_H_
  39 #define _THREAD_MPI_COLLECTIVE_H_
  40
  41 /** \file
  42  *
  43  * \brief Collective functions
  44  *
  45 */
  46
  47
  48 #ifdef __cplusplus
  49 extern "C"
  50 {
  51 #endif
  52 #if 0
  53 } /* Avoids screwing up auto-indentation */
  54 #endif
  55
  56 /** Execute function once over comm
  57
  58     Executes a given function only once per collective call over comm.
  59
  60     Collective function.
  61
  62     \param[in] function     the function to call
  63     \param[in] param        the parameter to the function
  64     \param[out] was_first   set to 1 if the current thread was the one to
  65                             execute the function. unchanged if current thread
  66                             was not the one to execute the function; ignored
  67                             if NULL.
  68     \param[in] comm         The communicator.
  69     \returns MPI_SUCCESS on success.
  70 */
  71 int tMPI_Once(tMPI_Comm comm,void (*function)(void*), void *param,
  72               int *was_first);
  73
  74 /** Execute function once over comm, and wait for the function to return
  75     its value.
  76
  77     Executes a given function only once per collective call over comm.
  78
  79     Collective function.
  80
  81     \param[in] function     the function to call
  82     \param[in] param        the parameter to the function
  83     \param[out] was_first   set to 1 if the current thread was the one to
  84                             execute the function. unchanged if current thread
  85                             was not the one to execute the function; ignored
  86                             if NULL.
  87     \param[in] comm         The communicator.
  88     \returns the return value of the function
  89 */
  90 void* tMPI_Once_wait(tMPI_Comm comm,void* (*function)(void*), void *param,
  91                      int *was_first);
  92
  93 /** Allocate a shared block of memory as a collective call.
  94
  95     Collective function.
  96
  97     \param[in] comm         The communicator
  98     \param[in] size         The size in bytes to allocate
  99 */
 100 void* tMPI_Shmalloc(tMPI_Comm comm, size_t size);
 101
 102
 103
 104
 105
 106
 107 #include "thread_mpi/atomic.h"
 108
 109 typedef struct
 110 {
 111     tMPI_Atomic_t n_remaining; /* number of remaining operations */
 112     void *res;                 /* result pointer */
 113     tMPI_Comm comm;
 114 } tMPI_Reduce_req;
 115
 116 tMPI_Reduce_req *tMPI_Reduce_req_alloc(tMPI_Comm comm);
 117 #if 0
 118 /** Execute fast a asynchronious reduce over comm.
 119
 120   Reduces array input with supplied funtion. This function may return before
 121   the input array is ready to be written to again; to check for its completion,
 122   use the tMPI_Reduce_wait functions.
 123
 124   \param[in] function   The function to reduce with (takes three arguments,
 125                         a size argument, two input pointers, and an output
 126                         pointer (which may be the same as one of the input
 127                         arguments, if res==NULL).
 128   \param[in] n          A size argument to pass to the function.
 129   \param[inout] input   The array of input data.
 130   \param[out] res       A temporary results array. May be NULL, in which case
 131                         the input data in 'in' gets overwritten.
 132 */
 133 void tMPI_Reduce_async(tMPI_Reduce_req *req,
 134                        void (*function)(int, void*, void*, void *),
 135                        size_t n, void *input, void *res);
 136
 137
 138 void tMPI_Reduce_wait(tMPI_Reduce_req *req);
 139
 140 void tMPI_Reduce_wait_results(tMPI_Reduce_req *req, void *res);
 141
 142 #endif
 143
 144
 145 #ifdef __cplusplus
 146 } /* closing extern "C" */
 147 #endif
 148
 149 #endif /* _THREAD_MPI_COLLECTIVE_H_ */