XMPI_Buoy(3)

💖 XMPI_Buoy(3) — the LAM/MPI manual, but make it make sense 💖

okay bestie, so this is a page from the LAM/MPI manual set, and today's main character is XMPI_Buoy. it's giving very niche, very powerful, very "only LAM/MPI gets it". let's go 🦋

---

✨ NAME ✨

XMPI_Buoy — a LAM/MPI-specific function that drops a buoy into the XMPI trace stream. yes literally, you're leaving little floaty markers in your trace. iconic behavior honestly 🎀

---

✨ SYNOPSIS ✨

#include <mpi.h>
int
XMPI_Buoy(const char* name)

---

✨ INPUT PARAMETER ✨

• name — the buoy name, and it's a string. that's it. that's the whole input. she's simple, she's elegant 💅

---

✨ NOTES ✨

so here's the tea ☕ the LAM implementation of MPI is all integrated with the XMPI run/debug viewer. it can generate tracefiles AND on-the-fly trace streams that are suitable for display in XMPI. two for one, no cap.

and a new functionality in XMPI is the ability to view "buoys" in the trace stream — which is genuinely so helpful for marking particular sections of your code. like little sticky notes but for your timeline. LAM/MPI lets you drop those buoys with the XMPI_Buoy function.

calling XMPI_Buoy with a string will drop a buoy of that name in the trace stream (only if tracing is enabled, bestie — otherwise it's not happening). dropping a buoy is a local action; the call returns immediately. and the buoy gets dropped into the trace stream of the local rank, so it'll show up on the corresponding rank timeline in XMPI. ✨

okay important detail: the name can be a maximum of 32 characters long. longer than that? it gets truncated. she will not fit, she will be shortened. 💀

if you invoke this function and tracing isn't active, the buoy is just... ignored. it simply did not happen. 🙈

ngl there is no profiling version of this function. don't go looking for one, she doesn't exist.

this is a LAM/MPI-specific function and it's intended mainly for use with XMPI. so if you're gonna use it, use it in conjunction with the LAM_MPI C preprocessor macro, like this:

#if LAM_MPI
XMPI_Buoy("my function begins");
// ... message passing code
XMPI_Buoy("my function ends");
#endif

see how cute that is? mark the beginning, mark the end, the timeline knows exactly what's going on. main character energy fr fr 👑

---

✨ NOTES FOR FORTRAN ✨

okay Fortran besties, this one's for you 🫶

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.

also, all MPI objects (e.g., MPI_Datatype, MPI_Comm) are of type INTEGER in Fortran. that's just how it is over there. 💜

---

✨ ERRORS ✨

if an error occurs in an MPI function, the current MPI error handler is called to handle it. and by default, that error handler aborts the MPI job. yes, like, full stop, game over. 😭

the error handler may be changed with MPI_Errhandler_set; the predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned (in C and Fortran; this error handler is less useful with the C++ MPI bindings. the predefined error handler MPI::ERRORS_THROW_EXCEPTIONS should be used in C++ if the error value needs to be recovered). and note that MPI does not guarantee that an MPI program can continue past an error. so like... be careful bestie.

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. the C++ bindings for MPI do not return error values; instead, error values are communicated by throwing exceptions of type MPI::Exception (but not by default). exceptions are only thrown if the error value is not MPI::SUCCESS.

and note that if the MPI::ERRORS_RETURN handler is set in C++, while MPI functions will return upon an error, there will be no way to recover what the actual error value was. it's giving lost information. 💀

here are the error codes, one by one, no skipping:

• MPI_SUCCESS — no error; the MPI routine completed successfully. slay ✨
• MPI_ERR_ARG — invalid argument. some argument is invalid and is not identified by a specific error class. this is typically a NULL pointer or other such error. check ur pointers bestie.
• MPI_ERR_INTERN — an internal error has been detected. this one is fatal. please send a bug report to the LAM mailing list (see http://www.lam-mpi.org/contact.php). like genuinely, they want to know. 🙏

---

✨ SEE ALSO ✨

• XMPI_Coloron
• XMPI_Coloroff

go read those next, they're the sibling icons of this whole buoy situation. iykyk 🌈

---

✨ LOCATION ✨

xbuoy.c — that's where she lives. 🏠

---

and that's the whole page, bestie!! this one came from the LAM/MPI 7.1.4 era, dated 6/24/2006, so yeah she's vintage but she still eats. go drop some buoys, mark your code sections, and let the XMPI timeline tell your story. periodt. 💖✨🎀