MPI_TEST_CANCELLED(3)

💖 MPI_TEST_CANCELLED 💖

okay bestie, welcome to MPI_TEST_CANCELLED — this one's a little Open MPI page and it's here to answer exactly one deeply dramatic question: was this request canceled, or not? 👑

---

✨ SYNTAX ✨

🎀 C Syntax

#include <mpi.h>

int MPI_Test_cancelled(const MPI_Status *status, int *flag)

🎀 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_TEST_CANCELLED(STATUS, FLAG, IERROR)
     LOGICAL FLAG
     INTEGER STATUS(MPI_STATUS_SIZE), IERROR

🎀 Fortran 2008 Syntax

USE mpi_f08
MPI_Test_cancelled(status, flag, ierror)
     TYPE(MPI_Status), INTENT(IN) :: status
     LOGICAL, INTENT(OUT) :: flag
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

🌸 INPUT PARAMETER 🌸

• status — the status object, as in, the whole point (status). 🫶

---

💜 OUTPUT PARAMETERS 💜

• flag — true if the operation was cancelled (a logical, so it's a yes/no vibe).
• ierror — Fortran only, bestie: the error status, and it's an integer.

---

🌈 DESCRIPTION 🌈

So here's the tea. This one returns flag = true if the communication tied to that status object was canceled successfully. 🎉 And in that case? Lowkey every other field of status — count, tag, the whole friend group — is undefined. Nothing to see there, don't go looking. 🙈

Otherwise it returns flag = false, periodt.

And the actual pro-tip that lives in this manpage: if a receive operation might get canceled, you should call MPI_Test_cancelled first to check whether the cancel actually went through, and only then go poking at the other fields of the return status. Order matters, bestie!! ✨

---

🦋 NOTES 🦋

Cancel can be an expensive operation, so use it only exceptionally. It's giving ✨special occasion✨, not everyday fit. 💅

---

💀 ERRORS 💀

Almost all MPI routines return an error value — C routines give it back as the return result of the function (return), and Fortran routines drop it in the last argument. Okay so:

Before that error value comes back, the current MPI error handler associated with the communication object (think: communicator, window, file) gets called. 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 error handler associated with that instead. And when MPI_COMM_SELF isn't initialized — meaning 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. 😭

That initial error handler is changeable:

• Call MPI_Comm_set_errhandler on MPI_COMM_SELF when you're in the World model, or
• Use the mpi_initial_errhandler CLI argument to mpiexec, or the info key to MPI_Comm_spawn / MPI_Comm_spawn_multiple.

If no other appropriate error handler has been set, then MPI_ERRORS_RETURN is what gets called for MPI I/O functions, and MPI_ERRORS_ABORT gets called for all other MPI functions.

Open MPI ships three predefined error handlers you can use, and they are:

• MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. 💀
• 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 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.
• MPI_ERRORS_RETURN — returns an error code to the application.

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

1. MPI_Comm_create_errhandler then MPI_Comm_set_errhandler
2. MPI_File_create_errhandler then MPI_File_set_errhandler
3. MPI_Session_create_errhandler then MPI_Session_set_errhandler or at MPI_Session_init
4. MPI_Win_create_errhandler then MPI_Win_set_errhandler

Heads up bestie: MPI does not guarantee that an MPI program can continue past an error. No cap. 🚨

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 info. 📚

---

👑 Copyright 👑

2003-2026, The Open MPI Community

---

and that's the whole page, bestie!! 💅✨ This lil icon was served up by the Open MPI crew, dated Sep 10, 2026, and yeah — it's stitched right into the good old MPI_TEST_CANCELLED(3) manual page. go forth and test those cancellations responsibly 🫶🌸