OMPI_AFFINITY_STR(3)

📦

version 5.0.10 · 7 versions

💖 `OMPI_Affinity_str` — the Open MPI page, bestie edition 💖

okay so you found the OMPI_AFFINITY_STR(3) page in the Open MPI manual, and honestly? you're about to find out exactly which CPU got stuck with your process. this is the one that gives you prettyprint strings of processor affinity information for this process. no cap, that's literally what it does: OMPI_Affinity_str — obtain prettyprint strings of processor affinity information for this process. 🌸

✨ SYNTAX ✨

🧚 C Syntax

#include <mpi.h>
#include <mpi-ext.h>

int OMPI_Affinity_str(ompi_affinity_fmt_type_t fmt_type,
                      char ompi_bound[OMPI_AFFINITY_STRING_MAX],
                      char current_binding[OMPI_AFFINITY_STRING_MAX],
                      char exists[OMPI_AFFINITY_STRING_MAX])

😭 Fortran Syntax

There is no Fortran binding for this function. bestie. i'm so sorry. 💀

😭 Fortran 2008 Syntax

There is no Fortran 2008 binding for this function. still no. 🫶

😭 C++ Syntax

There is no C++ binding for this function. yeah. C only, i fear. 🙈

🎀 INPUT PARAMETERS 🎀

fmt_type — an enum that tells the function how to format the ompi_bound and current_binding strings it hands back. and the options are lowkey cute:
- OMPI_AFFINITY_RSRC_STRING_FMT — returns the string as human-readable resource names, like "socket 0, core 0". very demure, very mindful. ✨
- OMPI_AFFINITY_LAYOUT_FMT — returns ASCII art showing where this MPI process is bound relative to the machine resource layout. for example, "[. B][. .]" means the process that called the routine is bound to socket 0, core 1, on a system with 2 sockets, each of which contains 2 cores. art. it's giving gallery. 🖼️
- See below for more output examples. 👀

🌈 OUTPUT PARAMETERS 🌈

ompi_bound — a prettyprint string describing what processor(s) Open MPI bound this process to — or a string telling you Open MPI did not bind this process at all. mixed signals but ok. 💅
current_binding — a prettyprint string describing what processor(s) this process is currently bound to — or a string saying the process is bound to all available processors (which means it's considered “unbound”). we love a free spirit. 🦋
exists — a prettyprint string describing the available sockets and sockets on this host. (yes, it really says "sockets and sockets" — iconic typo energy, we're keeping it fr fr 🍓)

👑 DESCRIPTION 👑

Open MPI may bind a process to specific sockets and/or cores at process launch time. this here is a non-standard Open MPI function call, and it returns prettyprint info about three things:

Where Open MPI bound this process. the string that lands in ompi_bound will either say that Open MPI did not bind this process to anything, or it'll contain a prettyprint description of the processor(s) that Open MPI bound this process to. simple as that. ✨
Where this process is currently bound. regardless of whether Open MPI bound this process or not — plot twist — another entity may have bound it. the string in current_binding tells you the current binding of this process, no matter what Open MPI did earlier. it'll either say the process is unbound (meaning it's bound to all available processors) or it'll hand you a prettyprint description of the sockets and cores this process is currently bound to. drama. 🎭
What processors exist. as a lil convenience for you, the exists string contains a prettyprint description of the sockets and cores this process can see — which is usually all the processors in the system. the whole vibe. 🌍

🍓 EXAMPLES 🍓

Example 1: Print out processes binding using resource string format. 🎀

int rank;
char ompi_bound[OMPI_AFFINITY_STRING_MAX];
char current_binding[OMPI_AFFINITY_STRING_MAX];
char exists[OMPI_AFFINITY_STRING_MAX];

MPI_Init(&argc, &argv);
MPI_Comm_rank(MPI_COMM_WORLD, &rank);

OMPI_Affinity_str(OMPI_AFFINITY_RSRC_STRING_FMT,
                  ompi_bound, current_binding, exists);
printf("rank %d: \n"
       "       ompi_bound: %s\n"
       "  current_binding: %s\n"
       "           exists: %s\n",
       rank, ompi_bound, current_binding, exists);
...

Output of mpirun -n 2 -bind-to-core a.out:

rank 0:
       ompi_bound: socket 0[core 0]
  current_binding: socket 0[core 0]
           exists: socket 0 has 4 cores
rank 1:
       ompi_bound: socket 0[core 1]
  current_binding: socket 0[core 1]
           exists: socket 0 has 4 cores

Output of mpirun -n 2 -bind-to-socket a.out:

rank 0:
       ompi_bound: socket 0[core 0-3]
  current_binding: Not bound (or bound to all available processors)
           exists: socket 0 has 4 cores
rank 1:
       ompi_bound: socket 0[core 0-3]
  current_binding: Not bound (or bound to all available processors)
           exists: socket 0 has 4 cores

Example 2: Print out processes binding using layout string format. 🖼️

int rank;
char ompi_bound[OMPI_AFFINITY_STRING_MAX];
char current_binding[OMPI_AFFINITY_STRING_MAX];
char exists[OMPI_AFFINITY_STRING_MAX];

MPI_Init(&argc, &argv);
MPI_Comm_rank(MPI_COMM_WORLD, &rank);

OMPI_Affinity_str(OMPI_AFFINITY_LAYOUT_FMT,
                  ompi_bound, current_binding, exists);
printf("rank %d: \n"
       "       ompi_bound: %s\n"
       "  current_binding: %s\n"
       "           exists: %s\n",
       rank, ompi_bound, current_binding, exists);
...