Communication Request vector class. More...

#include <dist.hpp>

Public Member Functions
	RequestVector ()
	Standard constructor. More...

	RequestVector (const RequestVector &)=delete
	request vectors are non-copyable

	RequestVector (RequestVector &&other)
	Move constructor. More...

	RequestVector (std::size_t size_)
	Sized constructor. More...

virtual	~RequestVector ()
	virtual destructor More...

std::size_t	active_count () const
	Returns the number of active requests in the vector. More...

void	cancel ()
	Cancels all remaining active requests. More...

void	clear ()
	Clears the request vector. More...

std::size_t	compress ()
	Compresses the request vector. More...

bool	empty () const
	Checks whether the request vector is empty. More...

void	free ()
	Frees all remaining active requests. More...

Request &	get_request (std::size_t idx)
	Returns a (const) reference to a single request in the vector. More...

const Request &	get_request (std::size_t idx) const
	Returns a (const) reference to a single request in the vector. More...

Status &	get_status (std::size_t idx)
	Returns a (const) reference to a single status in the vector. More...

const Status &	get_status (std::size_t idx) const
	Returns a (const) reference to a single status in the vector. More...

bool	is_null () const
	Checks whether all requests are null requests. More...

RequestVector &	operator= (const RequestVector &)=delete
	request vectors are non-copyable

RequestVector &	operator= (RequestVector &&other)
	Move-assignment operator. More...

Request &	operator[] (std::size_t idx)
	Returns a (const) reference to a single request in the vector. More...

const Request &	operator[] (std::size_t idx) const
	Returns a (const) reference to a single request in the vector. More...

void	push_back (Request &&request)
	Inserts a new request at the end of the request vector. More...

void	reserve (std::size_t size_)
	Reserves sufficient space for a specified number of requests. More...

void	resize (std::size_t size_)
	Resizes the request vector. More...

std::size_t	size () const
	Returns the total number of (both active and null) requests in the vector. More...

bool	test_all ()
	Tests whether all active requests are fulfilled (or null). More...

bool	test_any (Status &status)
	Tests whether one of the active requests has been fulfilled. More...

bool	test_any (std::size_t &idx)
	Tests whether one of the active requests has been fulfilled. More...

bool	test_any (std::size_t &idx, Status &status)
	Tests whether one of the active requests has been fulfilled. More...

bool	test_for (std::size_t idx)
	Tests whether a specific request is fulfilled (or null). More...

bool	test_for (std::size_t idx, Status &status)
	Tests whether a specific request is fulfilled (or null). More...

void	wait_all ()
	Blocks until all active requests are fulfilled. More...

bool	wait_any (Status &status)
	Blocks until one of the active requests has been fulfilled. More...

bool	wait_any (std::size_t &idx)
	Blocks until one of the active requests has been fulfilled. More...

bool	wait_any (std::size_t &idx, Status &status)
	Blocks until one of the active requests has been fulfilled. More...

bool	wait_for (std::size_t idx)
	Blocks until a specific request is fulfilled (or null). More...

bool	wait_for (std::size_t idx, Status &status)
	Blocks until a specific request is fulfilled (or null). More...

Private Attributes
std::vector< Request >	_reqs
	internal vector of Request objects More...

std::vector< Status >	_stats
	internal vector of Status objects More...

Detailed Description

Communication Request vector class.

This class encapsulates vectors of Request and Status objects, which can be used to manage a (related) set of requests. This class also offers the corresponding wait and test wrapper functions to check for the completion of a single, multiple or all requests.

This class is move-constructible and move-assignable, but objects of this class are non-copyable.

Waiting for completion:
There are two common scenarios regarding the completion of a request vector:

Wait until all requests are fulfilled: this can be easily achieved by calling wait_all()
Wait until one request is fulfilled, then do some work that is related to the completion of this particular request, and repeat these two steps until all requests have been processed.

The second of the above scenarios can be easily implemented by using a for or while loop and the wait_any() function:

RequestVector reqs;
 
... // create some requests here
 
for(std::size_t idx(0u); reqs.wait_any(idx); )
{
  ... // request 'idx' has been fulfilled
}
 
// all requests have been processed

Author: Peter Zajac

Definition at line 639 of file dist.hpp.

Constructor & Destructor Documentation

◆ RequestVector() [1/3]

FEAT::Dist::RequestVector::RequestVector ( )

inline

Standard constructor.

This constructor creates an empty request vector.

Definition at line 670 of file dist.hpp.

◆ RequestVector() [2/3]

FEAT::Dist::RequestVector::RequestVector ( std::size_t size_ )

inlineexplicit

Sized constructor.

This constructor creates a request vector of the desired size consisting of null requests and empty statuses.

Parameters

[in] size_ The number of null requests (and status objects) to allocate.

Definition at line 685 of file dist.hpp.

◆ RequestVector() [3/3]

FEAT::Dist::RequestVector::RequestVector ( RequestVector && other )

inline

Move constructor.

This constructor moves the input request vector into the newly constructed request vector and clears the input request vector other.

Parameters

[in,out] other The source request vector that is to be moved.

Definition at line 705 of file dist.hpp.

◆ ~RequestVector()

virtual FEAT::Dist::RequestVector::~RequestVector ( )

inlinevirtual

virtual destructor

Definition at line 741 of file dist.hpp.

References is_null(), and XASSERTM.

Member Function Documentation

◆ active_count()

std::size_t FEAT::Dist::RequestVector::active_count ( ) const

inline

Returns the number of active requests in the vector.

Note: If you want to query the total number of (active and null) requests in the vector, use the size() function instead.

Returns: The number of active requests in the vector.

Definition at line 915 of file dist.hpp.

References _reqs.

◆ cancel()

void FEAT::Dist::RequestVector::cancel ( )

inline

Cancels all remaining active requests.

This function cancels all active requests, but does not free them.

Note: This function does nothing if there are no requests at all or if all requests are already null requests.

Definition at line 992 of file dist.hpp.

References _reqs.

◆ clear()

void FEAT::Dist::RequestVector::clear ( )

inline

Clears the request vector.

This function sets the size of the request vector to zero.

Attention: This function must not be called if there are still active requests in vector, as this function will fire an assertion failure otherwise!

Note

If you want to remove all null requests from the vector, use the compress() function instead.
If you want to free all active requests in the vector, use the free() function instead.
If you want to cancel all active requests in the vector, use the cancel() function instead.

Definition at line 1015 of file dist.hpp.

References _reqs, _stats, is_null(), and XASSERT.

◆ compress()

std::size_t FEAT::Dist::RequestVector::compress ( )

inline

Compresses the request vector.

This function removes all null requests (and their corresponding statuses) from the vector and resizes the vector to the size of the remaining active requests.

Note: You usually do not need this function, as the wait/test functions can perfectly work with a vector of mixed null and active requests.

Returns: The number of active requests remaining in the vector.

Definition at line 858 of file dist.hpp.

References _reqs, _stats, and is_null().

◆ empty()

bool FEAT::Dist::RequestVector::empty ( ) const

inline

Checks whether the request vector is empty.

This function checks whether there are neither active nor null requests in the vector.

Note: If you want to check whether there are no active requests in the vector, use the is_null() function instead.

Returns: true, if there are no requests in the vector, otherwise false.

Definition at line 937 of file dist.hpp.

References _reqs.

◆ free()

void FEAT::Dist::RequestVector::free ( )

inline

Frees all remaining active requests.

This function frees all active requests, but does not resize or clear the vector. Upon exit, the vector consists only of null requests (or no requests at all).

Note: This function does nothing if there are no requests at all or if all requests are already null requests.

Definition at line 974 of file dist.hpp.

References _reqs.

◆ get_request() [1/2]

Request & FEAT::Dist::RequestVector::get_request ( std::size_t idx )

inline

Returns a (const) reference to a single request in the vector.

Parameters

[in] idx The index of the request to be returned.

Returns: A (const) reference to the desired Request object.

Definition at line 755 of file dist.hpp.

References _reqs, and XASSERT.

Referenced by FEAT::Global::SynchMatrix< MT_, VMT_ >::exec(), test_for(), and wait_for().

◆ get_request() [2/2]

const Request & FEAT::Dist::RequestVector::get_request ( std::size_t idx ) const

inline

Returns a (const) reference to a single request in the vector.

Parameters

[in] idx The index of the request to be returned.

Returns: A (const) reference to the desired Request object.

Definition at line 762 of file dist.hpp.

References _reqs, and XASSERT.

◆ get_status() [1/2]

Status & FEAT::Dist::RequestVector::get_status ( std::size_t idx )

inline

Returns a (const) reference to a single status in the vector.

Parameters

[in] idx The index of the status to be returned.

Returns: A (const) reference to the desired Status object.

Definition at line 777 of file dist.hpp.

References _stats, and XASSERT.

Referenced by test_for(), and wait_for().

◆ get_status() [2/2]

const Status & FEAT::Dist::RequestVector::get_status ( std::size_t idx ) const

inline

Returns a (const) reference to a single status in the vector.

Parameters

[in] idx The index of the status to be returned.

Returns: A (const) reference to the desired Status object.

Definition at line 784 of file dist.hpp.

References _stats, and XASSERT.

◆ is_null()

bool FEAT::Dist::RequestVector::is_null ( ) const

inline

Checks whether all requests are null requests.

This function checks whether are no active requests left in the vector.

Note: If you want to check whether there are neither active nor null requests in the vector, use the empty() function instead.

Returns: true, if all requests are null, or false, if there exists at least one active request in the vector.

Definition at line 954 of file dist.hpp.

References _reqs.

Referenced by ~RequestVector(), clear(), compress(), FEAT::Global::AlgDofPartiVector< LocalVector_, Mirror_ >::download(), and operator=().

◆ operator=()

RequestVector & FEAT::Dist::RequestVector::operator= ( RequestVector && other )

inline

Move-assignment operator.

This operator moves the input request vector into this request vector object and clears the input request vector other.

Attention: The destination request vector represented by this must be a null request, i.e. it must not contain any active requests, as this operator will fire an assertion failure otherwise!

Parameters

[in,out] other The source request vector that is to be moved.

Returns: *this.

Definition at line 728 of file dist.hpp.

References _reqs, _stats, is_null(), and XASSERT.

◆ operator[]() [1/2]

Request & FEAT::Dist::RequestVector::operator[] ( std::size_t idx )

inline

Returns a (const) reference to a single request in the vector.

Parameters

[in] idx The index of the request to be returned.

Returns: A (const) reference to the desired Request object.

Definition at line 791 of file dist.hpp.

References _reqs, and XASSERT.

◆ operator[]() [2/2]

const Request & FEAT::Dist::RequestVector::operator[] ( std::size_t idx ) const

inline

Returns a (const) reference to a single request in the vector.

Parameters

[in] idx The index of the request to be returned.

Returns: A (const) reference to the desired Request object.

Definition at line 798 of file dist.hpp.

References _reqs, and XASSERT.

◆ push_back()

void FEAT::Dist::RequestVector::push_back ( Request && request )

inline

Inserts a new request at the end of the request vector.

This function also reserves a new internal Status object for the request.

Parameters

[in,out] request The request that is to be inserted into the vector. This object is set to a null request upon exit of this function.

Definition at line 886 of file dist.hpp.

References _reqs, and _stats.

Referenced by FEAT::Global::SynchVectorTicket< VT_, VMT_ >::SynchVectorTicket(), FEAT::Geometry::DistributedMeshDistortion< MeshType_ >::_calc_shortest_edge(), FEAT::Geometry::GlobalMaskedBoundaryFactory< ParentMesh_ >::_sync_bnd_masks(), FEAT::Geometry::DistributedMeshDistortion< MeshType_ >::_synchronize(), FEAT::Geometry::DistributedUmbrellaSmoother< MeshType_ >::_synchronize(), and FEAT::Assembly::StokesFBMAssembler< MeshType_ >::sync().

◆ reserve()

void FEAT::Dist::RequestVector::reserve ( std::size_t size_ )

inline

Reserves sufficient space for a specified number of requests.

This function effectively wraps around the reserve() function of the internal std::vector objects.

Parameters

[in] size_ The minimum number of requests that space is to be reserved for.

Definition at line 813 of file dist.hpp.

References _reqs, and _stats.

Referenced by FEAT::Global::SynchVectorTicket< VT_, VMT_ >::SynchVectorTicket(), FEAT::Geometry::DistributedMeshDistortion< MeshType_ >::_calc_shortest_edge(), FEAT::Geometry::DistributedMeshDistortion< MeshType_ >::_synchronize(), FEAT::Geometry::DistributedUmbrellaSmoother< MeshType_ >::_synchronize(), and FEAT::Assembly::StokesFBMAssembler< MeshType_ >::sync().

◆ resize()

void FEAT::Dist::RequestVector::resize ( std::size_t size_ )

inline

Resizes the request vector.

This function effectively wraps around the resize() function of the internal std::vector objects.

Attention: This function does not free requests that would be removed if the size of the request vector is decreased! Instead, this function fires an assertion failure if a non-null request would be deleted.

Parameters

[in] size_ The new number of requests to be managed.

Definition at line 834 of file dist.hpp.

References _reqs, _stats, and XASSERT.

◆ size()

std::size_t FEAT::Dist::RequestVector::size ( ) const

inline

Returns the total number of (both active and null) requests in the vector.

Note: If you want to query the number of active (i.e. non-null) requests in the vector, use the active_count() function instead.

Returns: The total number of requests in the vector.

Definition at line 901 of file dist.hpp.

References _reqs.

◆ test_all()

bool FEAT::Dist::RequestVector::test_all ( )

Tests whether all active requests are fulfilled (or null).

Note: If you want to check whether there are remaining active requests without changing the state (i.e. fulfilling previously active requests), use the is_null() function instead.

Returns: true, if all requests are fulfilled, of false, if there at least one active request remains.

See also: [MPI31] Section 3.7.5, page 60

Definition at line 283 of file dist.cpp.

◆ test_any() [1/3]

bool FEAT::Dist::RequestVector::test_any ( Status & status )

inline

Tests whether one of the active requests has been fulfilled.

Parameters

[out] status A transient reference to the Status object that receives information about the active request that has been fulfilled by this call.

Attention: This function does not store the status of a successful test in the internal status array of this RequestVector object for efficiency reasons!

Returns: true, if a previously active request has been fulfilled by this call, or false, if no active request has been fulfilled or if there were no active requests left prior to the call of this function.

Definition at line 1137 of file dist.hpp.

References test_any().

◆ test_any() [2/3]

bool FEAT::Dist::RequestVector::test_any ( std::size_t & idx )

inline

Tests whether one of the active requests has been fulfilled.

Parameters

[out] idx A transient reference that receives the index of the previously active request that has been fulfilled by this call.

Note: If this function returns true, the corresponding Status object can be queried by get_status().

Returns: true, if a previously active request has been fulfilled by this call, or false, if no active request has been fulfilled or if there were no active requests left prior to the call of this function.

Definition at line 1112 of file dist.hpp.

References _stats, and test_any().

◆ test_any() [3/3]

bool FEAT::Dist::RequestVector::test_any	(	std::size_t &	idx,
		Status &	status
	)

Tests whether one of the active requests has been fulfilled.

Parameters

[out]	idx	A transient reference that receives the index of the previously active request that has been fulfilled by this call.
[out]	status	A transient reference to the Status object that receives information about the active request that has been fulfilled by this call.

Attention: This function does not store the status of a successful test in the internal status array of this RequestVector object for efficiency reasons!

Returns: true, if a previously active request has been fulfilled by this call, or false, if no active request has been fulfilled or if there were no active requests left prior to the call of this function.

See also: [MPI31] Section 3.7.5, page 58

Definition at line 290 of file dist.cpp.

References FEAT::Dist::Status::mpi_status().

Referenced by test_any().

◆ test_for() [1/2]

bool FEAT::Dist::RequestVector::test_for ( std::size_t idx )

inline

Tests whether a specific request is fulfilled (or null).

Parameters

[in] idx The index of the request that is to be tested.

Note: If this function returns true, the corresponding Status object can be queried by get_status().

Returns: true, if the corresponding request is fulfilled, or false, if the request is still active.

Definition at line 1033 of file dist.hpp.

References get_request(), get_status(), and FEAT::Dist::Request::test().

◆ test_for() [2/2]

bool FEAT::Dist::RequestVector::test_for	(	std::size_t	idx,
		Status &	status
	)

inline

Tests whether a specific request is fulfilled (or null).

Parameters

[in]	idx	The index of the request that is to be tested.
[out]	status	A transient reference to the Status object that receives information about the request, if it was fulfilled by this call.

Attention: This function does not store the status of a successful test in the internal status array of this RequestVector object for efficiency reasons!

Returns: true, if the corresponding request is fulfilled, or false, if the request is still active.

Definition at line 1054 of file dist.hpp.

References get_request(), and FEAT::Dist::Request::test().

◆ wait_all()

void FEAT::Dist::RequestVector::wait_all ( )

Blocks until all active requests are fulfilled.

Note: This function does nothing if all requests are already null upon call.

See also: [MPI31] Section 3.7.5, page 59

Definition at line 324 of file dist.cpp.

◆ wait_any() [1/3]

bool FEAT::Dist::RequestVector::wait_any ( Status & status )

inline

Blocks until one of the active requests has been fulfilled.

Parameters

[out] status A transient reference to the Status object that receives information about the active request that has been fulfilled by this call.

Attention: This function does not store the status of a successful test in the internal status array of this RequestVector object for efficiency reasons!

Returns: true, if a previously active request has been fulfilled by this call, or false, if there were no active requests left upon call of this function.

Note: The return value of this function can be used as a break-condition in a while loop as this function only returns false when all active requests have been fulfilled.

Definition at line 1267 of file dist.hpp.

References wait_any().

◆ wait_any() [2/3]

bool FEAT::Dist::RequestVector::wait_any ( std::size_t & idx )

inline

Blocks until one of the active requests has been fulfilled.

Parameters

[out] idx A transient reference that receives the index of the previously active request that has been fulfilled by this call.

Note: If this function returns true, the corresponding Status object can be queried by get_status().

Returns: true, if a previously active request has been fulfilled by this call, or false, if there were no active requests left upon call of this function.

Note: The return value of this function can be used as a break-condition in a while loop as this function only returns false when all active requests have been fulfilled.

Definition at line 1239 of file dist.hpp.

References _stats, and wait_any().

◆ wait_any() [3/3]

bool FEAT::Dist::RequestVector::wait_any	(	std::size_t &	idx,
		Status &	status
	)

Blocks until one of the active requests has been fulfilled.

Parameters

[out]	idx	A transient reference that receives the index of the previously active request that has been fulfilled by this call.
[out]	status	A transient reference to the Status object that receives information about the active request that has been fulfilled by this call.

Attention: This function does not store the status of a successful test in the internal status array of this RequestVector object for efficiency reasons!

Returns: true, if a previously active request has been fulfilled by this call, or false, if there were no active requests left upon call of this function.

Note: The return value of this function can be used as a break-condition in a while loop as this function only returns false when all active requests have been fulfilled.

See also: [MPI31] Section 3.7.5, page 57

Definition at line 329 of file dist.cpp.

References FEAT::Dist::Status::mpi_status().

Referenced by FEAT::Geometry::DistributedMeshDistortion< MeshType_ >::_calc_shortest_edge(), FEAT::Geometry::DistributedMeshDistortion< MeshType_ >::_synchronize(), FEAT::Geometry::DistributedUmbrellaSmoother< MeshType_ >::_synchronize(), FEAT::Global::AlgDofParti< LAFEM::DenseVector< DT_, IT_ >, LAFEM::VectorMirror< DT_, IT_ > >::assemble_by_gate(), FEAT::Global::AlgDofPartiVector< LocalVector_, Mirror_ >::download(), FEAT::Global::SynchMatrix< MT_, VMT_ >::exec(), FEAT::Global::AlgDofPartiMatrix< LocalMatrix_, Mirror_ >::upload_numeric(), FEAT::Global::SynchVectorTicket< VT_, VMT_ >::wait(), and wait_any().

◆ wait_for() [1/2]

bool FEAT::Dist::RequestVector::wait_for ( std::size_t idx )

inline

Blocks until a specific request is fulfilled (or null).

Parameters

[in] idx The index of the request that is to be waited for.

Note: The corresponding Status object can be queried by get_status().

Returns: true, if the corresponding request was fulfilled by this call, or false, if the corresponding request was already null prior to this call.

Definition at line 1156 of file dist.hpp.

References get_request(), get_status(), and FEAT::Dist::Request::wait().

◆ wait_for() [2/2]

bool FEAT::Dist::RequestVector::wait_for	(	std::size_t	idx,
		Status &	status
	)

inline

Blocks until a specific request is fulfilled (or null).

Parameters

[in]	idx	The index of the request that is to be waited for.
[out]	status	A transient reference to the Status object that receives information about the request, if it was fulfilled by this call.

Attention: This function does not store the status of a successful wait in the internal status array of this RequestVector object for efficiency reasons!

Returns: true, if the corresponding request was fulfilled by this call, or false, if the corresponding request was already null prior to this call.

Definition at line 1179 of file dist.hpp.

References get_request(), and FEAT::Dist::Request::wait().

Member Data Documentation

◆ _reqs

std::vector<Request> FEAT::Dist::RequestVector::_reqs

private

internal vector of Request objects

Definition at line 643 of file dist.hpp.

Referenced by active_count(), cancel(), clear(), compress(), empty(), free(), get_request(), is_null(), operator=(), operator[](), push_back(), reserve(), resize(), and size().

◆ _stats

std::vector<Status> FEAT::Dist::RequestVector::_stats

private

internal vector of Status objects

Definition at line 645 of file dist.hpp.

Referenced by clear(), compress(), get_status(), operator=(), push_back(), reserve(), resize(), test_any(), and wait_any().

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

kernel/util/dist.hpp
kernel/util/dist.cpp

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RequestVector() [1/3]

◆ RequestVector() [2/3]

◆ RequestVector() [3/3]

◆ ~RequestVector()

Member Function Documentation

◆ active_count()

◆ cancel()

◆ clear()

◆ compress()

◆ empty()

◆ free()

◆ get_request() [1/2]

◆ get_request() [2/2]

◆ get_status() [1/2]

◆ get_status() [2/2]

◆ is_null()

◆ operator=()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ push_back()

◆ reserve()

◆ resize()

◆ size()

◆ test_all()

◆ test_any() [1/3]

◆ test_any() [2/3]

◆ test_any() [3/3]

◆ test_for() [1/2]

◆ test_for() [2/2]

◆ wait_all()

◆ wait_any() [1/3]

◆ wait_any() [2/3]

◆ wait_any() [3/3]

◆ wait_for() [1/2]

◆ wait_for() [2/2]

Member Data Documentation

◆ _reqs

◆ _stats