MPIX_Comm_create_errhandler_x(3)

💖 MPIX_Comm_create_errhandler_x(3) — the MPI girlies' handbook 💖

okay bestie, welcome to section 3 of the MPI manual 💅 today we're building a whole custom communicator errorhandler, but make it extra — because this one carries around a lil baggage called extra_state. yes, it's the ✨deluxe✨ version. let's get into it.

---

🌸 NAME 🌸

MPIX_Comm_create_errhandler_x — Creates an MPI-style communicator errorhandler with an extra_state 🎀

like, it makes you an errorhandler for a communicator, and it lets you stash your own little state object on it. it's giving main character energy fr fr.

---

✨ SYNOPSIS ✨

int MPIX_Comm_create_errhandler_x(MPIX_Comm_errhandler_function_x *comm_errhandler_fn_x,
MPIX_Destructor_function *destructor_fn,
void *extra_state,
MPI_Errhandler *errhandler)

---

🫶 INPUT PARAMETERS 🫶

• comm_errhandler_fn_x — your very own, user-defined error handling procedure, but with extra_state along for the ride (it's a function, bestie, you write it)
• destructor_fn — the callback that fires when the op gets freed (also a function)
• extra_state — the extra state (which is None, iykyk)

---

👑 OUTPUT PARAMETERS 👑

• errhandler — the MPI error handler (a handle, hold onto it)

---

🌈 THREAD AND INTERRUPT SAFETY 🌈

This routine is thread-safe. periodt. that means multiple threads can use it at the same time and you do NOT need to bring your own thread locks, no cap.

However. 😭 it is not interrupt safe. and the reason is usually that it calls memory allocation routines like malloc, or other non-MPICH runtime routines that are themselves not interrupt-safe. so like… thread-safe yes, interrupt-safe no. don't mix those up boo.

---

🧚 NOTES FOR FORTRAN 🧚

all MPI routines in Fortran (except for MPI_WTIME and MPI_WTICK) get an extra argument called ierr tacked onto the end of the argument list. ierr is an integer and it means exactly the same thing as the return value of the routine in C. and in Fortran, MPI routines are subroutines, so you invoke them with the call statement. iconic behavior tbh.

also!! all MPI objects (like MPI_Datatype, MPI_Comm) are of type INTEGER in Fortran. don't forget it, or your code will simply not slay. 💀

---

🔥 ERRORS 🔥

every MPI routine (except MPI_Wtime and MPI_Wtick) returns an error value — C routines hand it back as the function's value, Fortran routines put it in that last argument. and before the value comes back, the current MPI error handler gets called. by default, that error handler aborts the MPI job 🚨 (yes, dramatic).

you can change the error handler with:

• MPI_Comm_set_errhandler (for communicators)
• MPI_File_set_errhandler (for files)
• MPI_Win_set_errhandler (for RMA windows)

the MPI-1 routine MPI_Errhandler_set may also be used, but its use is deprecated 🙈 like, it works, but respectfully, move on.

you can also use the predefined error handler MPI_ERRORS_RETURN to make error values get returned instead of aborting. and ngl, note that MPI does not guarantee an MPI program can continue past an error — however, MPI implementations will attempt to continue whenever possible. so there's hope, but no promises. 💜

• MPI_SUCCESS — No error; MPI routine completed successfully. (we love to see it ✨)
• MPI_ERR_ARG — Invalid argument. Some argument is invalid and is not identified by a specific error class (e.g., MPI_ERR_RANK).
• MPI_ERR_OTHER — Other error; use MPI_Error_string to get more information about this error code.

---

and that's the whole page bestie, you ate that 🍓 go forth and set your errhandlers with extra_state like the icon you are 💅

much love from the MPI section 3 girlies — this was MPIX_Comm_create_errhandler_x(3), dated 4/10/2026 🦋