5.2.60hdfql_mpi_use_communicator

#Syntax

#Description

Set the MPI communicator named communicator as the one to be used when performing operations (e.g. SELECT) in parallel. An MPI communicator represents a group of processes that participate in the communication, which may involve some or all the processes specified when launching a program using “mpiexec” (or a similar launcher). Of note, if the function is called before the first call to an operation (CREATE FILE, INSERT, SELECT, or USE FILE) or a function (hdfql_mpi_get_size or hdfql_mpi_get_rank) that employs parallelism, HDFql will not initialize the MPI library, as it assumes that the initialization was previously done by the programmer through MPI function “MPI_Init” (please refer to https://www.mpich.org/static/docs/v3.4/www3/MPI_Init.html or https://www.open-mpi.org/doc/v3.1/man3/MPI_Init.3.php for additional information in case the MPI library used is MPICH or Open MPI, respectively).

#Parameter(s)

communicator – pointer to an MPI communicator to use when performing operations in parallel. If the pointer is NULL (in C), the default MPI communicator (MPI_COMM_WORLD) is used instead (i.e. equivalent to calling the function hdfql_mpi_use_default_communicator). The equivalent of a NULL pointer in C++, Java, Python, C#, Fortran, R, and MATLAB HDFql wrappers is NULL, null, None, null, NULL(), NULL, and NaN, respectively.

#Return

int – depending on the success in using communicator, it can be HDFQL_SUCCESS, HDFQL_ERROR_NOT_SUPPORTED (in case MPI itself was not initialized properly or when using an HDFql non MPI-based distribution), or HDFQL_ERROR_UNKNOWN.

#Example(s)

// declare variables 
MPI_Comm my_communicator;
MPI_Group group;
int ranks[2];

// create an MPI group named "group" containing processes (i.e. ranks) #0 and #1 
ranks[0] = 0; 
ranks[1] = 1;
MPI_Group_incl(MPI_COMM_WORLD, 2, ranks, &group);

// create an MPI communicator named "my_communicator" based on MPI group "group" 
MPI_Comm_create(MPI_COMM_WORLD, group, &my_communicator);

// use MPI communicator "my_communicator" in subsequent operations performed in parallel 
hdfql_mpi_use_communicator(&my_communicator);

// select (i.e. read) dataset named "my_dataset" in parallel using MPI communicator "my_communicator"
hdfql_execute("SELECT FROM my_dataset IN PARALLEL");

// use default MPI communicator (MPI_COMM_WORLD) in subsequent operations performed in parallel
hdfql_mpi_use_communicator(NULL); 

// select (i.e. read) dataset "my_dataset" in parallel using default MPI communicator (MPI_COMM_WORLD)
hdfql_execute("SELECT FROM my_dataset IN PARALLEL");