#include <mpi/window.hpp>

Detailed Description

template<class BaseType>
class mpi::window< BaseType >

A C++ wrapper around MPI_Win providing convenient memory window management.

This class abstracts the complexities of MPI window management, allowing processes in an MPI communicator to create and share memory regions efficiently. It supports both local buffer-based windows and dynamically allocated memory windows.

If a base pointer is not specified, the constructor will allocate memory internally.

This class follows move-only semantics and takes ownership of the wrapped MPI_Win object.

Template Parameters

BaseType The type of elements stored in the memory window.

Definition at line 57 of file window.hpp.

Inheritance diagram for mpi::window< BaseType >:

Public Types
using	base_type = BaseType
	Type of the base pointer.

Public Member Functions
	window ()=default
	Construct a window with MPI_WIN_NULL.
	window (communicator const &c, BaseType *base_ptr, MPI_Aint sz, MPI_Info info=MPI_INFO_NULL)
	Construct an MPI window over an existing local memory buffer.
	window (communicator const &c, MPI_Aint sz, MPI_Info info=MPI_INFO_NULL)
	Construct an MPI window with dynamically allocated memory.
	window (window &&other) noexcept
	Move constructor takes ownership of the moved-from MPI window and leaves it with MPI_WIN_NULL.
	window (window const &)=delete
	Deleted copy constructor.
virtual	~window ()
	Destructor calls free() to release the window.
BaseType *	base () const
	Get a pointer to the beginning of the window memory.
void	complete () const
	Completes an RMA access epoch by calling MPI_Win_complete (see also start()).
int	disp_unit () const
	Get the displacement unit in bytes.
void	fence (int assert=0) const
	Synchronize all RMA operations within an access epoch by calling MPI_Win_fence.
void	flush (int rank=-1) const
	Ensure completion of all outstanding RMA operations.
void	free () noexcept
	Release allocated resources owned by the window.
template<typename TargetType = BaseType, typename OriginType> requires (has_mpi_type<OriginType> && has_mpi_type<TargetType>)
void	get (OriginType *origin_addr, int origin_count, int target_rank, MPI_Aint target_disp=0, int target_count=-1) const
	Read data from a remote memory window.
communicator	get_communicator () const
	Get the mpi::communicator associated with the window.
void	lock (int rank=-1, int lock_type=MPI_LOCK_SHARED, int assert=0) const
	Start an RMA access epoch.
	operator MPI_Win () const
	Convert the window to the wrapped MPI_Win object.
	operator MPI_Win * ()
	Convert a pointer to the window to a pointer to the wrapped MPI_Win object.
window &	operator= (window &&rhs) noexcept
	Move assignment operator takes ownership of the moved-from MPI window and leaves it with MPI_WIN_NULL.
window &	operator= (window const &)=delete
	Deleted copy assignment operator.
void	post (group const &grp, int assert=0) const
	Start an RMA exposure epoch by calling MPI_Win_post (see also wait()).
template<typename TargetType = BaseType, typename OriginType> requires (has_mpi_type<OriginType> && has_mpi_type<TargetType>)
void	put (OriginType *origin_addr, int origin_count, int target_rank, MPI_Aint target_disp=0, int target_count=-1) const
	Write data to a remote memory window.
MPI_Aint	size () const
	Get the size of the window in number of elements.
void	start (group const &grp, int assert=0) const
	Start an RMA access epoch by calling MPI_Win_start (see also complete()).
void	sync () const
	Synchronize the public and private copies of the window.
void	unlock (int rank=-1) const
	Complete an RMA access epoch started by lock().
void	wait () const
	Completes an RMA exposure epoch by calling MPI_Win_wait (see also post()).

Constructor & Destructor Documentation

◆ window() [1/2]

template<class BaseType>

mpi::window< BaseType >::window	(	communicator const &	c,
		BaseType *	base_ptr,
		MPI_Aint	sz,
		MPI_Info	info = MPI_INFO_NULL )

inlineexplicit

Construct an MPI window over an existing local memory buffer.

This constructor allows creating a window using a pre-allocated memory buffer by calling MPI_Win_create. The window provides access to the specified memory region across MPI processes within the given communicator. The buffer is not freed upon destruction.

Parameters

c	mpi::communicator that defines the group of processes sharing the window.
base_ptr	Pointer to the base address of the memory buffer.
sz	Number of elements in the buffer.
info	Additional MPI information. Default is MPI_INFO_NULL.

Definition at line 104 of file window.hpp.

◆ window() [2/2]

template<class BaseType>

mpi::window< BaseType >::window	(	communicator const &	c,
		MPI_Aint	sz,
		MPI_Info	info = MPI_INFO_NULL )

inlineexplicit

Construct an MPI window with dynamically allocated memory.

This constructor allocates a new memory buffer locally and creates an MPI window over it by calling MPI_Win_allocate. The allocated memory is automatically freed when the window is destroyed. This is useful when the memory region is meant to be shared across processes without needing an external buffer.

Parameters

c	mpi::communicator that defines the group of processes sharing the window.
sz	Number of elements to allocate for the calling process.
info	Additional MPI information. Default is MPI_INFO_NULL.

Definition at line 122 of file window.hpp.

Member Function Documentation

◆ fence()

template<class BaseType>

void mpi::window< BaseType >::fence ( int assert = 0 ) const

inline

Synchronize all RMA operations within an access epoch by calling MPI_Win_fence.

This function acts as a barrier for remote memory access (RMA) operations, ensuring all previous operations on the window are completed before continuing. The call is collective on the group of the window.

Parameters

assert Program assertion.

Definition at line 175 of file window.hpp.

◆ flush()

template<class BaseType>

void mpi::window< BaseType >::flush ( int rank = -1 ) const

inline

Ensure completion of all outstanding RMA operations.

If the given target rank is \( < 0 \), it calls MPI_Win_flush_all. Otherwise, it calls MPI_Win_flush.

Parameters

rank	Target rank.

Definition at line 187 of file window.hpp.

◆ free()

template<class BaseType>

void mpi::window< BaseType >::free ( )

inlinenoexcept

Release allocated resources owned by the window.

Before freeing the owned memory or the MPI_Win handle, a window must have completed all its involvement in RMA communications. For that reason we call MPI_Win_fence before MPI_Win_free.

The window also must be unlocked if it has been previously locked. However, this cannot be detected and is therefore the responsibility of the user.

If the window owns an allocated memory buffer, it will be automatically freed. Otherwise, only the MPI window handle is released.

Definition at line 153 of file window.hpp.

◆ get()

template<class BaseType>

template<typename TargetType = BaseType, typename OriginType>
requires (has_mpi_type<OriginType> && has_mpi_type<TargetType>)

void mpi::window< BaseType >::get	(	OriginType *	origin_addr,
		int	origin_count,
		int	target_rank,
		MPI_Aint	target_disp = 0,
		int	target_count = -1 ) const

inline

Read data from a remote memory window.

This function retrieves data from the memory window on the given process by calling MPI_get and stores it in a local buffer.

Template Parameters

TargetType	Value type of the target memory.
OriginType	Value type of the origin memory.

Parameters

origin_addr	Pointer to the memory buffer where the data will be stored.
origin_count	Number of elements to retrieve.
target_rank	Rank of the target process from which data is fetched.
target_disp	Displacement from the start of the target memory window.
target_count	Number of elements to read from the target. If negative or not specified, defaults to origin_count.

Definition at line 296 of file window.hpp.

◆ lock()

template<class BaseType>

void mpi::window< BaseType >::lock	(	int	rank = -1,
		int	lock_type = MPI_LOCK_SHARED,
		int	assert = 0 ) const

inline

Start an RMA access epoch.

It locks access to the memory window on a specific rank or all ranks, preventing concurrent modifications.

If the given target rank is \( < 0 \), it calls MPI_Win_lock_all. Otherwise, it calls MPI_Win_lock.

Parameters

rank	Target rank.
lock_type	Type of the lock (e.g. MPI_LOCK_SHARED or MPI_LOCK_EXCLUSIVE).
assert	An assertion flag providing optimization hints to MPI.

Definition at line 219 of file window.hpp.

◆ post()

template<class BaseType>

void mpi::window< BaseType >::post	(	group const &	grp,
		int	assert = 0 ) const

inline

Start an RMA exposure epoch by calling MPI_Win_post (see also wait()).

Parameters

grp	mpi::group of origin processes.
assert	An assertion flag providing optimization hints to MPI.

Definition at line 270 of file window.hpp.

◆ put()

template<class BaseType>

template<typename TargetType = BaseType, typename OriginType>
requires (has_mpi_type<OriginType> && has_mpi_type<TargetType>)

void mpi::window< BaseType >::put	(	OriginType *	origin_addr,
		int	origin_count,
		int	target_rank,
		MPI_Aint	target_disp = 0,
		int	target_count = -1 ) const

inline

Write data to a remote memory window.

This function transfers data from a local buffer to the memory window on the given process by calling MPI_Put.

Template Parameters

TargetType	Value type at the target memory.
OriginType	Value type at the origin memory.

Parameters

origin_addr	Pointer to the local memory buffer containing the data to be sent.
origin_count	Number of elements to transfer.
target_rank	Rank of the target process to which data is written.
target_disp	Displacement from the start of the target memory window.
target_count	Number of elements to write to the target. If negative or not specified, defaults to origin_count.

Definition at line 326 of file window.hpp.

◆ start()

template<class BaseType>

void mpi::window< BaseType >::start	(	group const &	grp,
		int	assert = 0 ) const

inline

Start an RMA access epoch by calling MPI_Win_start (see also complete()).

Parameters

grp	mpi::group of target processes.
assert	An assertion flag providing optimization hints to MPI.

Definition at line 255 of file window.hpp.

◆ sync()

template<class BaseType>

void mpi::window< BaseType >::sync ( ) const

inline

Synchronize the public and private copies of the window.

It ensures that any updates to the local memory are visible in the public window and vice versa by calling MPI_Win_sync.

Definition at line 203 of file window.hpp.

◆ unlock()

template<class BaseType>

void mpi::window< BaseType >::unlock ( int rank = -1 ) const

inline

Complete an RMA access epoch started by lock().

It unlocks access to the memory window on a specific rank or all ranks, allowing other processes to access or modify the window.

If the given target rank is \( < 0 \), it calls MPI_Win_unlock_all. Otherwise, it calls MPI_Win_unlock.

Parameters

rank	Target rank.

Definition at line 239 of file window.hpp.

The documentation for this class was generated from the following file:

mpi/window.hpp

Detailed Description

Public Types

Public Member Functions

Constructor & Destructor Documentation

◆ window() [1/2]

◆ window() [2/2]

Member Function Documentation

◆ fence()

◆ flush()

◆ free()

◆ get()

◆ lock()

◆ post()

◆ put()

◆ start()

◆ sync()

◆ unlock()