MPI_MPROBE(3)

💖 MPI_Mprobe — the blocking matched probe 💖

okay bestie, we're in the Open MPI manual and today's main character is MPI_Mprobe(3). she's a blocking matched probe for a message, and honestly? she eats. let's get into it 🫶

---

✨ SYNTAX ✨

🎀 C Syntax 🎀

#include <mpi.h>

int MPI_Mprobe(int source, int tag, MPI_Comm comm,
     MPI_Message *message, MPI_Status *status)

🎀 Fortran Syntax 🎀

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_MPROBE(SOURCE, TAG, COMM, MESSAGE, STATUS, IERROR)
     INTEGER SOURCE, TAG, COMM, MESSAGE
     INTEGER STATUS(MPI_STATUS_SIZE), IERROR

🎀 Fortran 2008 Syntax 🎀

USE mpi_f08
MPI_Mprobe(source, tag, comm, message, status, ierror)
     INTEGER, INTENT(IN) :: source, tag
     TYPE(MPI_Comm), INTENT(IN) :: comm
     TYPE(MPI_Message), INTENT(OUT) :: message
     TYPE(MPI_Status) :: status
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

🌸 INPUT PARAMETERS 🌸

• source — the source rank, or MPI_ANY_SOURCE if you're feeling ✨flexible✨ (integer, bestie).
• tag — the tag value, or MPI_ANY_TAG (integer).
• comm — the communicator, obvi (handle).

---

🦋 OUTPUT PARAMETERS 🦋

• message — a message (handle). yeah it's just called "message". iconic naming, no notes.
• status — a status object (status).
• ierror — Fortran only: the error status (integer).

---

👑 DESCRIPTION 👑

so like MPI_Probe and MPI_Iprobe, right? MPI_Mprobe and MPI_Improbe let you peek at incoming messages without actually receiving them. BUT — and this is the part that's giving very much main character energy — MPI_Mprobe and MPI_Improbe give you a whole mechanism to receive the specific message that got matched, no matter what other probe or receive operations are out there trying to interrupt. it's the message. you got the message. nobody else can claim her. 💅

and that means the application can literally decide how to receive the message based on the info that came back from the probe. yes bestie, you can allocate memory for the receive buffer based on the length of the probed message. tailored. bespoke. slay. 🔥

a matching probe with MPI_PROC_NULL as source returns message = MPI_MESSAGE_NO_PROC, and the status object gives you back source = MPI_PROC_NULL, tag = MPI_ANY_TAG, and count = 0. no cap. 🫡

when MPI_Mprobe returns (from a non-MPI_PROC_NULL source, just to be clear), you can then receive that matched message by handing the message handle over to the MPI_Mrecv or MPI_Imrecv functions. that's the whole arc, bestie. ✨

---

💀 ERRORS 💀

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

before that error value comes back, 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 attached to the MPI call, then the call is considered attached to MPI_COMM_SELF and will call the associated MPI error handler. 🫶

now here's the messy part. when MPI_COMM_SELF is not initialized (aka 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
• 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. every time. fr fr.

🌈 the three predefined error handlers 🌈

Open MPI ships with three predefined error handlers you can use:

• MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. like, everyone. gone. 😭
• MPI_ERRORS_ABORT — an error handler that can be invoked on a communicator, window, file, or session. when it's called on a communicator, it acts as if MPI_Abort was called on that communicator. if it's 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. and if it's called on a session, it aborts only the local process (respectful of everyone else's vibe, honestly).
• MPI_ERRORS_RETURN — returns an error code to the application. lowkey the chill one.

🧚 roll your own, bestie 🧚

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... don't assume survivability, bestie.

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

🍓 see also 🍓

• MPI_Improbe
• MPI_Probe
• MPI_Iprobe
• MPI_Mrecv
• MPI_Imrecv
• MPI_Cancel

---

📜 Copyright 📜

2003-2026, The Open MPI Community

---

aaaand that's the whole page, bestie!! 🎀💖 this was MPI_Mprobe(3) from Open MPI, and the footer is giving Sep 10, 2026 energy. go probe something safely, ily, periodt. ✨🫶👑