openmpi/ompi/mpi/man/man3/MPI_Win_allocate_shared.3in

.\" -*- nroff -*-
.\" Copyright 2015-2016 Los Alamos National Security, LLC. All rights reserved.
.\" Copyright 2010 Cisco Systems, Inc.  All rights reserved.
.\" Copyright 2007-2008 Sun Microsystems, Inc.
.\" Copyright (c) 1996 Thinking Machines Corporation
.\" $COPYRIGHT$
.TH MPI_Win_allocate_shared 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
.SH NAME
\fBMPI_Win_allocate_shared\fP \- One-sided MPI call that allocates
shared memory and returns a window object for RMA operations.

.SH SYNTAX
.ft R
.SH C Syntax
.nf
#include <mpi.h>
int MPI_Win_allocate_shared (MPI_Aint \fIsize\fP, int \fIdisp_unit\fP, MPI_Info \fIinfo\fP,
                             MPI_Comm \fIcomm\fP, void *\fIbaseptr\fP, MPI_Win *\fIwin\fP)

.fi
.SH Fortran Syntax
.nf
USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_WIN_ALLOCATE_SHARED(\fISIZE, DISP_UNIT, INFO, COMM, BASEPTR, WIN, IERROR\fP)
	INTEGER(KIND=MPI_ADDRESS_KIND) \fISIZE, BASEPTR\fP
	INTEGER \fIDISP_UNIT, INFO, COMM, WIN, IERROR\fP

.fi
.SH Fortran 2008 Syntax
.nf
USE mpi_f08
MPI_Win_allocate_shared(\fIsize\fP, \fIdisp_unit\fP, \fIinfo\fP, \fIcomm\fP, \fIbaseptr\fP, \fIwin\fP, \fIierror\fP)
	USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR
	INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN) :: \fIsize\fP
	INTEGER, INTENT(IN) :: \fIdisp_unit\fP
	TYPE(MPI_Info), INTENT(IN) :: \fIinfo\fP
	TYPE(MPI_Comm), INTENT(IN) :: \fIcomm\fP
	TYPE(C_PTR), INTENT(OUT) :: \fIbaseptr\fP
	TYPE(MPI_Win), INTENT(OUT) :: \fIwin\fP
	INTEGER, OPTIONAL, INTENT(OUT) :: \fIierror\fP

.fi
.SH INPUT PARAMETERS
.ft R
.TP 1i
size
Size of window in bytes (nonnegative integer).
.TP 1i
disp_unit
Local unit size for displacements, in bytes (positive integer).
.TP 1i
info
Info argument (handle).
.TP 1i
comm
Communicator (handle).

.SH OUTPUT PARAMETERS
.ft R
.TP 1i
baseptr
Initial address of window.
.TP 1i
win
Window object returned by the call (handle).
.TP 1i
IERROR
Fortran only: Error status (integer).

.SH DESCRIPTION
.ft R
\fBMPI_Win_allocate_shared\fP is a collective call executed by all
processes in the group of \fIcomm\fP. On each process, it allocates
memory of at least \fIsize\fP bytes that is shared among all processes
in \fIcomm\fP, and returns a pointer to the locally allocated segment
in \fIbaseptr\fP that can be used for load/store accesses on the
calling process. The locally allocated memory can be the target of
load/store accesses by remote processes; the base pointers for other
processes can be queried using the function
\fBMPI_Win_shared_query\fP. The call also returns a window object that
can be used by all processes in \fIcomm\fP to perform RMA
operations. The \fIsize\fP argument may be different at each process
and \fIsize\fP = 0 is valid. It is the user's responsibility to ensure
that the communicator \fIcomm\fP represents a group of processes that
can create a shared memory segment that can be accessed by all
processes in the group. The discussions of rationales for
\fBMPI_Alloc_mem\fP and \fBMPI_Free_mem\fP in MPI-3.1 \[char167] 8.2
also apply to \fBMPI_Win_allocate_shared\fP; in particular, see the
rationale in MPI-3.1 \[char167] 8.2 for an explanation of the type
used for \fIbaseptr\fP. The allocated memory is contiguous across
process ranks unless the info key \fIalloc_shared_noncontig\fP is
specified. Contiguous across process ranks means that the first
address in the memory segment of process i is consecutive with the
last address in the memory segment of process i - 1. This may enable
the user to calculate remote address offsets with local information
only.
.sp
The following info keys are supported:
.ft R
.TP 1i
alloc_shared_noncontig
If not set to \fItrue\fP, the allocation strategy is to allocate
contiguous memory across process ranks. This may limit the performance
on some architectures because it does not allow the implementation to
modify the data layout (e.g., padding to reduce access latency).
.sp
.TP 1i
blocking_fence
If set to \fItrue\fP, the osc/sm component will use \fBMPI_Barrier\fP
for \fBMPI_Win_fence\fP. If set to \fIfalse\fP a condition variable
and counter will be used instead. The default value is
\fIfalse\fP. This info key is Open MPI specific.
.sp
.TP 1i
For additional supported info keys see \fBMPI_Win_create\fP.
.sp

.SH NOTES
Common choices for \fIdisp_unit\fP are 1 (no scaling), and (in C
syntax) \fIsizeof(type)\fP, for a window that consists of an array of
elements of type \fItype\fP. The later choice will allow one to use
array indices in RMA calls, and have those scaled correctly to byte
displacements, even in a heterogeneous environment.
.sp

.SH ERRORS
Almost all MPI routines return an error value; C routines as the value
of the function and Fortran routines in the last argument.
.sp
Before the error value is returned, the current MPI error handler is
called. By default, this error handler aborts the MPI job, except for
I/O function errors. The error handler may be changed with
MPI_Comm_set_errhandler; the predefined error handler
MPI_ERRORS_RETURN may be used to cause error values to be
returned. Note that MPI does not guarantee that an MPI program can
continue past an error.

.SH SEE ALSO
.ft R
.sp
MPI_Alloc_mem
MPI_Free_mem
MPI_Win_allocate
MPI_Win_create
MPI_Win_shared_query