MPI_TYPE_GET_ENVELOPE(3)

📦
version 5.0.10 · 7 versions
, in ubuntu stonking

💖 NAME

okay so bestie, today's main character is MPI_Type_get_envelope — she returns information about input arguments associated with a data type. this is from the Open MPI manual, and she is serving ✨

✨ SYNTAX

🌈 C Syntax

#include <mpi.h>

int MPI_Type_get_envelope(MPI_Datatype datatype, int *num_integers,
     int *num_addresses, int *num_datatypes, int *combiner)

🌈 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_TYPE_GET_ENVELOPE(DATATYPE, NUM_INTEGERS, NUM_ADDRESSES,
             NUM_DATATYPES, COMBINER, IERROR)
     INTEGER DATATYPE, NUM_INTEGERS, NUM_ADDRESSES
     INTEGER NUM_DATATYPES, COMBINER, IERROR

🌈 Fortran 2008 Syntax

USE mpi_f08
MPI_Type_get_envelope(datatype, num_integers, num_addresses, num_datatypes,
             combiner, ierror)
     TYPE(MPI_Datatype), INTENT(IN) :: datatype
     INTEGER, INTENT(OUT) :: num_integers, num_addresses, num_datatypes,
     combiner
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

🫶 INPUT PARAMETER

  • datatype — the data type you wanna access, as a handle. like, the one you're snooping on 👀

🎀 OUTPUT PARAMETERS

  • num_integers — how many input integers were used in the call that constructed the combiner. it's a nonnegative integer, so no negativity allowed, periodt 💅
  • num_addresses — how many input addresses were used in the call constructing the combiner (also a nonnegative integer, naturally).
  • num_datatypes — how many input data types were used in the call constructing the combiner (nonnegative integer, we love consistency).
  • combiner — the combiner, i.e. the state. she's telling you which constructor birthed this datatype 🦋
  • ierror — Fortran only: the error status (integer). boo, Fortran, but ily 🤍

🦋 DESCRIPTION

so for any given data type, MPI_Type_get_envelope hands you back the info on the number and type of input arguments that were used in the call which created it. basically a birth certificate for your datatype, no cap 🍼

the number-of-arguments values it returns? you use those to make arrays big enough when you go decode everything with MPI_Type_get_contents. so it's the lil pre-game before the actual reveal, iykyk 💁‍♀️

this call, plus the meaning of all those returned values, is described right below. and the combiner? she reflects the MPI data type constructor call that was used in creating datatype. iconic behaviour honestly 👑

🌸 NOTES

these are the values that can come back in combiner, and their associated calls:

  • MPI_COMBINER_NAMED — a named predefined data type
  • MPI_COMBINER_DUP — MPI_Type_dup
  • MPI_COMBINER_CONTIGUOUS — MPI_Type_contiguous
  • MPI_COMBINER_VECTOR — MPI_Type_vector
  • MPI_COMBINER_HVECTOR — MPI_Type_hvector and MPI_Type_create_hvector
  • MPI_COMBINER_INDEXED — MPI_Type_indexed
  • MPI_COMBINER_HINDEXED — MPI_Type_hindexed and MPI_Type_create_hindexed
  • MPI_COMBINER_INDEXED_BLOCK — MPI_Type_create_indexed_block
  • MPI_COMBINER_STRUCT — MPI_Type_struct and MPI_Type_create_struct
  • MPI_COMBINER_SUBARRAY — MPI_Type_create_subarray
  • MPI_COMBINER_DARRAY — MPI_Type_create_darray
  • MPI_COMBINER_F90_REAL — MPI_Type_create_f90_real
  • MPI_COMBINER_F90_COMPLEX — MPI_Type_create_f90_complex
  • MPI_COMBINER_F90_INTEGER — MPI_Type_create_f90_integer
  • MPI_COMBINER_RESIZED — MPI_Type_create_resized

and if combiner comes back as MPI_COMBINER_NAMED? then datatype is a named predefined data type, simple as that bestie 💅

the actual arguments used in the creation call for a data type can be pulled from the call MPI_Type_get_contents. that's where the receipts live 🧾

😭 ERRORS

almost all MPI routines return an error value — C routines hand it back as the return result of the function, and Fortran routines stick it in the last argument. classic.

before that error value gets returned, the current MPI error handler associated with the communication object (like a communicator, window, or file) gets called. if no communication object is associated with the MPI call, then the call is considered attached to MPI_COMM_SELF and will call the associated MPI error handler. and when MPI_COMM_SELF is not initialized (meaning before MPI_Init/MPI_Init_thread, after MPI_Finalize, or when using the Sessions Model exclusively), the error raises the initial error handler. that initial error handler can be changed by calling MPI_Comm_set_errhandler on MPI_COMM_SELF when using the World model, or via the mpi_initial_errhandler CLI argument to mpiexec, or the info key to MPI_Comm_spawn/MPI_Comm_spawn_multiple. and if no other appropriate error handler has been set, then MPI_ERRORS_RETURN gets called for MPI I/O functions and MPI_ERRORS_ABORT gets called for all other MPI functions. wow that was a mouthful 🫠

Open MPI ships three predefined error handlers you can use:

  • MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. yeah. it's giving chaos 💀
  • MPI_ERRORS_ABORT — an error handler that can be invoked on a communicator, window, file, or session. when called on a communicator, it acts as if MPI_Abort was called on that communicator. if called on a window or file, it acts as if MPI_Abort was called on a communicator containing the group of processes in the corresponding window or file. if called on a session, it aborts only the local process. versatile queen tbh.
  • MPI_ERRORS_RETURN — returns an error code to the application. polite. respectful. we love her 🌸

MPI applications can also implement their own error handlers by calling:

  • MPI_Comm_create_errhandler then MPI_Comm_set_errhandler
  • MPI_File_create_errhandler then MPI_File_set_errhandler
  • MPI_Session_create_errhandler then MPI_Session_set_errhandler, or at MPI_Session_init
  • MPI_Win_create_errhandler then MPI_Win_set_errhandler
⚠️ note that MPI does not guarantee that an MPI program can continue past an error. so like, do not keep going and act surprised, bestie 😭

see the MPI man page for a full list of MPI error codes. see the Error Handling section of the MPI-3.1 standard for more information.

See also:

  • MPI_Type_get_contents

2003-2026, The Open MPI Community

and that's a wrap, my love 🌈 this page is from the Open MPI manual, dated Sep 10, 2026, section 3, titled MPI_TYPE_GET_ENVELOPE(3). go forth and decode your datatypes, you absolute icon 🎀💖✨

📦 where this page comes from