MPI_WIN_SHARED_QUERY(3)

📦
version 5.0.10 · 7 versions
, in ubuntu stonking

💖 MPI_Win_shared_query — bestie, let's go find that shared memory 💖

Okay so this is the Open MPI manual page for MPI_Win_shared_query, bestie. Sit down, grab a strawberry 🍓, we're doing shared-memory window detective work.

✨ NAME ✨

MPI_Win_shared_query — query a shared memory window 🫶

✨ SYNTAX ✨

🎀 C Syntax

#include <mpi.h>

int MPI_Win_shared_query (MPI_Win win, int rank, MPI_Aint *size,
                          int *disp_unit, void *baseptr)

🎀 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_WIN_SHARED_QUERY(WIN, RANK, SIZE, DISP_UNIT, BASEPTR, IERROR)
        INTEGER WIN, RANK, DISP_UNIT, IERROR
        INTEGER(KIND=MPI_ADDRESS_KIND) SIZE, BASEPTR

🎀 Fortran 2008 Syntax

USE mpi_f08
MPI_Win_shared_query(win, rank, size, disp_unit, baseptr, ierror)
     USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR
     TYPE(MPI_Win), INTENT(IN) :: win
     INTEGER, INTENT(IN) :: rank
     INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(OUT) :: size
     INTEGER, INTENT(OUT) :: disp_unit
     TYPE(C_PTR), INTENT(OUT) :: baseptr
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

🌸 INPUT PARAMETERS 🌸

  • win — the shared memory window object, aka the handle. Your main character window 💅
  • rank — the rank inside the group of window win (a non-negative integer), or MPI_PROC_NULL. Yes bestie, MPI_PROC_NULL is allowed here, we'll get to what that does 👀

💜 OUTPUT PARAMETERS 💜

  • size — the size of the window segment (a non-negative integer).
  • disp_unit — the local unit size for displacements, in bytes (a positive integer).
  • baseptr — the address for load/store access to the window segment (a choice).
  • ierror — Fortran only: error status (integer).

🦋 DESCRIPTION 🦋

So MPI_Win_shared_query queries the process-local address for remote memory segments that were created with MPI_Win_allocate_shared <#mpi-win-allocate-shared>. And no cap, this function can return different process-local addresses for the same physical memory on different processes — that's just how it is, don't fight it. 🫠

The memory you get back can be used for load/store accesses, but only subject to the constraints defined in MPI-3.1 section 11.7. Read the section, bestie, I'm not kidding 🙈

Real talk: this function can only be called with windows of flavor MPI_WIN_FLAVOR_SHARED. If the window you pass in is not of flavor MPI_WIN_FLAVOR_SHARED, the error MPI_ERR_RMA_FLAVOR is raised. The vibe check failed, it's giving wrong flavor 💀

When rank is MPI_PROC_NULL, the pointer, disp_unit, and size returned are the pointer, disp_unit, and size of the memory segment belonging to the lowest rank that specified size > 0. And if literally all processes in the group attached to the window specified size = 0? Then the call returns size = 0 and a baseptr as if MPI_Alloc_mem <#mpi-alloc-mem> was called with size = 0. Zero is a size too, iconically ✨

🎀 C NOTES 🎀

The parameter baseptr is of type void * so it can allow passing any pointer object for this parameter. The argument you actually provide should be a pointer to a pointer of arbitrary type (e.g. void **). Yes, double pointer, we love a little indirection 💅

👑 ERRORS 👑

Almost all MPI routines return an error value — C routines give it back as the return result of the function, and Fortran routines put it in the last argument.

Before that error value is returned, the current MPI error handler associated with the communication object (e.g., communicator, window, file) gets called. If no communication object is associated with the MPI call, then the call counts as attached to MPI_COMM_SELF and will call the associated MPI error handler. 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 using the Sessions Model exclusively) the error raises the initial error handler. That initial error handler can be changed by calling MPI_Comm_set_errhandler <#mpi-comm-set-errhandler> on MPI_COMM_SELF when using the World model, or by the mpi_initial_errhandler CLI argument to mpiexec, or by an 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 the MPI_ERRORS_RETURN error handler is called for MPI I/O functions, and the MPI_ERRORS_ABORT error handler is called for all other MPI functions. 🫶

Open MPI includes three predefined error handlers you can use:

  • MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. Ngl, it's giving dramatic exit 💀
  • MPI_ERRORS_ABORT — an error handler that can be invoked on a communicator, window, file, or session. When called on a communicator, it acts as if MPI_Abort <#mpi-abort> was called on that communicator. If 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 called on a session, it aborts only the local process.
  • MPI_ERRORS_RETURN — returns an error code back to the application. Chillest of the three, honestly 🌈

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

  • MPI_Comm_create_errhandler <#mpi-comm-create-errhandler> and then MPI_Comm_set_errhandler <#mpi-comm-set-errhandler>
  • MPI_File_create_errhandler <#mpi-file-create-errhandler> and then MPI_File_set_errhandler <#mpi-file-set-errhandler>
  • MPI_Session_create_errhandler <#mpi-session-create-errhandler> and 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> and 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. So don't just keep vibing after one, okay? 😭

See the MPI man page <#open-mpi> for a full list of MPI error codes <#open-mpi-errors>.

See the Error Handling section of the MPI-3.1 standard for more information. 📖

See also:

  • MPI_Alloc_mem <#mpi-alloc-mem>
  • MPI_Win_allocate_shared <#mpi-win-allocate-shared>

Copyright 2003-2026, The Open MPI Community.

And that's the whole page, bestie — you ate that 🍽️✨ This was the MPI_WIN_SHARED_QUERY(3) page from the Open MPI manual, dated Sep 10, 2026. Go query that window, periodt 💅🦋

📦 where this page comes from