ALP User Documentation  0.8.preview
Algebraic Programming User Documentation
Public Member Functions | List of all members
PinnedVector< IOType, implementation > Class Template Reference

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

Public Member Functions

template<typename Coord >
 PinnedVector (const Vector< IOType, implementation, Coord > &vector, const IOMode mode)
 Pins the contents of a given vector. More...
 
 PinnedVector ()
 Base constructor for this class. More...
 
 ~PinnedVector ()
 Destroys a grb::PinnedVector instance. More...
 
size_t getNonzeroIndex (const size_t k) const noexcept
 Retrieves a nonzero index. 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...
 
IOType getNonzeroValue (const size_t k) const noexcept
 Direct access variation of the general getNonzeroValue function. 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]vectorThe vector to pin the memory of.
[in]modeThe 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]kThe 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]

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

Returns a requested nonzero of the pinned vector.

Template Parameters
OutputTypeThe 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]kThe 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.

◆ getNonzeroValue() [2/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.

◆ 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: