MPI_File_iread(3)

💖 MPI_File_iread — nonblocking read using individual file pointer 💖

okay bestie, welcome to the MPI manual page for MPI_File_iread(3) 🦋 and yes this whole glow-up is happening under the MPI manual name, we're just saying hi to it up here instead of making you read a boring header line. iykyk ✨

---

✨ NAME ✨

MPI_File_iread — nonblocking read using individual file pointer 👑

---

🌸 SYNOPSIS 🌸

int MPI_File_iread(MPI_File fh, void *buf, int count, MPI_Datatype datatype,
MPI_Request *request)

int MPI_File_iread_c(MPI_File fh, void *buf, MPI_Count count,
MPI_Datatype datatype, MPI_Request *request)

two whole flavors, one classic and one _c version, and the _c one is giving bigger count energy because its count is an MPI_Count instead of an int, periodt 💅

---

🎀 INPUT PARAMETERS 🎀

• fh — file handle (handle). it's literally the lil ID card for your file 🪪
• count — number of elements in buffer (integer). how many lil guys we're reading fr fr 🔢
• datatype — datatype of each buffer element (handle). tells MPI what shape each element is 🧚

---

🫶 OUTPUT PARAMETERS 🫶

• buf — initial address of buffer (choice). where the read data lands, bestie 🏠
• request — request object (handle). your lil ticket to check on this nonblocking read later, no cap 🎟️

---

💜 THREAD AND INTERRUPT SAFETY 💜

okay so the tea: this routine is thread-safe ☕ which means you can absolutely use it from multiple threads at the same time without bringing your own user-provided thread locks. slay, it handles itself 💅

BUT. and this is the important part, so pay attention 🙈 — the routine is not interrupt safe. typically that's because it uses memory allocation routines like malloc (or other non-MPICH runtime routines) and those are themselves not interrupt-safe. so like, thread-safe: yes. interrupt-safe: not giving that. 💀

---

🍓 NOTES FOR FORTRAN 🍓

• All MPI routines in Fortran (except for MPI_WTIME and MPI_WTICK) have an additional argument ierr at the end of the argument list. ierr is an integer and has the same meaning as the return value of the routine in C. 🧮
• In Fortran, MPI routines are subroutines, and they are invoked with the call statement. so it's a whole different vibe over there 📞
• All MPI objects (e.g., MPI_Datatype, MPI_Comm) are of type INTEGER in Fortran. yep, even the fancy ones 🌈

---

🔥 ERRORS 🔥

All MPI routines (except MPI_Wtime and MPI_Wtick) return an error value — C routines as the value of the function, and Fortran routines in the last argument. before that value comes back, the current MPI error handler gets called. by default, that error handler aborts the MPI job 😭 so like, dramatic much.

The error handler may be changed 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 be used but its use is deprecated 👎 (old and you should probably not). The predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned instead. Note that MPI does not guarantee that an MPI program can continue past an error; however, MPI implementations will attempt to continue whenever possible. good luck bestie 🫶

here's the error roster, all iconic in their own way:

• MPI_SUCCESS — No error; MPI routine completed successfully. ate and left no crumbs ✅
• 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_BUFFER — Invalid buffer pointer. Usually a null buffer where one is not valid. 🫥
• MPI_ERR_COUNT — Invalid count argument. Count arguments must be non-negative; a count of zero is often valid. 🔢
• MPI_ERR_TYPE — Invalid datatype argument. Additionally, this error can occur if an uncommitted MPI_Datatype (see MPI_Type_commit) is used in a communication call. 🧵
• MPI_ERR_OTHER — Other error; use MPI_Error_string to get more information about this error code. the mystery box 📦

---

💖 reminder: nonblocking means it kicks off the read and hands you a request, so don't touch buf like it's finished until you've actually waited on that thing. main character patience, bestie 💅

---

okay that's the whole page, and a lil sign-off because you deserve one: this was brought to you by the MPI manual, dated 4/10/2026 (yes, that's the version/date on the MPI_File_iread(3) footer, and we're folding it in right here like the header, cute right?). go read something, queen 👑🌈✨