Commit c5b76b70 authored by Moritz Hanke's avatar Moritz Hanke Committed by Thomas Jahns
Browse files

improves documentation of exchangers

parent 7afe7695
......@@ -102,16 +102,15 @@ Xt_redist xt_redist_repeat_custom_new(Xt_redist redist, MPI_Aint src_extent,
/**
* constructor for a redistribution that has a repetitive pattern, which
* is described by the given redistribution. Uses default settings.
* @param[in] redist redistribution
* @param[in] src_extent extent that scales the given displacements
* for the source data
* @param[in] dst_extent extent that scales the given displacements
* for the destination data
* @param[in] num_repetitions number of repetitions of the given
* redistribution
* @param[in] src_displacements displacements for source repetitions
*
* @param[in] dst_displacements displacements for destination repetitions
* @param[in] redist redistribution
* @param[in] src_extent extent that scales the given displacements
* for the source data
* @param[in] dst_extent extent that scales the given displacements
* for the destination data
* @param[in] num_repetitions number of repetitions of the given
* redistribution
* @param[in] src_displacements displacements for source repetitions
* @param[in] dst_displacements displacements for destination repetitions
*
*/
Xt_redist
......@@ -123,16 +122,16 @@ xt_redist_repeat_asym_new(Xt_redist redist, MPI_Aint src_extent,
/**
* constructor for a redistribution that has a repetitive pattern, which
* is described by the given redistribution. Uses custom settings.
* @param[in] redist redistribution
* @param[in] src_extent extent that scales the given displacements
* for the source data
* @param[in] dst_extent extent that scales the given displacements
* for the destination data
* @param[in] num_repetitions number of repetitions of the given
* redistribution
* @param[in] src_displacements displacements for source repetitions
*
* @param[in] dst_displacements displacements for destination repetitions
* @param[in] redist redistribution
* @param[in] src_extent extent that scales the given displacements
* for the source data
* @param[in] dst_extent extent that scales the given displacements
* for the destination data
* @param[in] num_repetitions number of repetitions of the given
* redistribution
* @param[in] src_displacements displacements for source repetitions
* @param[in] dst_displacements displacements for destination repetitions
* @param[in] config configuration object for custom settings
*
*/
Xt_redist
......
......@@ -91,6 +91,7 @@ xt_redist_single_array_base_new(int nsend, int nrecv,
* @param[in] recv_msgs array with receive messages
* @param[in] comm MPI communicator that is to be used for the
* communication
* @param[in] config configuration object for custom settings
*/
Xt_redist
xt_redist_single_array_base_custom_new(int nsend, int nrecv,
......
/**
* @file xt_config_internal.c
* @file xt_config.c
* @brief implementation of configuration object
*
* @copyright Copyright (C) 2020 Jörg Behrens <behrens@dkrz.de>
......
/**
* @file xt_config_internal.c
* @file xt_config_internal.h
* @brief implementation of configuration object
*
* @copyright Copyright (C) 2020 Jörg Behrens <behrens@dkrz.de>
......
......@@ -112,17 +112,16 @@ xt_exchanger_irecv_isend_a_exchange(const void *src_data, void *dst_data,
*request = requests;
}
/**
* @param tag_offset tag tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
Xt_exchanger
xt_exchanger_irecv_isend_new(int nsend, int nrecv,
const struct Xt_redist_msg *send_msgs,
const struct Xt_redist_msg *recv_msgs,
MPI_Comm comm, int tag_offset) {
/** note: tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
return xt_exchanger_simple_base_new(nsend, nrecv, send_msgs, recv_msgs,
comm, tag_offset,
xt_exchanger_irecv_isend_s_exchange,
......
......@@ -54,6 +54,19 @@
#include "xt_exchanger.h"
#include "xt_redist_internal.h"
/**
* constructor for an exchanger using asynchronous send and recv
* @param[in] nsend number of send messages
* @param[in] nrecv number of receive messages
* @param[in] send_msgs array with send messages
* @param[in] recv_msgs array with receive messages
* @param[in] comm MPI communicator that is to be used for the
* communication
* @param[in] tag_offset tag
* @remark tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
Xt_exchanger
xt_exchanger_irecv_isend_new(int nsend, int nrecv,
const struct Xt_redist_msg *send_msgs,
......
......@@ -184,6 +184,10 @@ xt_exchanger_irecv_isend_packed_new(int nsend, int nrecv,
const struct Xt_redist_msg *recv_msgs,
MPI_Comm comm, int tag_offset) {
/** note: tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
return xt_exchanger_simple_base_new(nsend, nrecv, send_msgs, recv_msgs,
comm, tag_offset,
xt_exchanger_irecv_isend_packed_s_exchange,
......
......@@ -54,6 +54,21 @@
#include "xt_exchanger.h"
#include "xt_redist_internal.h"
/**
* Constructor for an exchanger using asynchronous send and recv, the data is
* is packed before/unpacked after the exchange. This ensures that the data
* being handled by MPI is in one contiguous buffer.
* @param[in] nsend number of send messages
* @param[in] nrecv number of receive messages
* @param[in] send_msgs array with send messages
* @param[in] recv_msgs array with receive messages
* @param[in] comm MPI communicator that is to be used for the
* communication
* @param[in] tag_offset tag
* @remark tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
Xt_exchanger
xt_exchanger_irecv_isend_packed_new(int nsend, int nrecv,
const struct Xt_redist_msg *send_msgs,
......
......@@ -87,6 +87,10 @@ xt_exchanger_irecv_send_new(int nsend, int nrecv,
const struct Xt_redist_msg * recv_msgs,
MPI_Comm comm, int tag_offset) {
/** note: tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
return xt_exchanger_simple_base_new(nsend, nrecv, send_msgs, recv_msgs,
comm, tag_offset,
xt_exchanger_irecv_send_s_exchange,
......
......@@ -54,6 +54,19 @@
#include "xt_exchanger.h"
#include "xt_redist_internal.h"
/**
* constructor for an exchanger using synchronous send and asynchronous recv.
* @param[in] nsend number of send messages
* @param[in] nrecv number of receive messages
* @param[in] send_msgs array with send messages
* @param[in] recv_msgs array with receive messages
* @param[in] comm MPI communicator that is to be used for the
* communication
* @param[in] tag_offset tag
* @remark tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
Xt_exchanger
xt_exchanger_irecv_send_new(int nsend, int nrecv,
const struct Xt_redist_msg *send_msgs,
......
......@@ -128,6 +128,11 @@ xt_exchanger_mix_isend_irecv_new(int nsend, int nrecv,
const struct Xt_redist_msg *recv_msgs,
MPI_Comm comm, int tag_offset) {
/** note: tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
assert((nsend >= 0) & (nrecv >= 0));
size_t nmsg = (size_t)nsend + (size_t)nrecv;
Xt_exchanger_mix_isend_irecv exchanger
......
......@@ -54,6 +54,21 @@
#include "xt_redist_internal.h"
#include "xt_exchanger.h"
/**
* Constructor for an exchanger using asynchronous send and recv. The order in
* which the send's and recv's are called are optimised to reduce network
* congestion and improve performance.
* @param[in] nsend number of send messages
* @param[in] nrecv number of receive messages
* @param[in] send_msgs array with send messages
* @param[in] recv_msgs array with receive messages
* @param[in] comm MPI communicator that is to be used for the
* communication
* @param[in] tag_offset tag
* @remark tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
Xt_exchanger
xt_exchanger_mix_isend_irecv_new(int nsend, int nrecv,
const struct Xt_redist_msg *send_msgs,
......
......@@ -152,6 +152,11 @@ xt_exchanger_neigh_alltoall_new(int nsend, int nrecv,
const struct Xt_redist_msg *recv_msgs,
MPI_Comm comm, int tag_offset) {
/** note: tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
int flag;
xt_mpi_call(MPI_Comm_test_inter(comm, &flag), comm);
if (flag)
......
......@@ -54,6 +54,21 @@
#include "xt_exchanger.h"
#include "xt_redist_internal.h"
/**
* constructor for an exchanger using a collective all to all operation on a
* virtual topoloy
* @param[in] nsend number of send messages
* @param[in] nrecv number of receive messages
* @param[in] send_msgs array with send messages
* @param[in] recv_msgs array with receive messages
* @param[in] comm MPI communicator that is to be used for the
* communication
* @param[in] tag_offset tag
* @remark tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
* @remark this exchanger requires MPI Version 3 or higher
*/
Xt_exchanger
xt_exchanger_neigh_alltoall_new(int nsend, int nrecv,
const struct Xt_redist_msg *send_msgs,
......
......@@ -122,6 +122,11 @@ xt_exchanger_simple_base_new(int nsend, int nrecv,
xt_simple_s_exchange_func s_func,
xt_simple_a_exchange_func a_func) {
/** note: tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
if (s_func == NULL)
Xt_abort(comm, "ERROR(xt_exchanger_simple_base_new): invalid synchronous "
"exchange function pointer", __FILE__, __LINE__);
......
......@@ -64,6 +64,21 @@ typedef void (*xt_simple_a_exchange_func)(
const struct Xt_redist_msg *send_msgs, const struct Xt_redist_msg *recv_msgs,
int tag_offset, MPI_Comm comm, Xt_request *request);
/**
* constructor for an exchanger using asynchronous send and recv
* @param[in] nsend number of send messages
* @param[in] nrecv number of receive messages
* @param[in] send_msgs array with send messages
* @param[in] recv_msgs array with receive messages
* @param[in] comm MPI communicator that is to be used for the
* communication
* @param[in] tag_offset tag
* @param[in] s_func function pointer used for synchronous exchanges
* @param[in] a_func function pointer used for asynchronous exchanges
* @remark tag_offset + xt_mpi_tag_exchange_msg must not
* be used on @a comm by any other part of the program during the
* lifetime of the created exchanger object
*/
Xt_exchanger
xt_exchanger_simple_base_new(int nsend, int nrecv,
const struct Xt_redist_msg *send_msgs,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment