MPIX_COMM_REVOKE(3)

💖 MPIX_COMM_REVOKE 💖

okay bestie, welcome to MPIX_COMM_REVOKE(3) from the Open MPI manual set — this is the page where we learn how to revoke a communicator. yes, like taking away its phone privileges, except the consequence is errors being raised, at all ranks, for non-local operations on that communicator. 💅

This one is part of the User Level Fault Mitigation ULFM extension. ✨

---

✨ SYNTAX ✨

🎀 C Syntax

#include <mpi.h>
#include <mpi-ext.h>

int MPIX_Comm_revoke(MPI_Comm comm)

🎀 Fortran Syntax

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

MPIX_COMM_REVOKE(COMM, IERROR)
     INTEGER COMM, IERROR

🎀 Fortran 2008 Syntax

USE mpi_f08
USE mpi_ext_f08

MPIX_Comm_revoke(comm, ierror)
     TYPE(MPI_Comm), INTENT(IN) :: comm
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

🌸 INPUT PARAMETERS 🌸

• comm — the communicator, as a handle. that's the whole input, she's low maintenance. 👑

🌸 OUTPUT PARAMETERS 🌸

• ierror — Fortran only: the error status (an integer). C girlies get it as the return value instead.

---

💜 DESCRIPTION 💜

so what does this actually do? MPIX_Comm_revoke marks the communicator comm as revoked at all MPI processes in the groups (local and remote) that are associated with comm. the way this works is not collective, so there is no matching call required on the remote MPI processes. no group chat handshake needed, she just does it. 🦋

if you want the full lore on when a communicator becomes revoked locally and what semantics apply on a revoked communicator, go read the docs for MPIX_Comm_is_revoked — that's the deep dive. the tl;dr: once a communicator is revoked, any non-local operation raises an exception of class MPIX_ERR_REVOKED, except for select fault-tolerant operations (those are the exceptions, iykyk). 🫶

---

🌈 PROPAGATION OF THE REVOKED STATE AND ORDERING 🌈

the implementation propagates the revoked state in a fault-tolerant manner. so even with failed processes in the mix, the communicator still becomes revoked at all the non-failed MPI processes that belong to comm. iconic behavior honestly. 💖

now the ordering part, pay attention: there is no particular ordering between the revocation call at another process and the completion of operations at a local process. for example — and this is the example, keep it — a receive operation can raise an error of class MPIX_ERR_REVOKED even if the send operation procedure is called before the revoke procedure at the sender. yes. chaos. that's just how it is. 💀

---

⭐ ERRORS ⭐

almost all MPI routines return an error value. C routines give it back as the return result of the function, and Fortran routines put it in the last argument. that's the split, no cap.

before that error value comes back to you, the current MPI error handler 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 will call the associated MPI error handler for that. 📞

when MPI_COMM_SELF is not initialized — that means 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 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 is the error handler that gets called for MPI I/O functions, and MPI_ERRORS_ABORT gets called for all other MPI functions. that's the default pipeline, fr fr.

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

• MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. yeah. everybody. 😭
• 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. different vibes per object, love that for us. 🎀
• MPI_ERRORS_RETURN — returns an error code to the application. the chill one. ✨

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

• MPI_Comm_create_errhandler and then MPI_Comm_set_errhandler
• MPI_File_create_errhandler and then MPI_File_set_errhandler
• MPI_Session_create_errhandler and then MPI_Session_set_errhandler, or at MPI_Session_init
• MPI_Win_create_errhandler and 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 she's fine after an error, because she might not be. 🫣

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:

• MPIX_Comm_is_revoked
• MPIX_Comm_agree
• MPIX_Comm_shrink

---

👑 Copyright 👑

2003-2026, The Open MPI Community 💖

---

and that's the whole page bestie!! this was MPIX_COMM_REVOKE(3) from Open MPI, last touched Sep 10, 2026. go forth, revoke responsibly, and remember: non-local ops raise MPIX_ERR_REVOKED, no matching remote call needed, and you ate. 🎀💅✨🦋