.. _mpi_win_create:


MPI_Win_create
==============

.. include_body

:ref:`MPI_Win_create` |mdash| One-sided MPI call that returns a window object for
RMA operations.

.. The following file was automatically generated
.. include:: ./bindings/mpi_win_create.rst

INPUT PARAMETERS
----------------
* ``base``: Initial address of window (choice).
* ``size``: Size of window in bytes (nonnegative integer).
* ``disp_unit``: Local unit size for displacements, in bytes (positive integer).
* ``info``: Info argument (handle).
* ``comm``: Communicator (handle).

OUTPUT PARAMETERS
-----------------
* ``win``: Window object returned by the call (handle).
* ``ierror``: Fortran only: Error status (integer).

DESCRIPTION
-----------

:ref:`MPI_Win_create` is a one-sided MPI communication collective call executed
by all processes in the group of *comm*. It returns a window object that
can be used by these processes to perform RMA operations. Each process
specifies a window of existing memory that it exposes to RMA accesses by
the processes in the group of *comm*. The window consists of *size*
bytes, starting at address *base*. A process may elect to expose no
memory by specifying *size* = 0.

If the *base* value used by :ref:`MPI_Win_create` was allocated by
:ref:`MPI_Alloc_mem`, the size of the window can be no larger than the value
set by the :ref:`MPI_ALLOC_MEM` function.

The displacement unit argument is provided to facilitate address
arithmetic in RMA operations: the target displacement argument of an RMA
operation is scaled by the factor *disp_unit* specified by the target
process, at window creation.

The following info keys are supported:

no_locks
   If set to *true*, then the implementation may assume that the local
   window is never locked (by a call to :ref:`MPI_Win_lock` or
   MPI_Win_lock_all). Setting this value if only active synchronization
   may allow the implementation to enable certain optimizations.

accumulate_ordering
   By default, accumulate operations from one initiator to one target on
   the same window memory location are strictly ordered. If the info key
   accumulate_ordering is set to *none*, no ordering of accumulate
   operations guaranteed. They key can also be a comma-separated list of
   required orderings consisting of *rar*, *war*, *raw*, and *waw* for
   read-after-read, write-after-read, read-after-write, and
   write-after-write, respectively. Looser ordering constraints are
   likely to result in improved performance.

accumulate_ops
   If set to *same_op*, the implementation will assume that all
   concurrent accumulate calls to the same target address will use the
   same operation. If set to *same_op_no_op*, then the implementation
   will assume that all concurrent accumulate calls to the same target
   address will use the same operation or MPI_NO_OP. The default is
   *same_op_no_op*.

same_size
   If set to *true*, then the implementation may assume that the
   argument *size* is identical on all processes, and that all processes
   have provided this info key with the same value.

same_disp_unit
   If set to *true*, then the implementation may assume that the
   argument *disp_unit* is identical on all processes, and that all
   processes have provided this info key with the same value.


NOTES
-----

Common choices for *disp_unit* are 1 (no scaling), and (in C syntax)
*sizeof(type)*, for a window that consists of an array of elements of
type *type*. 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.

Use memory allocated by :ref:`MPI_Alloc_mem` to guarantee properly aligned
window boundaries (such as word, double-word, cache line, page frame,
and so on).


ERRORS
------

.. include:: ./ERRORS.rst

.. seealso::
   * :ref:`MPI_Alloc_mem`
   * :ref:`MPI_Free_mem`
   * :ref:`MPI_Win_allocate`
   * :ref:`MPI_Win_allocate_shared`