MPI_GET_ELEMENTS_X(3)

📦

version 5.0.10 · 4 versions

👑 MPI_GET_ELEMENTS_X 💅

hi bestie!! welcome to the Open MPI manual page for MPI_Get_elements_x(3) — yes it's the _x one, and yeah, its bestie MPI_Get_elements is riding along in the same doc because they're basically the same girl in two different sizes. sit down, grab a boba, and let's talk element counting 🧋✨

✨ NAME ✨

MPI_Get_elements, MPI_Get_elements_x — returns the number of basic elements in a data type. 🦋

no fr, that's the whole job. it counts the basic elements, not the top-level copies. we'll get into why that slaps in a sec.

🌸 SYNTAX 🌸

💻 C Syntax

#include <mpi.h>

int MPI_Get_elements(const MPI_Status *status, MPI_Datatype datatype,
    int *count)

int MPI_Get_elements_x(const MPI_Status *status, MPI_Datatype datatype,
    MPI_Count *count)

🎀 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'

MPI_GET_ELEMENTS(STATUS, DATATYPE, COUNT, IERROR)
    INTEGER STATUS(MPI_STATUS_SIZE), DATATYPE, COUNT, IERROR

MPI_GET_ELEMENTS_X(STATUS, DATATYPE, COUNT, IERROR)
    INTEGER STATUS(MPI_STATUS_SIZE), DATATYPE
        INTEGER(KIND=MPI_COUNT_KIND) COUNT
        INTEGER IERROR

🧚 Fortran 2008 Syntax

USE mpi_f08

MPI_Get_elements(status, datatype, count, ierror)
    TYPE(MPI_Status), INTENT(IN) :: status
    TYPE(MPI_Datatype), INTENT(IN) :: datatype
    INTEGER, INTENT(OUT) :: count
    INTEGER, OPTIONAL, INTENT(OUT) :: ierror

MPI_Get_elements_x(status, datatype, count, ierror)
    TYPE(MPI_Status), INTENT(IN) :: status
    TYPE(MPI_Datatype), INTENT(IN) :: datatype
    INTEGER(KIND = MPI_COUNT_KIND), INTENT(OUT) :: count
    INTEGER, OPTIONAL, INTENT(OUT) :: ierror

🌈 INPUT PARAMETERS 🌈

status : the return status of a receive operation (that's your trusty status object, holding all the tea about what actually arrived).
datatype : the datatype that the receive operation used (a handle, bestie).

🎁 OUTPUT PARAMETERS 🎁

ierror : Fortran only — the error status, an integer. if you're in C, you get the error as the return value instead, so don't come looking for ierror there 💀

💖 DESCRIPTION 💖

okay so here's the thing that makes MPI_Get_elements and MPI_Get_elements_x different from their cousin MPI_Get_count: MPI_Get_count hands you the number of "top-level entries" that were received — like, literally the number of "copies" of the type datatype. that's it. that's the whole vibe.

MPI_Get_count can return any integer value k, where 0 =< k =< count. and here's the plot twist: if MPI_Get_count returns k, then the number of basic elements received (which is also the value that MPI_Get_elements and MPI_Get_elements_x hand back to you) is n k — as in, n times k — where n is the number of basic elements in the type map of datatype. 🧠✨

and now the messy part: if the number of basic elements received is not a multiple of n — meaning the receive operation didn't get a whole, integral number of datatype "copies" — then MPI_Get_count just returns MPI_UNDEFINED. no partial credit, no notes, just MPI_UNDEFINED. 😭

for BOTH functions: if the count parameter can't even express the value that needs to come back (say, the parameter is too small to hold the output value), it gets set to MPI_UNDEFINED. so yeah, watch your sizes bestie.

🍓 Example: usage of `MPI_Get_count` and `MPI_Get_elements`

call MPI_TYPE_CONTIGUOUS(2, MPI_REAL, Type2, ierr)
call MPI_TYPE_COMMIT(Type2, ierr)
call MPI_COMM_RANK(comm, rank, ierr)

IF ( rank == 0 ) THEN
   CALL MPI_SEND(a, 2, MPI_REAL, 1, 0, comm, ierr)
   CALL MPI_SEND(a, 3, MPI_REAL, 1, 0, comm, ierr)
ELSE
   CALL MPI_RECV(a, 2, Type2, 0, 0, comm, stat, ierr)
   CALL MPI_GET_COUNT(stat, Type2, i, ierr) ! returns i=1
   CALL MPI_GET_ELEMENTS(stat, Type2, i, ierr) ! returns i=2
   CALL MPI_RECV(a, 2, Type2, 0, 0, comm, stat, ierr)
   CALL MPI_GET_COUNT(stat, Type2, i, ierr) ! returns i=MPI_UNDEFINED
   CALL MPI_GET_ELEMENTS(stat, Type2, i, ierr)  ! returns i=3
END IF

see how the two functions tell two different stories? MPI_Get_count is counting copies, MPI_Get_elements is counting the actual little elements inside. main character energy from both of them honestly.

bonus lore: MPI_Get_elements can also be used after a probe to find out how many elements are in the probed message. 🕵️‍♀️

and one more thing — MPI_Get_count and MPI_Get_elements return the same values when you use them with primitive data types. so if that's your situation, they're twins. periodt.

💀 ERRORS 💀

almost every MPI routine returns an error value. C routines give it back as the return value of the function, and Fortran routines put it in the last argument. slay.

before that error value gets returned, the current MPI error handler associated with the communication object (like a communicator, window, or file) gets called. and if there's no communication object associated with the MPI call, then the call counts as attached to MPI_COMM_SELF and it'll call the associated MPI error handler. 👀

when MPI_COMM_SELF is not initialized (i.e., 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 using the World model, or
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 the MPI_ERRORS_RETURN error handler gets called for MPI I/O functions, and the MPI_ERRORS_ABORT error handler gets called for all other MPI functions. 😌

🌟 Open MPI's three predefined error handlers 🌟

MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. yes, all of them. bye. 💀
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.
MPI_ERRORS_RETURN — returns an error code to the application. the chill one. 🫶

🎀 DIY error handlers 🎀

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. like, that's not a vibe, that's a real warning. ⚠️

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_Get_count

💜 Copyright 💜

2003-2026, The Open MPI Community.

and that's the whole page bestie!! you ate that 🍽️✨ this beauty is from the Open MPI manual, dated Sep 10, 2026 — MPI_GET_ELEMENTS_X(3), forever iconic, no cap 💅🎀🦋🌸👑

📦 where this page comes from

ubuntu stonking: openmpi-doc 5.0.10-6 · other
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

MPI_GET_ELEMENTS_X(3)