MPI_FESTIVUS(3)

NAME

MPI_Festivus – An MPI function for the rest of us

SYNTAX

C Syntax

   #include 
   int MPI_Festivus(void *handle, char *requested, char *provided,
        MPI_Info *result)

Fortran Syntax

   use mpi_f08
   MPI_FESTIVUS(handle, requested, provided, resultlen, result, ierror)
        <type> handle
        CHARACTER(LEN=MPI_MAX_HOLIDAY_NAME), INTENT(IN) :: requested
        CHARACTER(LEN=MPI_MAX_HOLIDAY_NAME), INTENT(OUT) :: provided
        INTEGER, INTENT(OUT) :: resultlen
        TYPE(MPI_Info), INTENT(OUT) :: result
        INTEGER, OPTIONAL, INTENT(OUT) :: ierror

INPUT PARAMETERS

• handle: MPI handle used to observe the holiday
• requested: Name of the requested Winter festival to celebrate

OUTPUT PARAMETERS

• provided Name of the actual Winter festival that was celebrated
• result Result of celebrating the provided Winter festival
• resultlen: Length of the result string (Fortran only)
• ierror: Error status (Fortran only)

DESCRIPTION

MPI_FESTIVUS requests a specified Winter celebration to be celebrated on the specified MPI handle.

A new info object is returned containing information describing the results of the provided Winter celebration. The user is responsible for freeing result via MPI_INFO_FREE.

In some cases, even if the requested Winter celebration may be supported, it may not be able to be celebrated for implementation-specific reasons. This is not necessarily an error, as this may be the expected result of an attempted Winter festival celebration. Instead, the results of the attempted celebration will be contained in result.

Example 1:

   $ cat festivus_example.c
   #include 
   #include "mpi.h"

   int main(int argc, char* argv[]) {
       MPI_Init(NULL, NULL);
       char *buffer = malloc(100663296);
       char requested[MPI_MAX_HOLIDAY_NAME] = "Christmas";
       char provided[MPI_MAX_HOLIDAY_NAME];
       MPI_Info result;
       MPI_Festivus(MPI_COMM_WORLD, requested, &provided, &result)

       printf("Provided: %s\n", provided);
       print_info_keys(result);

       MPI_Info_free(&result);
       MPI_Finalize();
       return 0;
   }
   $ mpicc festivus_example.c -lprint_info_keys -O3 -g -o festivus_example
   $ mpirun -np 1 festivus_example
   Provided: Christmas
   result = coal
   reason = naughty (too much memory requested)

Note, too, that different Winter festivals can be requested on different MPI handles in order to create a diverse application.

Example 2:

   $ cat festivus_example2.c
   #include 
   #include "mpi.h"

   int main(int argc, char* argv[]) {
       MPI_Init(NULL, NULL);
       char requested[MPI_MAX_HOLIDAY_NAME] = "Hanukkah";
       char provided[MPI_MAX_HOLIDAY_NAME];
       MPI_Info result;

       MPI_Festivus(MPI_COMM_SELF, requested, &provided, &result)
       printf("Provided: %s\n", provided);
       print_info_keys(result);
       MPI_Info_free(&result);

       strcpy(requested, "Christmas");
       MPI_Festivus(MPI_COMM_WOLRD, requested, &provided, &result)
       printf("Provided: %s\n", provided);
       print_info_keys(result);
       MPI_Info_free(&result);

       MPI_Finalize();
       return 0;
   }
   $ mpicc festivus_example2.c -lprint_info_keys -O3 -g -o festivus_example2
   $ mpirun -np 1 festivus_example2
   Provided: Hanukkah
   result = Menorah
   Provided: Christmas
   result = toys
   reason = nice

ADVICE TO IMPLEMENTORS

Although implementors are encouraged to support as many Winter celebrations as possible, it is clear that not all Winter celebrations may be observable in all environments (e.g., some require too many resources for constrained run-time environments).

ERRORS

As with other MPI functions, MPI_FESTIVUS returns MPI_SUCCESS upon successful execution. MPI_ERR_NOT_SUPPORTED may be returned if the requested Winter celebration is not supported and no suitable replacement can be found.

SEE ALSO

MPI_INIT, MPI_FINALIZE