PinnedVector< IOType, implementation > Class Template Reference

Provides a mechanism to access ALP containers from outside of an ALP context. More...

#include <pinnedvector.hpp>

Public Member Functions
	PinnedVector ()
	Base constructor for this class. More...
template<typename Coord >
	PinnedVector (const Vector< IOType, implementation, Coord > &vector, const IOMode mode)
	Pins the contents of a given vector. More...
	~PinnedVector ()
	Destroys a grb::PinnedVector instance. More...
size_t	getNonzeroIndex (const size_t k) const noexcept
	Retrieves a nonzero index. More...
IOType	getNonzeroValue (const size_t k) const noexcept
	Direct access variation of the general getNonzeroValue function. More...
template<typename OutputType >
OutputType	getNonzeroValue (const size_t k, const OutputType one=OutputType()) const noexcept
	Returns a requested nonzero of the pinned vector. More...
size_t	nonzeroes () const noexcept
size_t	size () const noexcept

Detailed Description

template<typename IOType, enum Backend implementation>
class grb::PinnedVector< IOType, implementation >

Provides a mechanism to access ALP containers from outside of an ALP context.

An instance of grb::PinnedVector caches a container's data and returns it to the user. The user can refer to the returned data until such time the instance of grb::PinnedVector is destroyed, regardless of whether a call to grb::finalize occurs, and regardless whether the ALP/GraphBLAS program executed through the grb::Launcher had already returned.

The original container may not be modified or any derived instance of PinnedVector shall become invalid.

Note

It would be strange if an ALP/GraphBLAS container a pinned vector is derived from persists– pinned vectors are designed to be used precisely when the original container no longer is in scope. Therefore this last remark on invalidation should not matter.

The grb::PinnedVector abstracts a read-only container of nonzeroes. A nonzero is a pair of indices and values. One may query for the number of nonzeroes and use

1. getNonzeroValue to retrieve a nonzero value, or
2. getNonzeroIndex to retrieve a nonzero index.

An instance of grb::PinnedVector cannot modify the underlying nonzero structure nor can it modify its values.

Note

A performant implementation in fact does not copy the container data, but provides a mechanism to access the underlying ALP memory whenever it is possible to do so. This memory should remain valid even after a call to grb::Launcher::exec has completed, and for as long as the grb::PinnedVector instance remains valid.

Constructor & Destructor Documentation

PinnedVector() [1/2]

PinnedVector ( const Vector< IOType, implementation, Coord > &  vector, const IOMode  mode  )

inline

Pins the contents of a given vector.

A successfully constructed grb::PinnedVector shall remain valid until it is destroyed, regardless of whether the ALP context in which the original vector appears has been destroyed.

Pinning may or may not require a memory copy, depending on the ALP implementation and backend. If it does not, then destroying this instance may result in memory deallocation. It only must result in deallocation if the pinned vector that did not require a memory copy happens to be the last remaining reference to the original vector.

If one user process calls this constructor, all user processes must do so and with the same arguments– this is a collective call.

All member functions of this class are not collective.

Parameters

[in]	vector	The vector to pin the memory of.
[in]	mode	The grb::IOMode.

The mode argument is optional. The default is grb::PARALLEL.

Performance semantics (#IOMode::SEQUENTIAL):

1. This function contains \( \Theta(n) \) work, where \( n \) is the global length of vector.
2. This function moves up to \( \mathcal{O}(n) \) bytes of data within its process.
3. This function incurs an inter-process communication cost bounded by \( \mathcal{O}(ng+\log(p)l) \).
4. This function may allocate \( \mathcal{O}(n) \) memory and (thus) incur system calls.

Performance semantics (#IOMode::PARALLEL):

1. This function contains \( \Theta(1) \) work.
2. This function moves \( \Theta(1) \) data within its process.
3. This function has no inter-process communication cost.
4. This function performs no dynamic memory allocations and shall not make system calls.

PinnedVector() [2/2]

PinnedVector ( )

inline

Base constructor for this class.

This corresponds to pinning an empty vector of zero size in PARALLEL mode. A call to this function inherits the same performance semantics as described above.

Unlike the above, and exceptionally, calling this constructor need not be a collective operation.

~PinnedVector()

~PinnedVector ( )

inline

Destroys a grb::PinnedVector instance.

Destroying a pinned vector will only remove the underlying vector data if and only if: 1) the original grb::Vector has been destroyed; 2) no other PinnedVector instance derived from the same source container exists.

Member Function Documentation

getNonzeroIndex()

size_t getNonzeroIndex ( const size_t  k ) const

inlinenoexcept

Retrieves a nonzero index.

Parameters

[in]

k

The nonzero ID to return the index of.

A nonzero is a tuple of an index and nonzero value. A pinned vector holds nonzeroes nonzeroes. Therefore, k must be less than nonzeroes.

Returns

The requested index.

Performance semantics.

1. This function incurs \( \Theta(1) \) work.
2. This function moves \( \Theta(1) \) bytes of data.
3. This function does not incur inter-process communication.
4. This function does not allocate new memory nor makes any other system calls.

getNonzeroValue() [1/2]

IOType getNonzeroValue ( const size_t  k ) const

inlinenoexcept

Direct access variation of the general getNonzeroValue function.

This variant is only defined when IOType is not void.

Warning

If, in your application, IOType is templated and can be void, then robust code should use the general getNonzeroValue variant.

For semantics, including performance semantics, see the general specification of getNonzeroValue.

Note

By providing this variant, implementations may avoid the requirement that IOType must be default-constructable.

getNonzeroValue() [2/2]

OutputType getNonzeroValue ( const size_t  k, const OutputType  one = OutputType()  ) const

inlinenoexcept

Returns a requested nonzero of the pinned vector.

Template Parameters

OutputType

The value type returned by this function. If this differs from IOType and IOType is not void, then nonzero values will be cast to OutputType.

Warning

If OutputType and IOType is not compatible, then this function should not be used.

Parameters

[in]	k	The nonzero ID to return the value of.
[in]	one	(Optional.) In case IOType is void, which value should be returned in lieu of a vector element value. By default, this will be a default-constructed instance of OutputType.

If OutputType cannot be default-constructed, then one no longer is optional.

A nonzero is a tuple of an index and nonzero value. A pinned vector holds nonzeroes nonzeroes. Therefore, k must be less than nonzeroes.

Returns

The requested value.

Performance semantics.

1. This function incurs \( \Theta(1) \) work.
2. This function moves \( \Theta(1) \) bytes of data.
3. This function does not incur inter-process communication.
4. This function does not allocate new memory nor makes any other system calls.

nonzeroes()

size_t nonzeroes ( ) const

inlinenoexcept

Returns

The number of nonzeroes this pinned vector contains.

Performance semantics.

1. This function incurs \( \Theta(1) \) work.
2. This function moves \( \Theta(1) \) bytes of data.
3. This function does not incur inter-process communication.
4. This function does not allocate new memory nor makes any other system calls.

size()

size_t size ( ) const

inlinenoexcept

Returns

The length of this vector, in number of elements.

Performance semantics.

1. This function incurs \( \Theta(1) \) work.
2. This function moves \( \Theta(1) \) bytes of data.
3. This function does not incur inter-process communication.
4. This function does not allocate new memory nor makes any other system calls.

---

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

• pinnedvector.hpp