src/gromacs/legacyheaders/thread_mpi/tmpi.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 _TMPI_H_
  39 #define _TMPI_H_
  40
  41 /** \file
  42  *
  43  * \brief Partial implementation of MPI using only threads.
  44  *
  45  * See the MPI specification at
  46  * http://www.mpi-forum.org/docs/docs.html
  47  * for an explanation of what these functions do.
  48  *
  49  * Because this is a thread-based library, be very careful with global
  50  * variables and static variables in functions: they will be shared across
  51  * all threads and lead to conflicts if not properly mutex-ed or barrier-ed
  52  * out.
  53  *
  54  * \sa http://www.mpi-forum.org/docs/docs.html for MPI documentation.
  55 */
  56
  57
  58 #ifdef __cplusplus
  59 extern "C"
  60 {
  61 #endif
  62 #if 0
  63 } /* Avoids screwing up auto-indentation */
  64 #endif
  65
  66 /** tMPI definition.
  67
  68 Use this to check for thread_mpi with the preprocessor. */
  69 #define TMPI
  70
  71
  72
  73 /** tMPI Communicator
  74
  75   Holds the group of processes to communicate
  76    with, and defines the scope for global operations such as broadcast. */
  77 typedef struct tmpi_comm_ *tMPI_Comm;
  78
  79 /** tMPI Group
  80
  81   The group structure. Contains a list of threads. */
  82 typedef struct tmpi_group_ *tMPI_Group;
  83
  84 /** tMPI Request
  85
  86   Request structure for holding data about non-blocking transfers. */
  87 typedef struct tmpi_req_ *tMPI_Request;
  88
  89
  90 /** tMPI datatype
  91
  92   tMPI data type structure. Holds info about datatypes. */
  93 typedef struct tmpi_datatype_ *tMPI_Datatype;
  94
  95
  96 /*! \name tMPI Data types
  97     These are MPI data types as specified by the MPI standard.
  98     Note that not all are available.  */
  99 /*! \{ */
 100 extern const tMPI_Datatype TMPI_CHAR;               /**< char */
 101 extern const tMPI_Datatype TMPI_SHORT;              /**< short */
 102 extern const tMPI_Datatype TMPI_INT;                /**< int */
 103 extern const tMPI_Datatype TMPI_LONG;               /**< long */
 104 #ifdef SIZEOF_LONG_LONG_INT
 105 extern const tMPI_Datatype TMPI_LONG_LONG;          /**< long long */
 106 extern const tMPI_Datatype TMPI_LONG_LONG_INT;      /**< long long int */
 107 #endif
 108 extern const tMPI_Datatype TMPI_SIGNED_CHAR;        /**< signed char */
 109 extern const tMPI_Datatype TMPI_UNSIGNED_CHAR;      /**< unsigned char */
 110 extern const tMPI_Datatype TMPI_UNSIGNED_SHORT;     /**< unsigned short */
 111 extern const tMPI_Datatype TMPI_UNSIGNED;           /**< unsigned int */
 112 extern const tMPI_Datatype TMPI_UNSIGNED_LONG;      /**< unsigned long */
 113 #ifdef SIZEOF_LONG_LONG_INT
 114 extern const tMPI_Datatype TMPI_UNSIGNED_LONG_LONG; /**< unsigned long long */
 115 #endif
 116 extern const tMPI_Datatype TMPI_FLOAT;              /**< float */
 117 extern const tMPI_Datatype TMPI_DOUBLE;             /**< double */
 118 extern const tMPI_Datatype TMPI_LONG_DOUBLE;        /**< long double */
 119 /*extern tMPI_Datatype tMPI_UNSIGNED_WCHAR */
 120 extern const tMPI_Datatype TMPI_BYTE;               /**< byte (for binary
 121                                                                xmissions) */
 122 extern const tMPI_Datatype TMPI_POINTER;            /**< pointer (thread_mpi
 123                                                                   specific) */
 124
 125 /*! \} */
 126
 127
 128 /** Error codes */
 129 enum
 130 {
 131     TMPI_SUCCESS=0,                 /*!< No error */
 132     TMPI_ERR_MALLOC,                /*!< Out of memory */
 133     TMPI_ERR_INIT,                  /*!< Initialization error */
 134     TMPI_ERR_FINALIZE,              /*!< Finalize error */
 135     TMPI_ERR_GROUP,                 /*!< Group error */
 136     TMPI_ERR_COMM,                  /*!< Comm error */
 137     TMPI_ERR_STATUS,                /*!< Status error */
 138     TMPI_ERR_GROUP_RANK,            /*!< Group rank error */
 139     TMPI_ERR_DIMS,
 140     TMPI_ERR_COORDS,
 141     TMPI_ERR_CART_CREATE_NPROCS,
 142     TMPI_ERR_XFER_COUNTERPART,
 143     TMPI_ERR_XFER_BUFSIZE,
 144     TMPI_ERR_XFER_BUF_OVERLAP,
 145     TMPI_ERR_SEND_DEST,
 146     TMPI_ERR_RECV_SRC,
 147     TMPI_ERR_BUF,
 148     TMPI_ERR_MULTI_MISMATCH,
 149     TMPI_ERR_OP_FN,
 150     TMPI_ERR_ENVELOPES,
 151     TMPI_ERR_REQUESTS,
 152     TMPI_ERR_IN_STATUS,
 153     TMPI_FAILURE,
 154     TMPI_ERR_UNKNOWN,
 155     N_TMPI_ERR  /* this must be the last one */
 156 };
 157
 158 /** Maximum length of error string for tMPI_Error_string() */
 159 #define TMPI_MAX_ERROR_STRING            256
 160
 161 /** default code for undefined value,
 162
 163     For example for undefined color in tMPI_Split(). */
 164 #define TMPI_UNDEFINED -1
 165
 166 /** error handler function */
 167 typedef void (*tMPI_Errhandler_fn)(tMPI_Comm*, int*);
 168 /** error handler object */
 169 typedef struct tmpi_errhandler_ *tMPI_Errhandler;
 170
 171 /** pre-defined error handler that abort()s on every error */
 172 extern tMPI_Errhandler TMPI_ERRORS_ARE_FATAL;
 173 /** pre-defined error handler that tries to continue on every error */
 174 extern tMPI_Errhandler TMPI_ERRORS_RETURN;
 175
 176 /*! \name tMPI_Comm_compare() return codes */
 177 /*! \{ */
 178 /** Identical comms*/
 179 #define TMPI_IDENT 0
 180 /** Comms with the same members in the same order*/
 181 #define TMPI_CONGRUENT 1
 182 /** Comms with the same members in the different order*/
 183 #define TMPI_SIMILAR 2
 184 /** Comms with the different  members */
 185 #define TMPI_UNEQUAL 3
 186 /*! \} */
 187
 188
 189 /** Source number wildcard so tMPI_Recv(), etc. can receive from
 190            any source. */
 191 #define TMPI_ANY_SOURCE -1
 192 /** Tag number wildcard so tMPI_Recv(), etc. can receive messages with
 193            any tag. */
 194 #define TMPI_ANY_TAG -1
 195
 196 /** Return code for Cartesian topology with tMPI_Topo_test().  */
 197 #define TMPI_CART 1
 198 /** Return code for graph topology with tMPI_Topo_test().  */
 199 #define TMPI_GRAPH 2
 200
 201
 202 /** Pre-initialized communicator with all available threads. */
 203 extern tMPI_Comm TMPI_COMM_WORLD;
 204
 205
 206 /** A pre-defined NULL communicator to compare against, to check comm
 207            validity */
 208 #define TMPI_COMM_NULL NULL
 209 /** A pre-defined NULL group to compare against, to check group
 210            validity */
 211 #define TMPI_GROUP_NULL NULL
 212
 213 /** the empty group */
 214 extern tMPI_Group TMPI_GROUP_EMPTY;
 215
 216
 217 /** The maximum processor name returned using tMPI_Get_processor_name(). */
 218 #define TMPI_MAX_PROCESSOR_NAME 128
 219
 220
 221 /** Used as NULL status for tMPI_Recv(), etc. */
 222 #define TMPI_STATUS_IGNORE NULL
 223 /** Used as NULL status list for tMPI_Waitall(), etc. */
 224 #define TMPI_STATUSES_IGNORE NULL
 225
 226 /** tMPI Status.
 227
 228   Holds status info (tag, sender, amount of data transmitted) for receives.
 229   The status object is user-maintained. */
 230 typedef struct tmpi_status_
 231 {
 232     int TMPI_SOURCE;        /**< Message source rank. */
 233     int TMPI_TAG;           /**< Message source tag. */
 234     int TMPI_ERROR;         /**< Message error. */
 235     size_t transferred;     /**< Number of transferred bytes */
 236     int cancelled;          /**< Whether the transmission was canceled */
 237 } tMPI_Status;
 238 /*typedef struct tmpi_status_ tMPI_Status;*/
 239
 240 /** NULL request */
 241 #define TMPI_REQUEST_NULL NULL
 242
 243 /** collective communication special to signify that the send
 244            buffer is to function as receive buffer.
 245
 246            Used, for example in tMPI_Reduce. */
 247 #define TMPI_IN_PLACE NULL
 248
 249
 250 /** tMPI_Reduce operators.
 251
 252     These all work (except obviously bad combinations like bitwise
 253     and/or/xor on floats, etc): */
 254 typedef enum
 255 {
 256     TMPI_MAX,       /**< calculate maximum value */
 257     TMPI_MIN,       /**< calculate minimum value */
 258     TMPI_SUM,       /**< calculate sum */
 259     TMPI_PROD,      /**< calculate product */
 260     TMPI_LAND,      /**< calculate logical and */
 261     TMPI_BAND,      /**< calculate binary and */
 262     TMPI_LOR,       /**< calculate logical or */
 263     TMPI_BOR,       /**< calculate binary or */
 264     TMPI_LXOR,      /**< calculate logical xor */
 265     TMPI_BXOR       /**< calculate binary xor */
 266 } tMPI_Op;
 267
 268 #ifndef DOXYGEN
 269 /* function to obtain tMPI_COMM_SELF */
 270 tMPI_Comm tMPI_Get_comm_self(void);
 271 #endif
 272 /** The thread-specific comm containing only the thread itself.
 273
 274     \hideinitializer
 275     \return the self comm object associated with the thread. */
 276 #define TMPI_COMM_SELF (tMPI_Get_comm_self())
 277
 278
 279
 280
 281
 282
 283
 284 /* functions: */
 285
 286 /*! \name Initialization and exit functions
 287     \{ */
 288 /** Traditional MPI initializer; spawns threads that start at
 289     the given function.
 290
 291     Seeks the argument '-nt n', where n is the number of
 292     threads that will be created. If n==0, the number of threads will
 293     be the recommended number of threads for this platform as obtained
 294     from tMPI_Get_recommended_ntreads().
 295
 296     The new threads then run the function start_function, with the original
 297     argc and argv. This function could be main(), or any other function;
 298     calling this function again - whether from the started threads or from
 299     the main thread - has no effect.
 300
 301     \param[in] argc     argc of original main() invocation, or NULL
 302     \param[in] argv     argv of original main() invocation, or NULL.
 303     \param[in] start_function Starting function of type
 304                         int start_function(int argc, char *argv[]);
 305
 306     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 307 int tMPI_Init(int *argc, char ***argv, int (*start_function)(int, char**));
 308
 309
 310 /** Alternate thread MPI intializer and thread spawner.
 311
 312     Creates N threads (including main thread)
 313     that run the function start_function, which takes a void* argument,
 314     given by arg. The function start_function also gets called by the main
 315     thread. When the function start_function returns it, will behave
 316     as if tMPI_Finalize is called, and if it's a sub-thread it will
 317     stop running.
 318
 319     If N==0, the number of threads will be the recommended number of
 320     threads for this platform as obtained from tMPI_Get_recommended_ntreads().
 321
 322     \param[in]  main_thread_returns   whether the control in the main thread
 323                                       should return immediately (if true), or
 324                                       the start_function() should be called
 325                                       from the main thread, too (if false).
 326     \param[in] N                      The number of threads to start (or 0 to
 327                                       automatically determine this).
 328     \param[in] start_function         The function to start threads at
 329                                       (including main thread if
 330                                       main_thread_returns).
 331     \param[in] arg                    An optional argument for start_function().
 332
 333     \return  TMPI_FAILURE on failure, TMPI_SUCCESS on succes (after all
 334              threads have finished if main_thread_returns=true).  */
 335 int tMPI_Init_fn(int main_thread_returns, int N,
 336                  void (*start_function)(void*), void *arg);
 337
 338 /** get the number of threads from the command line
 339
 340     can be called before tMPI_Init()
 341
 342     \param[in]  argc                    argc from main()
 343     \param[in]  argv                    argv from main()
 344     \param[in]  optname                 name of the argument specifying the
 345                                         number of threads to run. If this is
 346                                         NULL, this function will read the first
 347                                         argument and interpret it as the number
 348                                         of threads.
 349     \param[out] nthreads                the number of threads
 350
 351     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 352 int tMPI_Get_N(int *argc, char ***argv, const char *optname, int *nthreads);
 353
 354
 355
 356 /** Waits for all other threads to finish and cleans up
 357
 358     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 359 int tMPI_Finalize(void);
 360
 361
 362 /** Just kills all threads.
 363
 364     Not really neccesary because exit() would do that for us anyway.
 365
 366     \param[in] comm         Comm to kill threads for
 367     \param[in] errorcode    Error code to exit with
 368
 369     \return Never returns. */
 370 int tMPI_Abort(tMPI_Comm comm, int errorcode);
 371
 372 /** whether tMPI_Init, but not yet tMPI_Finalize, has been run
 373
 374     \param[out] flag     Set to TRUE if tMPI_Init() has been called,
 375                          FALSE if not.
 376
 377     \return     always returns TMPI_SUCCESS. */
 378 int tMPI_Initialized(int *flag);
 379
 380 /** Determine whether tMPI_Finalize has been run.
 381
 382     \param[out] flag        Set to TRUE if tMPI_Finalize() has been
 383                             called, FALSE if not.
 384
 385     \return     always returns TMPI_SUCCESS.  */
 386 int tMPI_Finalized(int *flag);
 387 /** \} */
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397 /*! \name Error handling functions
 398     \{ */
 399 /** Create an error handler object from a function.
 400
 401     \param[in]  function        The function to make an error handler of.
 402     \param[out] errhandler      The error handler.
 403
 404     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 405 int tMPI_Create_errhandler(tMPI_Errhandler_fn *function,
 406                            tMPI_Errhandler *errhandler);
 407
 408
 409 /** Free the error handler object.
 410
 411     \param[in] errhandler       The error handler.
 412     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 413 int tMPI_Errhandler_free(tMPI_Errhandler *errhandler);
 414
 415 /** Set the error handler.
 416
 417     \param[in] comm         the communicator to set the error handler for.
 418     \param[in] errhandler   the error handler.
 419
 420     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 421
 422 int tMPI_Comm_set_errhandler(tMPI_Comm comm, tMPI_Errhandler errhandler);
 423 /** get the error handler.
 424
 425     Gets the error handler associated with a comm
 426
 427     \param[in]  comm         the communicator to get the error handler for.
 428     \param[out] errhandler   the error handler.
 429
 430     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 431
 432 int tMPI_Comm_get_errhandler(tMPI_Comm comm, tMPI_Errhandler *errhandler);
 433
 434 /** get the error string associated with an error code.
 435
 436     The length of the error string will never exceed TMPI_MAX_ERROR_STRING.
 437
 438     \param[in]  errorcode   The error code.
 439     \param[out] string      The pre-allocated char pointer to output to.
 440     \param[out] resultlen   The length of the error string. Will
 441                             never be longer than TMPI_MAX_ERROR_STRING.
 442
 443     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 444 int tMPI_Error_string(int errorcode, char *string, size_t *resultlen);
 445 /** \} */
 446
 447
 448
 449
 450
 451
 452
 453
 454 /*! \name Environment query functions
 455     \{ */
 456 /** returns string with thread number.
 457
 458     \param[out] name        Pre-allocated string to output name to (will not
 459                             be longer than TMPI_MAX_PROCESSOR_NAME).
 460     \param[out] resultlen   The length of the output. Note that this is an
 461                             int instead of a size_t because the MPI standard
 462                             for some reason defines all sizes as int
 463
 464     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 465 int tMPI_Get_processor_name(char *name, int *resultlen);
 466
 467 /** get a time value as a double, in seconds.
 468
 469     \return time value.
 470     */
 471 double tMPI_Wtime(void);
 472 /** get the resolution of tMPI_Wtime as a double, in seconds
 473
 474     \return time resolution. */
 475 double tMPI_Wtick(void);
 476
 477 #ifndef DOXYGEN
 478 #define tMPI_This_threadnr() (int)(tMPI_Get_current() - threads)
 479 #else
 480 /** Get the thread number of this thread.
 481     Mostly for debugging.
 482
 483     \return the global thread number. */
 484 int tMPI_This_Threadnr(void);
 485 #endif
 486
 487 /** \} */
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497 /*! \name tMPI_Group functions
 498     \{ */
 499 /** Get the size (number of members) of a group.
 500
 501     \param[in]  group       The group.
 502     \param[out] size        Size.
 503     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 504 int tMPI_Group_size(tMPI_Group group, int *size);
 505
 506 /** Get the rank of a thread in a group
 507
 508     \param[in]  group       The group.
 509     \param[out] rank        Variable for the rank, or TMPI_UNDEFINED
 510                             if not in group.
 511     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 512 int tMPI_Group_rank(tMPI_Group group, int *rank);
 513
 514 /** Create a new group as a the collection of threads with given ranks.
 515
 516     \param[in] group        The group from which the ranks are taken.
 517     \param[in] n            The number of new group members.
 518     \param[in] ranks        The ranks of the threads to add to the new group.
 519     \param[out] newgroup    The new group.
 520
 521     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 522 int tMPI_Group_incl(tMPI_Group group, int n, int *ranks, tMPI_Group *newgroup);
 523
 524 /** Get a pointer to the group in the comm.
 525
 526     \param[in] comm         The comm from which to take the group.
 527     \param[out] group       The comm's group.
 528
 529     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 530 int tMPI_Comm_group(tMPI_Comm comm, tMPI_Group *group);
 531
 532 /** De-allocate a group
 533
 534     \param[in] group        The group to de-allocate.
 535     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 536 int tMPI_Group_free(tMPI_Group *group);
 537 /*! \} */
 538
 539
 540
 541
 542
 543
 544
 545 /*! \name tMPI_Comm functions
 546     \{ */
 547 /** Get the comm size (nr. of threads).
 548
 549     \param[in] comm         The comm to query.
 550     \param[out] size        The comm size.
 551     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 552 int tMPI_Comm_size(tMPI_Comm comm, int *size);
 553
 554 /** get the rank in comm of the current process
 555
 556     \param[in]  comm        The comm to query.
 557     \param[out] rank        Thread rank in comm.
 558     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 559 int tMPI_Comm_rank(tMPI_Comm comm, int *rank);
 560
 561 /** Compare two comms. Returns TMPI_IDENT if the two comms point to
 562     the same underlying comm structure, TMPI_CONGRUENT if all
 563     members appear in the both comms in the same order, TMPI_SIMILAR
 564     if both comms have the smae members but not in the same order, or
 565     TMPI_UNEQUAL if the comms have different members.
 566
 567     \param[in]  comm1        The first comm to compare.
 568     \param[in]  comm2        The second comm to compare.
 569     \param[out] result       The output result, one of the values
 570                              described above.
 571     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 572 int tMPI_Comm_compare(tMPI_Comm comm1, tMPI_Comm comm2, int *result);
 573
 574
 575 /** De-allocate a comm
 576
 577     Collective function.
 578
 579     \param[in] comm         The comm to free.
 580     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 581 int tMPI_Comm_free(tMPI_Comm *comm);
 582
 583 /** Create a comm based on group membership.
 584
 585     Collective function that creates a new comm containing only proceses
 586     that are members of the given group.
 587
 588     \param[in]  comm        The originating comm.
 589     \param[in]  group       The group of threads to create a comm from.
 590     \param[out] newcomm     The new comm.
 591
 592     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 593 int tMPI_Comm_create(tMPI_Comm comm, tMPI_Group group, tMPI_Comm *newcomm);
 594
 595 /** Split up a group into same-colored sub-groups ordered by key.
 596
 597     This is the main comm creation function: it's a collective call that takes
 598     a color and a key from each process, and arranges all threads that
 599     call tMPI_Split() withe the same color together into a comm.
 600
 601     The rank in the new group will be based on the value given in key.
 602
 603     Passing TMPI_UNDEFINED as a color will result in the thread not being
 604     part of any group, and getting TMPI_COMM_NULL back in newcomm.
 605
 606     \param[in]  comm        The originating comm.
 607     \param[in]  color       This thread's color (determines which comm it will
 608                             be in). Giving TMPI_UNDEFINED will result in
 609                             this thread not being in any group.
 610     \param[in]  key         This thread's key (determines rank).
 611     \param[out] newcomm     The new comm.
 612     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 613 int tMPI_Comm_split(tMPI_Comm comm, int color, int key, tMPI_Comm *newcomm);
 614
 615 /** Make a duplicate of a comm.
 616
 617     Collective function.
 618
 619     \param[in] comm         The originating comm.
 620     \param[in] newcomm      The new comm.
 621     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 622 int tMPI_Comm_dup(tMPI_Comm comm, tMPI_Comm *newcomm);
 623 /*! \} */
 624
 625
 626
 627
 628
 629
 630
 631
 632 /*! \name Topology functions
 633     \{ */
 634 /* topology functions */
 635 /** Check what type of topology the comm has.
 636
 637     \param[in] comm         The comm to query
 638     \param[out] status      The type of topology.
 639
 640     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 641 int tMPI_Topo_test(tMPI_Comm comm, int *status);
 642
 643 /** Get the dimensionality of a comm with a topology.
 644
 645     \param[in] comm         The comm to query.
 646     \param[out] ndims       The number of dimensions.
 647
 648     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 649
 650 int tMPI_Cartdim_get(tMPI_Comm comm, int *ndims);
 651 /** Get the size and pbc a of a comm with a Cartesian topology has.
 652
 653     \param[in]  comm        The comm to query.
 654     \param[in]  maxdims     The maximum number of dimensions in the periods
 655                             and coords parameter.
 656     \param[out] dims        The number of dimensions.
 657     \param[out] periods     The periodicity in each dimension.
 658     \param[out] coords      The number of coordinates in each dimension.
 659
 660     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 661
 662 int tMPI_Cart_get(tMPI_Comm comm, int maxdims, int *dims, int *periods,
 663                   int *coords);
 664
 665
 666 /** Get rank that a specific set of process coordinates has in
 667     a Cartesian topology.
 668
 669     \param[in]  comm        The comm to query.
 670     \param[in]  coords      The coordinates in each dimension.
 671     \param[out] rank        The rank associated with the coordinates.
 672
 673     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 674 int tMPI_Cart_rank(tMPI_Comm comm, int *coords, int *rank);
 675
 676 /** Get coordinates of a process rank in a Cartesian topology.
 677
 678     \param[in]  comm        The comm to query.
 679     \param[in]  rank        The rank associated with the coordinates.
 680     \param[in]  maxdims     The maximum number of dimensions in the coords
 681                             parameter.
 682     \param[out] coords      The coordinates in each dimension.
 683
 684     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 685 int tMPI_Cart_coords(tMPI_Comm comm, int rank, int maxdims, int *coords);
 686
 687 /** Get optimal rank this process would have in a Cartesian topology.
 688
 689     \param[in]  comm        The comm to query.
 690     \param[in]  ndims       The number of dimensions.
 691     \param[in]  dims        The size in each dimension.
 692     \param[in]  periods     The periodicity in each dimension.
 693
 694     \param[out] newrank     The rank the thread would have given the topology.
 695
 696     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 697 int tMPI_Cart_map(tMPI_Comm comm, int ndims, int *dims, int *periods,
 698                   int *newrank);
 699
 700 /** Create a comm with a Cartesian topology.
 701
 702     \param[in]  comm_old    The originating comm.
 703     \param[in]  ndims       The number of dimensions.
 704     \param[in]  dims        The size in each dimension.
 705     \param[in]  periods     The periodicity in each dimension.
 706     \param[in]  reorder     Whether to allow reordering of the threads
 707                             according to tMPI_Cart_map().
 708     \param[out] comm_cart   The new comm with Cartesian topology.
 709
 710     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 711 int tMPI_Cart_create(tMPI_Comm comm_old, int ndims, int *dims, int *periods,
 712                      int reorder, tMPI_Comm *comm_cart);
 713
 714 /** Create a comms that are sub-spaces of the Cartesian topology communicator.
 715     Works like a MPI_Comm_split() for the Cartesian dimensions specified
 716     as false in remain_dims.
 717
 718     \param[in]  comm        The originating comm with Cartesian topology.
 719     \param[in]  remain_dims An Boolean array that decides whether a specific
 720                             dimensionality should remain in newcomm (if true),
 721                             or should be split up (if false).
 722     \param[out] newcomm     The new split communicator
 723
 724     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 725 int tMPI_Cart_sub(tMPI_Comm comm, int *remain_dims, tMPI_Comm *newcomm);
 726
 727 /*! \} */
 728
 729
 730
 731
 732
 733
 734
 735
 736 /*! \name Data type manipulation functions
 737     \{ */
 738 /** Create a contiguous data type (the only type possible right now).
 739
 740     Creates a datatype that is a vector of oldtype.
 741
 742     \param[in]  count       The number of oldtype types in the new type.
 743     \param[in]  oldtype     The old data type.
 744     \param[out] newtype     The new data type (still needs to be committed).
 745     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 746 int tMPI_Type_contiguous(int count, tMPI_Datatype oldtype,
 747                         tMPI_Datatype *newtype);
 748
 749
 750 /** Make a data type ready for use.
 751
 752     \param[in,out] datatype  The new datatype.
 753     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 754 int tMPI_Type_commit(tMPI_Datatype *datatype);
 755 /*! \} */
 756
 757
 758
 759
 760
 761
 762
 763
 764 /*! \name Point-to-point communication functions
 765     \{ */
 766
 767 /* blocking transfers. The actual transfer (copy) is done on the receiving end
 768     (so that the receiver's cache already contains the data that it presumably
 769      will use soon).  */
 770 /** Send message; blocks until buf is reusable.
 771
 772     \param[in]  buf         The buffer with data to send.
 773     \param[in]  count       The number of items to send.
 774     \param[in]  datatype    The data type of the items in buf.
 775     \param[in]  dest        The rank of the destination thread.
 776     \param[in]  tag         The message tag.
 777     \param[in]  comm        The shared communicator.
 778     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 779 int tMPI_Send(void* buf, int count, tMPI_Datatype datatype, int dest,
 780              int tag, tMPI_Comm comm);
 781
 782 /** Receive message; blocks until buf is filled.
 783
 784     \param[out] buf         The buffer for data to receive.
 785     \param[in]  count       The maximum number of items to receive.
 786     \param[in]  datatype    The data type of the items in buf.
 787     \param[in]  source      The rank of the source thread (or TMPI_ANY_SOURCE).
 788     \param[in]  tag         The message tag (or TMPI_ANY_TAG).
 789     \param[in]  comm        The shared communicator.
 790     \param[out] status      The message status.
 791     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 792 int tMPI_Recv(void* buf, int count, tMPI_Datatype datatype, int source,
 793              int tag, tMPI_Comm comm, tMPI_Status *status);
 794
 795 /** Send & receive message at the same time.
 796
 797     Blocks until recvbuf is filled, and sendbuf is ready for reuse.
 798
 799     \param[in]  sendbuf     The buffer with data to send.
 800     \param[in]  sendcount   The number of items to send.
 801     \param[in]  sendtype    The data type of the items in send buf.
 802     \param[in]  dest        The rank of the destination thread.
 803     \param[in]  sendtag     The send message tag.
 804     \param[out] recvbuf     The buffer for data to receive.
 805     \param[in]  recvcount   The maximum number of items to receive.
 806     \param[in]  recvtype    The data type of the items in recvbuf.
 807     \param[in]  source      The rank of the source thread (or TMPI_ANY_SOURCE).
 808     \param[in]  recvtag     The recveive message tag (or TMPI_ANY_TAG).
 809     \param[in]  comm        The shared communicator.
 810     \param[out] status      The received message status.
 811     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 812 int tMPI_Sendrecv(void *sendbuf, int sendcount, tMPI_Datatype sendtype,
 813                  int dest, int sendtag, void *recvbuf, int recvcount,
 814                  tMPI_Datatype recvtype, int source, int recvtag,
 815                  tMPI_Comm comm, tMPI_Status *status);
 816
 817 /* async send/recv. The actual transfer is done on the receiving
 818     end, during tMPI_Wait, tMPI_Waitall or tMPI_Test. For tMPI_Waitall,
 819     the incoming messages are processed in the order they come in.  */
 820
 821 /** Initiate sending a message, non-blocking.
 822
 823     This makes the buffer available to be received. The contents of buf
 824     should not be touched before the transmission is finished with
 825     tMPI_Wait(), tMPI_Test() or tMPI_Waitall().
 826
 827
 828     \param[in]  buf         The buffer with data to send.
 829     \param[in]  count       The number of items to send.
 830     \param[in]  datatype    The data type of the items in buf.
 831     \param[in]  dest        The rank of the destination thread.
 832     \param[in]  tag         The message tag.
 833     \param[in]  comm        The shared communicator.
 834     \param[out] request     The request object that can be used in tMPI_Wait(),
 835                             tMPI_Test, etc.
 836     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 837 int tMPI_Isend(void* buf, int count, tMPI_Datatype datatype, int dest,
 838               int tag, tMPI_Comm comm, tMPI_Request *request);
 839
 840 /** Initiate receiving a message.
 841
 842     This makes the buffer available to be filled with data. The contents of
 843     buf should not be relied on before the transmission is finished with
 844     tMPI_Wait(), tMPI_Test() or tMPI_Waitall().
 845
 846     \param[out] buf         The buffer for data to receive.
 847     \param[in]  count       The maximum number of items to receive.
 848     \param[in]  datatype    The data type of the items in buf.
 849     \param[in]  source      The rank of the source thread (or TMPI_ANY_SOURCE).
 850     \param[in]  tag         The message tag (or TMPI_ANY_TAG).
 851     \param[in]  comm        The shared communicator.
 852     \param[out] request     The request object that can be used in tMPI_Wait(),
 853                             tMPI_Test, etc.
 854     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 855 int tMPI_Irecv(void* buf, int count, tMPI_Datatype datatype, int source,
 856               int tag, tMPI_Comm comm, tMPI_Request *request);
 857
 858
 859
 860
 861 /** Test whether a message is transferred.
 862
 863     \param[in,out]  request The request obtained wit tMPI_Isend()/tMPI_Irecv().
 864     \param[out]     flag    A flag set to TRUE(1) if the request is finished,
 865                             FALSE(0) otherwise.
 866     \param[out]     status  Message status (can be set to TMPI_STATUS_IGNORE).
 867
 868     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 869 int tMPI_Test(tMPI_Request *request, int *flag, tMPI_Status *status);
 870
 871 /** Wait until a message is transferred.
 872
 873     \param[in,out]  request The request obtained wit tMPI_Isend()/tMPI_Irecv().
 874     \param[out]     status  Message status.
 875
 876     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 877 int tMPI_Wait(tMPI_Request *request, tMPI_Status *status);
 878
 879
 880
 881
 882 /** Wait until several messages are transferred.
 883
 884     \param[in]      count               The number of requests
 885     \param[in,out]  array_of_requests   List of count requests obtained with
 886                                         tMPI_Isend()/tMPI_Irecv().
 887     \param[out]     array_of_statuses   List of count message statuses (can
 888                                         be set to TMPI_STATUSES_IGNORE).
 889
 890     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 891 int tMPI_Waitall(int count, tMPI_Request *array_of_requests,
 892                 tMPI_Status *array_of_statuses);
 893
 894 /** Test whether several messages are transferred.
 895
 896     \param[in]      count               The number of requests
 897     \param[in,out]  array_of_requests   List of count requests obtained with
 898                                         tMPI_Isend()/tMPI_Irecv().
 899     \param[out]     flag                Whether all requests have completed.
 900     \param[out]     array_of_statuses   List of count message statuses (can
 901                                         be set to TMPI_STATUSES_IGNORE).
 902
 903     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 904 int tMPI_Testall(int count, tMPI_Request *array_of_requests, int *flag,
 905                 tMPI_Status *array_of_statuses);
 906
 907 /** Wait until one of several messages is transferred.
 908
 909     \param[in]      count               The number of requests
 910     \param[in,out]  array_of_requests   List of count requests obtained with
 911                                         tMPI_Isend()/tMPI_Irecv().
 912     \param[out]     index               Index of the request that has
 913                                         completed.
 914     \param[out]     status              Pointer to tMPI_Status object
 915                                         associated with completed request.
 916
 917     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 918 int tMPI_Waitany(int count, tMPI_Request *array_of_requests,
 919                  int *index, tMPI_Status *status);
 920
 921 /** Test whether one of several messages is transferred.
 922
 923     \param[in]      count               The number of requests
 924     \param[in,out]  array_of_requests   List of count requests obtained with
 925                                         tMPI_Isend()/tMPI_Irecv().
 926     \param[out]     index               Index of the request that has
 927                                         completed.
 928     \param[out]     flag                Whether any request has completed.
 929     \param[out]     status              Pointer to tMPI_Status object
 930                                         associated with completed request.
 931
 932     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 933 int tMPI_Testany(int count, tMPI_Request *array_of_requests,
 934                  int *index, int *flag, tMPI_Status *status);
 935
 936 /** Wait until some of several messages are transferred. Waits until at least
 937     one message is transferred.
 938
 939     \param[in]      count               The number of requests
 940     \param[in,out]  array_of_requests   List of count requests obtained with
 941                                         tMPI_Isend()/tMPI_Irecv().
 942     \param[out]     outcount            Number of completed requests
 943     \param[out]     array_of_indices    Array of ints that gets filled with
 944                                         the indices of the completed requests.
 945     \param[out]     array_of_statuses   List of count message statuses (can
 946                                         be set to TMPI_STATUSES_IGNORE).
 947
 948     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 949 int tMPI_Waitsome(int incount, tMPI_Request *array_of_requests,
 950                   int *outcount, int *array_of_indices,
 951                   tMPI_Status *array_of_statuses);
 952
 953 /** Test whether some of several messages are transferred.
 954
 955     \param[in]      count               The number of requests
 956     \param[in,out]  array_of_requests   List of count requests obtained with
 957                                         tMPI_Isend()/tMPI_Irecv().
 958     \param[out]     outcount            Number of completed requests
 959     \param[out]     array_of_indices    Array of ints that gets filled with
 960                                         the indices of the completed requests.
 961     \param[out]     array_of_statuses   List of count message statuses (can
 962                                         be set to TMPI_STATUSES_IGNORE).
 963
 964     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 965 int tMPI_Testsome(int incount, tMPI_Request *array_of_requests,
 966                  int *outcount, int *array_of_indices,
 967                  tMPI_Status *array_of_statuses);
 968
 969
 970
 971
 972
 973
 974 /** get the number of actually transferred items from a receive
 975     status.
 976
 977     \param[in]  status      The status.
 978     \param[in]  datatype    The data type which was received.
 979     \param[out] count       The number of items actually received.
 980
 981     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 982 int tMPI_Get_count(tMPI_Status *status, tMPI_Datatype datatype, int *count);
 983 /*! \} */
 984
 985
 986
 987
 988
 989
 990
 991
 992 /*! \name Synchronization functions
 993     \{ */
 994 /** Block until all threads in the comm call this function.
 995
 996     \param[in]  comm    The comm object.
 997
 998     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
 999 int tMPI_Barrier(tMPI_Comm comm);
1000 /*! \} */
1001
1002
1003
1004
1005
1006
1007
1008 /*! \name Multicast communication functions
1009     \{ */
1010 /** Broadcast from one thread to all others in comm.
1011
1012     Collective function; data is transferred from root's buffer to all others'
1013     buffer.
1014
1015     \param[in,out]  buffer      The buffer to send from (root)/receive from
1016                                 (other threads).
1017     \param[in]      count       The number of items to send/receive.
1018     \param[in]      datatype    The type of the items to send/receive.
1019     \param[in]      root        The rank of the sending thread.
1020     \param[in]      comm        The communicator.
1021
1022     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1023 int tMPI_Bcast(void* buffer, int count, tMPI_Datatype datatype, int root,
1024               tMPI_Comm comm);
1025
1026 /** Gather data from all threads in comm to root.
1027
1028     Collective function; assumes that all data is received in blocks of
1029     recvcount.
1030
1031     \param[in]      sendbuf     The send buffer for all threads (root may
1032                                 specify TMPI_IN_PLACE, in which case it
1033                                 transfers nothing to itself).
1034     \param[in]      sendcount   The number of items to send for all threads.
1035     \param[in]      sendtype    The type of the items to send.
1036     \param[out]     recvbuf     The receiving buffer (for root thread).
1037     \param[in]      recvcount   The number of items to receive (for root).
1038     \param[in]      recvtype    The type of the items to receive (for root).
1039     \param[in]      root        The rank of root.
1040     \param[in]      comm        The communicator.
1041
1042     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1043 int tMPI_Gather(void* sendbuf, int sendcount, tMPI_Datatype sendtype,
1044                void* recvbuf, int recvcount, tMPI_Datatype recvtype, int root,
1045                tMPI_Comm comm);
1046
1047
1048 /** Gather irregularly laid out data from all processes in comm to root.
1049
1050     Collective function.
1051
1052     \param[in]      sendbuf     The send buffer for all threads (root may
1053                                 specify TMPI_IN_PLACE, in which case it
1054                                 transfers nothing to itself).
1055     \param[in]      sendcount   The number of items to send for all threads.
1056     \param[in]      sendtype    The type of the items to send.
1057     \param[out]     recvbuf     The receiving buffer (for root thread).
1058     \param[in]      recvcounts  The list of number of items to receive (for
1059                                 root).
1060     \param[in]      displs      The list of displacements in recvbuf to
1061                                 receive data in (for root).
1062     \param[in]      recvtype    The type of the items to receive (for root).
1063     \param[in]      root        The rank of root.
1064     \param[in]      comm        The communicator.
1065
1066     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1067 int tMPI_Gatherv(void* sendbuf, int sendcount, tMPI_Datatype sendtype,
1068                 void* recvbuf, int *recvcounts, int *displs,
1069                 tMPI_Datatype recvtype, int root, tMPI_Comm comm);
1070
1071
1072 /** Spread parts of sendbuf to all processes in comm from root.
1073
1074     Collective function.
1075
1076     \param[in]      sendbuf     The send buffer for root.
1077     \param[in]      sendcount   The number of items for root to send to each
1078                                 thread.
1079     \param[in]      sendtype    The type of the items root sends.
1080     \param[out]     recvbuf     The receiving buffer for all receiving threads
1081                                 (root may specify TMPI_IN_PLACE, in which case
1082                                 it transmits nothing to itself).
1083     \param[in]      recvcount   The number of items recvbuf can receive.
1084     \param[in]      recvtype    The type of items to receive.
1085     \param[in]      root        The rank of root.
1086     \param[in]      comm        The communicator.
1087
1088     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1089 int tMPI_Scatter(void* sendbuf, int sendcount, tMPI_Datatype sendtype,
1090                 void* recvbuf, int recvcount, tMPI_Datatype recvtype, int root,
1091                 tMPI_Comm comm);
1092
1093 /** Spread irregularly laid out parts of sendbuf to all processes
1094             in comm from root.
1095
1096     Collective function.
1097
1098     \param[in]      sendbuf     The send buffer for root.
1099     \param[in]      sendcounts  List of the number of items for root to send
1100                                 to each thread.
1101     \param[in]      displs      List of displacements in sendbuf from which
1102                                 to start transmission to each thread.
1103     \param[in]      sendtype    The type of the items root sends.
1104     \param[out]     recvbuf     The receiving buffer for all receiving threads
1105                                 (root may specify TMPI_IN_PLACE, in which case
1106                                 it transmits nothing to itself).
1107     \param[in]      recvcount   The number of items recvbuf can receive.
1108     \param[in]      recvtype    The type of items to receive.
1109     \param[in]      root        The rank of root.
1110     \param[in]      comm        The communicator.
1111
1112     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1113 int tMPI_Scatterv(void* sendbuf, int *sendcounts, int *displs,
1114                  tMPI_Datatype sendtype, void* recvbuf, int recvcount,
1115                  tMPI_Datatype recvtype, int root, tMPI_Comm comm);
1116
1117
1118 /** Spread out parts of sendbuf to all processes from all processes in
1119            comm.
1120
1121     Collective function.
1122
1123     \param[in]      sendbuf     The send buffer.
1124     \param[in]      sendcount   The number of items for to send to each thread.
1125     \param[in]      sendtype    The type of the items to send.
1126     \param[out]     recvbuf     The receive buffer for all threads.
1127     \param[in]      recvcount   The number of items recvbuf can receive per
1128                                 thread.
1129     \param[in]      recvtype    The type of items to receive.
1130     \param[in]      comm        The communicator.
1131
1132     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1133 int tMPI_Alltoall(void* sendbuf, int sendcount, tMPI_Datatype sendtype,
1134                   void* recvbuf, int recvcount, tMPI_Datatype recvtype,
1135                   tMPI_Comm comm);
1136
1137
1138 /** Spread out irregularly laid out parts of sendbuf to all
1139            processes from all processes in comm.
1140
1141     Collective function.
1142
1143     \param[in]      sendbuf     The send buffer.
1144     \param[in]      sendcounts  List of the number of items for to send to
1145                                 each thread.
1146     \param[in]      sdispls     List of the displacements in sendbuf of items
1147                                 to send to each thread.
1148     \param[in]      sendtype    The type of the items to send.
1149     \param[out]     recvbuf     The receive buffer for all threads.
1150     \param[in]      recvcounts  List of the number of items recvbuf can
1151                                 receive from each thread.
1152     \param[in]      rdispls     List of the displacements in recvbuf of items
1153                                 to receive from each thread.
1154     \param[in]      recvtype    The type of items to receive.
1155     \param[in]      comm        The communicator.
1156
1157     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1158 int tMPI_Alltoallv(void* sendbuf, int *sendcounts, int *sdispls,
1159                   tMPI_Datatype sendtype, void* recvbuf, int *recvcounts,
1160                   int *rdispls, tMPI_Datatype recvtype, tMPI_Comm comm);
1161
1162 /*! \} */
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172 /*! \name Reduce functions
1173     \{ */
1174 /** Do an operation between all locally held buffers on all items in the
1175     buffers, and send the results to root.
1176
1177     Collective function.
1178
1179     \param[in]  sendbuf     The operand parameters. Root may specify
1180                             TMPI_IN_PLACE, in which case recvbuf will hold
1181                             the operand parameters.
1182     \param[out] recvbuf     The result buffer at root.
1183     \param[in]  count       The number of items to do operation on.
1184     \param[in]  datatype    The data type of the items.
1185     \param[in]  op          The operation to perform.
1186     \param[in]  root        The root thread (which is to receive the results).
1187     \param[in]  comm        The communicator.
1188
1189     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1190 int tMPI_Reduce(void* sendbuf, void* recvbuf, int count,
1191                tMPI_Datatype datatype, tMPI_Op op, int root, tMPI_Comm comm);
1192
1193
1194
1195 /** Do an operation between all locally held buffers on all items in the
1196     buffers and broadcast the results.
1197
1198     Collective function.
1199
1200
1201     \param[in]  sendbuf     The operand parameters. Any process may specify
1202                             TMPI_IN_PLACE, in which case recvbuf will hold
1203                             the operand parameters for that process.
1204     \param[out] recvbuf     The result buffer.
1205     \param[in]  count       The number of items to do operation on.
1206     \param[in]  datatype    The data type of the items.
1207     \param[in]  op          The operation to perform.
1208     \param[in]  comm        The communicator.
1209
1210     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1211 int tMPI_Allreduce(void* sendbuf, void* recvbuf, int count,
1212                   tMPI_Datatype datatype, tMPI_Op op, tMPI_Comm comm);
1213
1214 /** Do an tMPI_Reduce, but with the following assumption:
1215     recvbuf points to a valid buffer in all calling threads, or
1216     sendbuf has the value TMPI_IN_PLACE (in which case the values of
1217     sendbuf may be changed in that thread).
1218
1219     This avoids unnecesary memory allocations associated with the normal
1220     tMPI_Reduce.
1221
1222     Collective function.
1223
1224     \param[in]      sendbuf     The operand parameters (or TMPI_IN_PLACE,
1225                                 in which case the operand parameters will
1226                                 be in recvbuf).
1227     \param[in,out]  recvbuf     The result buffer.
1228     \param[in]      count       The number of items to do operation on.
1229     \param[in]      datatype    The data type of the items.
1230     \param[in]      op          The operation to perform.
1231     \param[in]      root        The root thread (which is to receive
1232                                 the final results).
1233     \param[in]      comm        The communicator.
1234
1235     \return  TMPI_SUCCESS on success, TMPI_FAILURE on failure.  */
1236 int tMPI_Reduce_fast(void* sendbuf, void* recvbuf, int count,
1237                      tMPI_Datatype datatype, tMPI_Op op, int root,
1238                      tMPI_Comm comm);
1239 /*! \} */
1240
1241
1242
1243 #ifdef __cplusplus
1244 } /* closing extern "C" */
1245 #endif
1246
1247 #endif /* _TMPI_H_ */