Ginkgo  Generated from pipelines/224724463 branch based on develop. Ginkgo version 1.3.0
A numerical linear algebra library targeting many-core architectures
Classes | Public Member Functions | Friends | List of all members
gko::Executor Class Referenceabstract

The first step in using the Ginkgo library consists of creating an executor. More...

#include <ginkgo/core/base/executor.hpp>

Collaboration diagram for gko::Executor:
[legend]

Public Member Functions

 Executor (Executor &)=delete
 
 Executor (Executor &&)=default
 
Executoroperator= (Executor &)=delete
 
Executoroperator= (Executor &&)=default
 
virtual void run (const Operation &op) const =0
 Runs the specified Operation using this Executor. More...
 
template<typename ClosureOmp , typename ClosureCuda , typename ClosureHip , typename ClosureDpcpp >
void run (const ClosureOmp &op_omp, const ClosureCuda &op_cuda, const ClosureHip &op_hip, const ClosureDpcpp &op_dpcpp) const
 Runs one of the passed in functors, depending on the Executor type. More...
 
template<typename T >
T * alloc (size_type num_elems) const
 Allocates memory in this Executor. More...
 
void free (void *ptr) const noexcept
 Frees memory previously allocated with Executor::alloc(). More...
 
template<typename T >
void copy_from (const Executor *src_exec, size_type num_elems, const T *src_ptr, T *dest_ptr) const
 Copies data from another Executor. More...
 
template<typename T >
void copy (size_type num_elems, const T *src_ptr, T *dest_ptr) const
 Copies data within this Executor. More...
 
template<typename T >
copy_val_to_host (const T *ptr) const
 Retrieves a single element at the given location from executor memory. More...
 
virtual std::shared_ptr< Executorget_master () noexcept=0
 Returns the master OmpExecutor of this Executor. More...
 
virtual std::shared_ptr< const Executorget_master () const noexcept=0
 Returns the master OmpExecutor of this Executor. More...
 
virtual void synchronize () const =0
 Synchronize the operations launched on the executor with its master.
 
- Public Member Functions inherited from gko::log::EnableLogging< Executor >
void add_logger (std::shared_ptr< const Logger > logger) override
 Adds a new logger to the list of subscribed loggers. More...
 
void remove_logger (const Logger *logger) override
 Removes a logger from the list of subscribed loggers. More...
 

Friends

class OmpExecutor
 
class HipExecutor
 
class DpcppExecutor
 
class CudaExecutor
 

Detailed Description

The first step in using the Ginkgo library consists of creating an executor.

Executors are used to specify the location for the data of linear algebra objects, and to determine where the operations will be executed. Ginkgo currently supports three different executor types:

The following code snippet demonstrates the simplest possible use of the Ginkgo library:

auto omp = gko::create<gko::OmpExecutor>();
auto A = gko::read_from_mtx<gko::matrix::Csr<float>>("A.mtx", omp);

First, we create a OMP executor, which will be used in the next line to specify where we want the data for the matrix A to be stored. The second line will read a matrix from the matrix market file 'A.mtx', and store the data on the CPU in CSR format (gko::matrix::Csr is a Ginkgo matrix class which stores its data in CSR format). At this point, matrix A is bound to the CPU, and any routines called on it will be performed on the CPU. This approach is usually desired in sparse linear algebra, as the cost of individual operations is several orders of magnitude lower than the cost of copying the matrix to the GPU.

If matrix A is going to be reused multiple times, it could be beneficial to copy it over to the accelerator, and perform the operations there, as demonstrated by the next code snippet:

auto cuda = gko::create<gko::CudaExecutor>(0, omp);
auto dA = gko::copy_to<gko::matrix::Csr<float>>(A.get(), cuda);

The first line of the snippet creates a new CUDA executor. Since there may be multiple NVIDIA GPUs present on the system, the first parameter instructs the library to use the first device (i.e. the one with device ID zero, as in cudaSetDevice() routine from the CUDA runtime API). In addition, since GPUs are not stand-alone processors, it is required to pass a "master" OmpExecutor which will be used to schedule the requested CUDA kernels on the accelerator.

The second command creates a copy of the matrix A on the GPU. Notice the use of the get() method. As Ginkgo aims to provide automatic memory management of its objects, the result of calling gko::read_from_mtx() is a smart pointer (std::unique_ptr) to the created object. On the other hand, as the library will not hold a reference to A once the copy is completed, the input parameter for gko::copy_to() is a plain pointer. Thus, the get() method is used to convert from a std::unique_ptr to a plain pointer, as expected by gko::copy_to().

As a side note, the gko::copy_to routine is far more powerful than just copying data between different devices. It can also be used to convert data between different formats. For example, if the above code used gko::matrix::Ell as the template parameter, dA would be stored on the GPU, in ELLPACK format.

Finally, if all the processing of the matrix is supposed to be done on the GPU, and a CPU copy of the matrix is not required, we could have read the matrix to the GPU directly:

auto omp = gko::create<gko::OmpExecutor>();
auto cuda = gko::create<gko::CudaExecutor>(0, omp);
auto dA = gko::read_from_mtx<gko::matrix::Csr<float>>("A.mtx", cuda);

Notice that even though reading the matrix directly from a file to the accelerator is not supported, the library is designed to abstract away the intermediate step of reading the matrix to the CPU memory. This is a general design approach taken by the library: in case an operation is not supported by the device, the data will be copied to the CPU, the operation performed there, and finally the results copied back to the device. This approach makes using the library more concise, as explicit copies are not required by the user. Nevertheless, this feature should be taken into account when considering performance implications of using such operations.

Member Function Documentation

◆ alloc()

template<typename T >
T* gko::Executor::alloc ( size_type  num_elems) const
inline

Allocates memory in this Executor.

Template Parameters
Tdatatype to allocate
Parameters
num_elemsnumber of elements of type T to allocate
Exceptions
AllocationErrorif the allocation failed
Returns
pointer to allocated memory

◆ copy()

template<typename T >
void gko::Executor::copy ( size_type  num_elems,
const T *  src_ptr,
T *  dest_ptr 
) const
inline

Copies data within this Executor.

Template Parameters
Tdatatype to copy
Parameters
num_elemsnumber of elements of type T to copy
src_ptrpointer to a block of memory containing the data to be copied
dest_ptrpointer to an allocated block of memory where the data will be copied to

References copy_from().

◆ copy_from()

template<typename T >
void gko::Executor::copy_from ( const Executor src_exec,
size_type  num_elems,
const T *  src_ptr,
T *  dest_ptr 
) const
inline

Copies data from another Executor.

Template Parameters
Tdatatype to copy
Parameters
src_execExecutor from which the memory will be copied
num_elemsnumber of elements of type T to copy
src_ptrpointer to a block of memory containing the data to be copied
dest_ptrpointer to an allocated block of memory where the data will be copied to

References get_master().

Referenced by copy().

◆ copy_val_to_host()

template<typename T >
T gko::Executor::copy_val_to_host ( const T *  ptr) const
inline

Retrieves a single element at the given location from executor memory.

Template Parameters
Tdatatype to copy
Parameters
ptrthe pointer to the element to be copied
Returns
the value stored at ptr

References get_master().

◆ free()

void gko::Executor::free ( void *  ptr) const
inlinenoexcept

Frees memory previously allocated with Executor::alloc().

If ptr is a nullptr, the function has no effect.

Parameters
ptrpointer to the allocated memory block

◆ get_master() [1/2]

virtual std::shared_ptr<const Executor> gko::Executor::get_master ( ) const
pure virtualnoexcept

Returns the master OmpExecutor of this Executor.

Returns
the master OmpExecutor of this Executor.

Implemented in gko::DpcppExecutor, gko::HipExecutor, gko::CudaExecutor, and gko::OmpExecutor.

◆ get_master() [2/2]

virtual std::shared_ptr<Executor> gko::Executor::get_master ( )
pure virtualnoexcept

Returns the master OmpExecutor of this Executor.

Returns
the master OmpExecutor of this Executor.

Implemented in gko::DpcppExecutor, gko::HipExecutor, gko::CudaExecutor, and gko::OmpExecutor.

Referenced by copy_from(), and copy_val_to_host().

◆ run() [1/2]

template<typename ClosureOmp , typename ClosureCuda , typename ClosureHip , typename ClosureDpcpp >
void gko::Executor::run ( const ClosureOmp &  op_omp,
const ClosureCuda &  op_cuda,
const ClosureHip &  op_hip,
const ClosureDpcpp &  op_dpcpp 
) const
inline

Runs one of the passed in functors, depending on the Executor type.

Template Parameters
ClosureOmptype of op_omp
ClosureCudatype of op_cuda
ClosureHiptype of op_hip
Parameters
op_ompfunctor to run in case of a OmpExecutor or ReferenceExecutor
op_cudafunctor to run in case of a CudaExecutor
op_hipfunctor to run in case of a HipExecutor

References run().

◆ run() [2/2]

virtual void gko::Executor::run ( const Operation op) const
pure virtual

Runs the specified Operation using this Executor.

Parameters
opthe operation to run

Implemented in gko::DpcppExecutor, gko::HipExecutor, gko::CudaExecutor, and gko::ReferenceExecutor.

Referenced by run().


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