The previously described window creation procedures require the user to identify the local memory that may be a target of RMA calls at the time the window is created. This has advantages for both the programmer (only this memory can be updated by one-sided operations and provides greater safety) and the MPI implementation (special steps may be taken to make one-sided access to such memory more efficient). However, consider implementing a modifiable linked list using RMA operations; as new items are added to the list, memory must be allocated. In a C or C++ program, this memory is typically allocated using malloc or new respectively. With the previously described window creation procedures, the programmer must create a window with a predefined amount of memory and then implement routines for allocating memory from within the window's memory. In addition, there is no easy way to handle the situation where the predefined amount of memory turns out to be inadequate. To support this model, the routine MPI_WIN_CREATE_DYNAMIC creates a window that makes it possible to expose memory without remote synchronization. It must be used in combination with the local routines MPI_WIN_ATTACH and MPI_WIN_DETACH.
| MPI_WIN_CREATE_DYNAMIC(info, comm, win) | |
| IN info | info argument (handle) |
| IN comm | intra-communicator (handle) |
| OUT win | window object (handle) |
This procedure is collective over the group of comm. It returns a window win without memory attached. Existing MPI process memory can be attached as described below. This procedure returns a handle to a new window that can be used by MPI processes in the group of comm to perform RMA operations on attached memory. Because this window has special properties, it will sometimes be referred to as a dynamic window.
The info argument can be used to specify hints similar to the info argument for MPI_WIN_CREATE.
In the case of a window created with MPI_WIN_CREATE_DYNAMIC, the target_disp for all RMA functions is the address at the target; i.e., the effective window_base is MPI_BOTTOM and the disp_unit is one. For dynamic windows, the target_disp argument to RMA communication operations is not restricted to nonnegative values. Users should use MPI_GET_ADDRESS at the target process to determine the address of a target memory location and communicate this address to the origin process.
Advice to users.
Users are cautioned that displacement arithmetic can overflow in
variables of type MPI_Aint and result in unexpected values on some
platforms.
The MPI_AINT_ADD and MPI_AINT_DIFF
functions can be used to safely perform address arithmetic with MPI_Aint
displacements.
( End of advice to users.)
Advice
to implementors.
In environments with heterogeneous data representations, care must be
exercised in communicating addresses between MPI processes. For example, it
is possible that an address valid at the target MPI process (for example, a
64-bit pointer) cannot be expressed as an address at the origin (for
example, the origin uses 32-bit pointers). For this reason, a portable
MPI implementation should ensure that the type MPI_AINT
(see Table 4) is able to store addresses
from any MPI process.
( End of advice to implementors.)
Memory at the target cannot be accessed with this window until that memory
has been
attached using the function MPI_WIN_ATTACH.
That is, in addition to using MPI_WIN_CREATE_DYNAMIC to
create an MPI window, the user must use MPI_WIN_ATTACH
before any local memory may be the target of an MPI RMA operation.
Only memory that is currently accessible may be attached.
| MPI_WIN_ATTACH(win, base, size) | |
| IN win | window object (handle) |
| IN base | initial address of memory to be attached (choice) |
| IN size | size of memory to be attached in bytes (non-negative integer) |
Attaches a local memory region beginning at base for remote access within the given window. The memory region specified must not contain any part that is already attached to the window win, that is, attaching overlapping memory concurrently within the same window is erroneous. The argument win must be a window that was created with MPI_WIN_CREATE_DYNAMIC. The local memory region attached to the window consists of size bytes, starting at address base. In C, base is the starting address of a memory region. In Fortran, one can pass the first element of a memory region or a whole array, which must be `simply contiguous' (for `simply contiguous,' see Section Problems Due to Data Copying and Sequence Association with Subscript Triplets). Multiple (but nonoverlapping) memory regions may be attached to the same window.
Rationale.
Requiring that memory be explicitly attached before it is exposed to
one-sided access by other MPI processes can
simplify
implementations and improve performance. The ability to make memory
available for RMA operations without requiring a collective
MPI_WIN_CREATE call is needed for some one-sided programming
models.
( End of rationale.)
Advice to users.
Attaching memory to a window may require the use of scarce resources; thus, attaching large regions of memory is not recommended in portable programs. Attaching memory to a window may fail if sufficient resources are not available; this is similar to the behavior of MPI_ALLOC_MEM.
The user is also responsible for ensuring that MPI_WIN_ATTACH at the target has returned before an MPI process attempts to target that memory with an MPI RMA operation.
Performing an RMA operation on memory that has not been attached to
a window created with MPI_WIN_CREATE_DYNAMIC is
erroneous. ( End of advice to users.)
Advice
to implementors.
A high-quality implementation will attempt to make as much memory
available for attaching as possible. Any limitations should be
documented by the implementor.
( End of advice to implementors.)
MPI_WIN_ATTACH is a local procedure that is not collective.
Memory may be detached with the procedure
MPI_WIN_DETACH. After memory has been
detached, it may not be the target of an MPI RMA operation on
that window (unless the
memory is re-attached with MPI_WIN_ATTACH).
| MPI_WIN_DETACH(win, base) | |
| IN win | window object (handle) |
| IN base | initial address of memory to be detached (choice) |
Detaches a previously attached memory region beginning at base. The arguments base and win must match the arguments passed to a previous call to MPI_WIN_ATTACH. MPI_WIN_DETACH is a local procedure that is not collective.
Advice to users.
Detaching memory may permit the implementation to make more
efficient use of special memory or provide memory that may be needed
by a subsequent MPI_WIN_ATTACH. Users are encouraged to
detach memory that is no longer needed.
Memory should be detached before it is freed by the user.
( End of advice to users.)
Memory becomes detached when the associated dynamic memory window is
freed, see Section Window Destruction.