#ifndef __FVM_PARALL_H__
#define __FVM_PARALL_H__

/*============================================================================
 * Base functions for parallelism
 *============================================================================*/

/*
  This file is part of the "Finite Volume Mesh" library, intended to provide
  finite volume mesh and associated fields I/O and manipulation services.

  Copyright (C) 2004-2006  EDF

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

/*----------------------------------------------------------------------------*/

#include <fvm_config.h>

#if defined(FVM_HAVE_MPI)
#include <mpi.h>
#endif

/*----------------------------------------------------------------------------
 *  Local headers
 *----------------------------------------------------------------------------*/

#include <fvm_defs.h>

/*----------------------------------------------------------------------------*/

#ifdef __cplusplus
extern "C" {
#if 0
} /* Fake brace to force back Emacs auto-indentation back to column 0 */
#endif
#endif /* __cplusplus */

/*=============================================================================
 * Macro definitions
 *============================================================================*/

/*============================================================================
 * Type definitions
 *============================================================================*/

#if defined(FVM_HAVE_MPI)

#define FVM_MPI_TAG      (int)('F'+'V'+'M') /* MPI tag for FVM operations */

#define FVM_MPI_LNUM     MPI_INT            /* MPI type corresponding to
                                               fvm_lnum_t integer type */
#define FVM_MPI_GNUM     MPI_UNSIGNED       /* MPI type corresponding to
                                               fvm_gnum_t integer type */
#define FVM_MPI_COORD    MPI_DOUBLE         /* MPI type corresponding to
                                               fvm_coord_t integer type */

#endif

/*=============================================================================
 * Static global variables
 *============================================================================*/

/* MPI Datatypes associated with fvm datatypes */

#if defined(FVM_HAVE_MPI)

extern MPI_Datatype  fvm_datatype_to_mpi[];

#endif

/*=============================================================================
 * Public function prototypes
 *============================================================================*/

#if defined(FVM_HAVE_MPI)

/*----------------------------------------------------------------------------
 * Return default MPI communicator for FVM library functions.
 *
 * returns:
 *   handle to MPI communicator
 *----------------------------------------------------------------------------*/

MPI_Comm
fvm_parall_get_mpi_comm(void);

/*----------------------------------------------------------------------------
 * Set default MPI communicator for FVM library functions.
 *
 * parameters:
 *   comm <-- handle to MPI communicator
 *----------------------------------------------------------------------------*/

void
fvm_parall_set_mpi_comm(const MPI_Comm  comm);

#endif /* defined(FVM_HAVE_MPI) */

/*----------------------------------------------------------------------------
 * Return rank of current process among associated program processes.
 *
 * returns:
 *   rank of current process in current communicator, or 0 in scalar mode
 *----------------------------------------------------------------------------*/

int
fvm_parall_get_rank(void);

/*----------------------------------------------------------------------------
 * Return number of processes associated with the current program.
 *
 * returns:
 *   number of processes in current communicator, or 1 in scalar mode
 *----------------------------------------------------------------------------*/

int
fvm_parall_get_size(void);

/*----------------------------------------------------------------------------
 * Sum counters on all FVM default communicator processes.
 *
 * parameters:
 *   cpt <-> local counter value  input, global counter value output (array)
 *   n   <-- number of counter array values
 *----------------------------------------------------------------------------*/

#if defined(FVM_HAVE_MPI)
void
fvm_parall_counter(fvm_gnum_t  cpt[],
                   const int   n);
#else
#define fvm_parall_counter(_cpt, _n)
#endif

/*----------------------------------------------------------------------------
 * Maximum values of a counter on all FVM default communicator processes.
 *
 * parameters:
 *   cpt <-> local counter value  input, global counter value output (array)
 *   n   <-- number of counter array values
 *----------------------------------------------------------------------------*/

#if defined(FVM_HAVE_MPI)
void
fvm_parall_counter_max(fvm_lnum_t  cpt[],
                       const int   n);
#else
#define fvm_parall_counter_max(_cpt, _n)
#endif

/*----------------------------------------------------------------------------
 * Return minimum recommended scatter or gather buffer size.
 *
 * This is used by FVM's internal strided and indexed array scatter/gather
 * algorithms, for non MPI-IO Input/output.
 *
 * returns:
 *   minimum recommended gather buffer size (in bytes)
 *----------------------------------------------------------------------------*/

size_t
fvm_parall_get_min_coll_buf_size(void);

/*----------------------------------------------------------------------------
 * Define minimum recommended scatter or gather buffer size.
 *
 * This is used by FVM's internal strided and indexed array scatter/gather
 * algorithms, for non MPI-IO Input/output.
 *
 * parameters:
 *   minimum recommended gather buffer size (in bytes)
 *----------------------------------------------------------------------------*/

void
fvm_parall_set_min_coll_buf_size(size_t buffer_size);

/*----------------------------------------------------------------------------
 * Indicates if safe synchronization gather mode is set.
 *
 * This is used by FVM's internal strided and indexed array gather
 * algorithms, for non MPI-IO Input/output.
 *
 * Using this mode (unset by default), rank 0 sends a message to other
 * ranks prior to receiving data from them, and data size is indicated
 * by an extra message rather than probing the incoming messages.
 * This may be slightly slower, but should avoid buffer allocation issues
 * with high processor counts.
 *
 * returns:
 *   1 if safe mode is set, 0 if unset.
 *----------------------------------------------------------------------------*/

int
fvm_parall_get_safe_gather_mode(void);

/*----------------------------------------------------------------------------
 * Set or unset safe synchronization gather mode.
 *
 * This is used by FVM's internal strided and indexed array gather
 * algorithms, for non MPI-IO Input/output.
 *
 * Using this mode (unset by default), rank 0 sends a message to other
 * ranks prior to receiving data from them, and data size is indicated
 * by an extra message rather than probing the incoming messages.
 * This may be slightly slower, but should avoid buffer allocation issues
 * with high processor counts.
 *
 * parameters:
 *   1 to set safe mode, 0 to unset.
 *----------------------------------------------------------------------------*/

void
fvm_parall_set_safe_gather_mode(int safe_mode);

/*----------------------------------------------------------------------------*/

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* __FVM_PARALL_H__ */