MPI_TYPE_FREE(3)

💖 MPI_TYPE_FREE 💖

okay so quick vibe check: this whole page is MPI_TYPE_FREE(3) from the Open MPI crew 🫶 — the manual page that tells you how to yeet a datatype into the void. Let's get into it bestie ✨

🌸 NAME 🌸

MPI_Type_free — frees a data type. bye boo 👋💅

---

🎀 SYNTAX 🎀

✨ C Syntax ✨

#include <mpi.h>

int MPI_Type_free(MPI_Datatype *datatype)

✨ Fortran Syntax ✨

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_TYPE_FREE(DATATYPE, IERROR)
     INTEGER DATATYPE, IERROR

✨ Fortran 2008 Syntax ✨

USE mpi_f08
MPI_Type_free(datatype, ierror)
     TYPE(MPI_Datatype), INTENT(INOUT) :: datatype
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

🦋 INPUT/OUTPUT PARAMETER 🦋

• datatype — the datatype getting freed (it's a handle, babes). 💀➡️✨

🦋 OUTPUT PARAMETER 🦋

• ierror — Fortran only, bestie: the error status (an integer). 🍓

---

👑 DESCRIPTION 👑

So what actually happens? The datatype object chillin' behind datatype gets marked for de-allocation, and then datatype gets set to MPI_DATATYPE_NULL. Periodt. 💅

And the tea ☕: any communication that's currently using this datatype? It'll complete normally, no drama, no cap. And derived datatypes that were defined from the freed datatype? They are not affected. They're fine, they're thriving, they're living their best life 🦋.

Freeing a datatype does not affect any other datatype that was built from the freed one. The system behaves as if the input datatype arguments to derived datatype constructors are passed by value. literally iconic behavior tbh.

---

🔥 ERRORS 🔥

Okay so almost all MPI routines return an error value — C routines as the return result of the function itself, and Fortran routines in that last argument. iykyk 😭

Before the 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 attached to the MPI call? Then the call is considered attached to MPI_COMM_SELF and it'll call the associated MPI error handler. But 💀 — when MPI_COMM_SELF is not initialized (i.e., before MPI_Init (#mpi-init) / MPI_Init_thread (#mpi-init-thread), after MPI_Finalize (#mpi-finalize), or when you're using the Sessions Model exclusively), the error raises the initial error handler instead.

That initial error handler can be changed by calling MPI_Comm_set_errhandler (#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) / MPI_Comm_spawn_multiple (#mpi-comm-spawn-multiple). And if no other appropriate error handler has been set, then MPI_ERRORS_RETURN is the one called for MPI I/O functions, while MPI_ERRORS_ABORT gets called for all other MPI functions.

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

• MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. dramatic, honestly 💀
• 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 (#mpi-abort) was called on that communicator. If it's called on a window or file, it acts as if MPI_Abort (#mpi-abort) was called on a communicator containing the group of processes in the corresponding window or file. If it's called on a session, it aborts only the local process. subtle. we love range 💅
• MPI_ERRORS_RETURN — returns an error code to the application. the polite one 🫶

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

• MPI_Comm_create_errhandler (#mpi-comm-create-errhandler) then MPI_Comm_set_errhandler (#mpi-comm-set-errhandler)
• MPI_File_create_errhandler (#mpi-file-create-errhandler) then MPI_File_set_errhandler (#mpi-file-set-errhandler)
• MPI_Session_create_errhandler (#mpi-session-create-errhandler) then MPI_Session_set_errhandler (#mpi-session-set-errhandler), or at MPI_Session_init (#mpi-session-init)
• MPI_Win_create_errhandler (#mpi-win-create-errhandler) then MPI_Win_set_errhandler (#mpi-win-set-errhandler)

⚠️ heads up bestie: MPI does not guarantee that an MPI program can continue past an error. read that again. fr fr. 😭

Peep the MPI man page (#open-mpi) for a full list of MPI error codes (#open-mpi-errors), and check the Error Handling section of the MPI-3.1 standard for even more info. 📚

---

🌈 Copyright 🌈

2003-2026, The Open MPI Community 🫶👑

---

and that's the whole page bestie, we ate 💅✨ Open MPI babes, dated Sep 10, 2026 — go forth and free your datatypes responsibly 🎀💖