MPIX_Stream_comm_create_multiplex(3)

💖 MPIX_Stream_comm_create_multiplex 💖

okay bestie, welcome to the MPI manual, page MPIX_Stream_comm_create_multiplex(3). yes the name is a mouthful, we don't make the rules, we just slay them. this one is all about making a brand new communicator with multiple local streams attached to it. multiple. streams. attached. the way that this is literally the group-chat-of-communicators function. 🦋

---

✨ NAME ✨

MPIX_Stream_comm_create_multiplex — Create a new communicator with multiple local streams attached 💅

---

✨ SYNOPSIS ✨

int MPIX_Stream_comm_create_multiplex(MPI_Comm comm, int count,
MPIX_Stream array_of_streams[],
MPI_Comm *newcomm)

---

🌸 INPUT PARAMETERS 🌸

• comm — communicator (handle). it's the squad you're starting from, the og vibe. 🫶
• count — list length (non-negative integer). non-negative, bestie, we're not doing negative lengths in this house.
• array_of_streams — stream object array (handle). yes it's an array, yes every single one gets attached, that's the whole point of the "multiplex" in the name. 💅

---

🎀 OUTPUT PARAMETERS 🎀

• newcomm — new stream-associated communicator (handle). this is the glow-up communicator, freshly made, streams included. ✨

---

🔥 THREAD AND INTERRUPT SAFETY 🔥

bestie this routine is thread-safe — which means multiple threads can use it at the same time with zero user-provided thread locks needed. no mutex, no stress, just vibes. 😌

But. and this is the important but — the routine is not interrupt safe. typically this is because of memory allocation routines like malloc or other non-MPICH runtime routines that are themselves not interrupt-safe. so like, threads? yes. interrupts? absolutely not, do not @ me. 💀

---

🌈 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're invoked with the call statement. iconic behavior honestly.
• All MPI objects (e.g., MPI_Datatype, MPI_Comm) are of type INTEGER in Fortran. yes, even the ones that feel fancy. 💜

---

💀 ERRORS 💀

so every MPI routine (except MPI_Wtime and MPI_Wtick) returns an error value — C routines as the value of the function, and Fortran routines in that last argument. before the value comes back to you, the current MPI error handler gets called. by default, this error handler aborts the MPI job. like, the whole thing. gone. 😭

the error handler can be changed with MPI_Comm_set_errhandler (for communicators), MPI_File_set_errhandler (for files), and MPI_Win_set_errhandler (for RMA windows). the MPI-1 routine MPI_Errhandler_set may be used but its use is deprecated — do not, ngl, it's giving legacy. the predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned instead.

and note: MPI does not guarantee that an MPI program can continue past an error; however, MPI implementations will attempt to continue whenever possible. optimistic of them, honestly. 🫶

here are the error codes, one bullet each, no skips:

• MPI_SUCCESS — No error; MPI routine completed successfully. ate. 👑
• 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_COMM — Invalid communicator. A common error is to use a null communicator in a call (not even allowed in MPI_Comm_rank). fr fr, don't do it.
• MPI_ERR_COUNT — Invalid count argument. Count arguments must be non-negative; a count of zero is often valid.
• MPI_ERR_OTHER — Other error; use MPI_Error_string to get more information about this error code.

---

ok final vibe check: thread-safe ✅, interrupt safe ❌, default error handler will end your whole job ✅✅✅. be normal about it. 🍓

---

anyway bestie that's the whole page, from the MPI source dated 4/10/202 — that's the version and date right there, dropping it in like a little signature at the bottom because that's what icons do. hope this helped, ily, go make some multiplexed communicators. 🧚💖🌸