NAME

MPI_Festivus -An MPI function for the rest of us

SYNTAX

C Syntax

   #includeint 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

• providedName of the actual Winter festival that was celebrated
• resultResult 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