MPI_TYPE_GET_TRUE_EXTENT_X(3)

📦
version 5.0.10 · 4 versions
, in ubuntu stonking

💅 MPI_TYPE_GET_TRUE_EXTENT_X — Open MPI, bestie edition ✨

okay so this is a page from the Open MPI manual, and wow does it have range. Two whole functions, four whole language bindings, and they do exactly one (1) thing: tell you the true lower bound and the true extent of a data type's corresponding typemap, ignoring MPI_UB and MPI_LB markers. no cap.

The functions on deck:

  • MPI_Type_get_true_extent
  • MPI_Type_get_true_extent_x

🌸 SYNTAX 🌸

🎀 C Syntax

#include <mpi.h>

int MPI_Type_get_true_extent(MPI_Datatype datatype,
     MPI_Aint *true_lb, MPI_Aint *true_extent)
int MPI_Type_get_true_extent_x(MPI_Datatype datatype,
     MPI_Count *true_lb, MPI_Count *true_extent)

🎀 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_TYPE_GET_TRUE_EXTENT(DATATYPE, TRUE_LB, TRUE_EXTENT, IERROR)
     INTEGER DATATYPE, IERROR
     INTEGER(KIND=MPI_ADDRESS_KIND) TRUE_LB, TRUE_EXTENT
MPI_TYPE_GET_TRUE_EXTENT_X(DATATYPE, TRUE_LB, TRUE_EXTENT, IERROR)
     INTEGER DATATYPE, IERROR
     INTEGER(KIND=MPI_COUNT_KIND) TRUE_LB, TRUE_EXTENT

🎀 Fortran 2008 Syntax

USE mpi_f08
MPI_Type_get_true_extent(datatype, true_lb, true_extent, ierror)
     TYPE(MPI_Datatype), INTENT(IN) :: datatype
     INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(OUT) :: true_lb, true_extent
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror
MPI_Type_get_true_extent_x(datatype, true_lb, true_extent, ierror)
     TYPE(MPI_Datatype), INTENT(IN) :: datatype
     INTEGER(KIND = MPI_COUNT_KIND), INTENT(OUT) :: true_lb, true_extent
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

🫶 INPUT PARAMETER

  • datatype — the data type you're being nosy about, aka the one you want info on. it's a handle, bestie. give it what it wants.

⭐ OUTPUT PARAMETERS

  • true_lb — the true lower bound of the data type. it's an integer. 💖
  • true_extent — the true size of the data type. also an integer, we love a consistent queen. 💖
  • ierror — Fortran only, babes: the error status, as an integer. 🙈

🔥 DESCRIPTION 🔥

okay so let's break it down, because this is actually so satisfying once it clicks.

true_lb gives you back the offset of the lowest unit of store that's addressed by the data type — that is, the lower bound of the corresponding typemap, and it's ignoring MPI_LB markers. periodt.

true_extent gives you back the true size of the data type — that is, the extent of the corresponding typemap, ignoring MPI_LB and MPI_UB markers, and it does no rounding for alignment. not even a little. it's giving raw, unfiltered truth.

And here's the ✨fun✨ part: for both functions, if either the true_lb or true_extent parameter is too small to express the value that's supposed to come back, it gets set to MPI_UNDEFINED. so like, the parameter literally cannot hold the output value — that's the example the docs give — and boom, MPI_UNDEFINED. 😭

Also, in case you needed it spelled out: the true_extent is the minimum number of bytes of memory necessary to hold a data type, uncompressed. that's the whole vibe right there.

If you want the full, real, extremely-thorough definition of how these parameters relate to the typemap, go read section 4.1.8 of the MPI-3 standard. the docs said it, not me. iykyk. 📚

😭 ERRORS 😭

so, error handling. almost all MPI routines return an error value, and the way they hand it to you depends on the language:

  • C routines — it comes back as the return result of the function.
  • Fortran routines — it lands in that last argument.

Before the error value comes back to you, the current MPI error handler that's associated with the communication object (think: communicator, window, file) gets called. and if there's no communication object associated with the MPI call? then the call is considered attached to MPI_COMM_SELF, and it'll call the associated MPI error handler. 💅

When MPI_COMM_SELF is not initialized — like, before MPI_Init/MPI_Init_thread, after MPI_Finalize, or when you're using the Sessions Model exclusively — the error raises the initial error handler. You can change that initial error handler by:

  • calling MPI_Comm_set_errhandler on MPI_COMM_SELF when you're using the World model, or
  • using 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 is called for MPI I/O functions
  • MPI_ERRORS_ABORT is called for all other MPI functions

👑 the three predefined error handlers Open MPI ships with

  • MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. dramatic. iconic. permanent.
  • MPI_ERRORS_ABORT — an error handler you can invoke 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.
  • MPI_ERRORS_RETURN — returns an error code to the application. the chill one. 🧘

🦋 roll your own error handler, why don't you

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
⚠️ important, and I mean it: MPI does not guarantee that an MPI program can continue past an error. so don't go assuming you can just keep vibing after one. 💀

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

2003-2026, The Open MPI Community

and that's the whole page, bestie — no crumbs left, ate and left no notes. mwah. 💋

this lil masterpiece is page MPI_TYPE_GET_TRUE_EXTENT_X(3), from the Open MPI manual, last touched up on Sep 10, 2026. copyright 2003-2026, The Open MPI Community — huge shoutout to them, fr fr. go forth and get those true extents. 🌈✨🫶

📦 where this page comes from