MPI_COMM_IDUP(3)

📦
version 5.0.10 · 7 versions
, in ubuntu stonking

🦋 NAME 🦋

MPI_Comm_idup — okay so bestie, this one starts the nonblocking duplication of an existing communicator, and it brings all its cached information with it. Like a glow-up copy but it happens in the background, no cap ✨

(also hi, this is the Open MPI manual, section 3, and we're gonna get through it together 💖)

🎀 SYNTAX 🎀

C Syntax

#include <mpi.h>

int MPI_Comm_idup(MPI_Comm comm, MPI_Comm *newcomm, MPI_Request *request)

Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_COMM_IDUP(COMM, NEWCOMM, REQUEST, IERROR)
     INTEGER COMM, NEWCOMM, REQUEST, IERROR

Fortran 2008 Syntax

USE mpi_f08
MPI_Comm_idup(comm, newcomm, request, ierror)
     TYPE(MPI_Comm), INTENT(IN) :: comm
     TYPE(MPI_Comm), INTENT(OUT) :: newcomm
     TYPE(MPI_Request), INTENT(OUT) :: request
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

🌸 INPUT PARAMETER 🌸

  • comm — the communicator, as a handle. Your origin story, your main character 🫶

💅 OUTPUT PARAMETERS 💅

  • newcomm — a copy of comm, as a handle. The dupe. The twin. The sequel 🔥
  • request — the communication request, as a handle. Hold onto this, you need it to know when the copy's done ⌛
  • ierror — Fortran only: error status (integer). Yes only Fortran gets this one, C fends for itself 😭

⭐ DESCRIPTION ⭐

So MPI_Comm_idup starts the nonblocking duplication of an existing communicator comm, with associated key values. For each key value, the respective copy callback function decides what attribute value goes with that key in the new communicator — and one specific thing a copy callback is allowed to do is straight up delete the attribute from the new communicator. Crafty, but valid ✨

It returns in newcomm a new communicator with:

  • the same group
  • any copied cached information
  • but a brand new context 👑

(the type of context stuff is explained in the "Functionality" subsection of the "Caching" section in the "Groups, Contexts, and Communicators" chapter of the MPI Standard at https://www.mpi-forum.org/docs/, if you wanna go deep, iykyk)

🚨 Important bestie: the communicator handed back in newcomm will not be available until the request is complete. Do not pass go, do not use it early. Wait for it 💀

Wanna know when a communicator duplication request has finished? Call any of these with the request this function gave you:

  • MPI_Wait <#mpi-wait>
  • MPI_Waitany <#mpi-waitany>
  • MPI_Test <#mpi-test>
  • MPI_Testany <#mpi-testany>

Any one of those four, your choice, slay 🌈

🧚 NOTES 🧚

This operation exists so a parallel library call can get itself a duplicate communication space that has all the same properties as the original communicator. "Same properties" meaning:

And the tea is: this call is valid even if there are pending point-to-point communications involving the communicator comm. So like, mid-conversation? Still fine. Iconic 🫶

A typical usage, picture it: an MPI_Comm_idup at the very beginning of your parallel call, and an MPI_Comm_free <#mpi-comm-free> of that duplicated communicator at the end of the call. Clean. Bookended. Obsessed. Other models of communicator management are also possible, so do your thing 💅

This call applies to both intra- and intercommunicators ✨

⚠️ Now the fine print, no skipping: it is not defined by the MPI standard what happens if the attribute copy callback invokes other MPI functions. And in Open MPI specifically, it is not valid for attribute copy callbacks (or any of their children, literally anyone in the family tree) to add or delete attributes on the same object on which the attribute copy callback is being invoked. Don't do it. I'm serious. 🚫

💀 ERRORS 💀

Almost all MPI routines return an error value:

  • C routines: as the return result of the function
  • Fortran routines: in the last argument

Before the 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 it'll call the associated MPI error handler.

But when MPI_COMM_SELF is not initialized — meaning before MPI_Init <#mpi-init>/MPI_Init_thread <#mpi-init-thread>, after MPI_Finalize <#mpi-finalize>, or when you're using the Sessions Model exclusively — the error raises the initial error handler 😳

The 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
  • the mpi_initial_errhandler CLI argument to mpiexec, or
  • the info key to MPI_Comm_spawn <#mpi-comm-spawn>/MPI_Comm_spawn_multiple <#mpi-comm-spawn-multiple>

If no other appropriate error handler has been set, then:

  • the MPI_ERRORS_RETURN error handler is called for MPI I/O functions
  • the MPI_ERRORS_ABORT error handler is called for all other MPI functions

🌟 Open MPI includes three predefined error handlers that can be used 🌟

  • MPI_ERRORS_ARE_FATAL — Causes the program to abort all connected MPI processes. Everyone. All of them. 😭
  • 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 to the application. Just hands it to you and lets you deal 💅

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

  • MPI_Comm_create_errhandler <#mpi-comm-create-errhandler> then MPI_Comm_set_errhandler <#mpi-comm-set-errhandler>
  • MPI_File_create_errhandler <#mpi-file-create-errhandler> then MPI_File_set_errhandler <#mpi-file-set-errhandler>
  • MPI_Session_create_errhandler <#mpi-session-create-errhandler> 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> then MPI_Win_set_errhandler <#mpi-win-set-errhandler>
🫠 Note that MPI does not guarantee that an MPI program can continue past an error. Sometimes it's just over.

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_Comm_dup <#mpi-comm-dup>
  • MPI_Comm_dup_with_info <#mpi-comm-dup-with-info>

2003-2026, The Open MPI Community

That's the whole page bestie, you ate it 💖 This was the MPI_COMM_IDUP(3) page from Open MPI, dated Sep 10, 2026 — now go forth and duplicate responsibly 🦋✨

📦 where this page comes from