Executors

A module dedicated to the implementation and usage of the executors in Ginkgo. More...

Collaboration diagram for Executors:

Modules
	CUDA Executor
	A module dedicated to the implementation and usage of the CUDA executor in Ginkgo.
	DPC++ Executor
	A module dedicated to the implementation and usage of the DPC++ executor in Ginkgo.
	HIP Executor
	A module dedicated to the implementation and usage of the HIP executor in Ginkgo.
	OpenMP Executor
	A module dedicated to the implementation and usage of the OpenMP executor in Ginkgo.
	Reference Executor
	A module dedicated to the implementation and usage of the Reference executor in Ginkgo.

Classes
class	gko::Operation
	Operations can be used to define functionalities whose implementations differ among devices. More...
class	gko::Executor
	The first step in using the Ginkgo library consists of creating an executor. More...
class	gko::executor_deleter< T >
	This is a deleter that uses an executor's free method to deallocate the data. More...
class	gko::OmpExecutor
	This is the Executor subclass which represents the OpenMP device (typically CPU). More...
class	gko::ReferenceExecutor
	This is a specialization of the OmpExecutor, which runs the reference implementations of the kernels used for debugging purposes. More...
class	gko::CudaExecutor
	This is the Executor subclass which represents the CUDA device. More...
class	gko::HipExecutor
	This is the Executor subclass which represents the HIP enhanced device. More...
class	gko::DpcppExecutor
	This is the Executor subclass which represents a DPC++ enhanced device. More...

Macros
#define	GKO_REGISTER_OPERATION(_name, _kernel)
	Binds a set of device-specific kernels to an Operation. More...
#define	GKO_REGISTER_HOST_OPERATION(_name, _kernel)
	Binds a host-side kernel (independent of executor type) to an Operation. More...

Detailed Description

A module dedicated to the implementation and usage of the executors in Ginkgo.

Below, we provide a brief introduction to executors in Ginkgo, how they have been implemented, how to best make use of them and how to add new executors.

Executors in Ginkgo.

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:

• OpenMP Executor specifies that the data should be stored and the associated operations executed on an OpenMP-supporting device (e.g. host CPU);
• CUDA Executor specifies that the data should be stored and the operations executed on the NVIDIA GPU accelerator;
• HIP Executor uses the HIP library to compile code for either NVIDIA or AMD GPU accelerator;
• DPC++ Executor uses the DPC++ compiler for any DPC++ supported hardware (e.g. Intel CPUs, GPU, FPGAs, ...);
• Reference Executor executes a non-optimized reference implementation, which can be used to debug the library.

Macro Definition Documentation

GKO_REGISTER_HOST_OPERATION

#define GKO_REGISTER_HOST_OPERATION	(		_name,
			_kernel
	)

Value:

template <typename... Args>                                              \
    auto make_##_name(Args&&... args)                                        \
    {                                                                        \
        return ::gko::detail::make_register_operation(                       \
            #_kernel,                                                        \
            [&args...](auto) { _kernel(std::forward<Args>(args)...); });     \
    }                                                                        \
    static_assert(true,                                                      \
                  "This assert is used to counter the false positive extra " \
                  "semi-colon warnings")

Binds a host-side kernel (independent of executor type) to an Operation.

It also defines a helper function which creates the associated operation. Any input arguments passed to the helper function are forwarded to the kernel when the operation is executed. The kernel name is searched for in the namespace where this macro is called. Host operations are used to make computations that are not part of the device kernels visible to profiling loggers and benchmarks.

Parameters

_name	operation name
_kernel	kernel which will be bound to the operation

Example

 {c++}
void host_kernel(int) {
    // do some expensive computations
}
 
// Bind the kernels to the operation
GKO_REGISTER_HOST_OPERATION(my_op, host_kernel);
 
int main() {
    // create executor
    auto ref = ReferenceExecutor::create();
 
    // create the operation
    auto op = make_my_op(5); // x = 5
 
    ref->run(op);  // run host kernel
}

GKO_REGISTER_OPERATION

#define GKO_REGISTER_OPERATION	(		_name,
			_kernel
	)

Binds a set of device-specific kernels to an Operation.

It also defines a helper function which creates the associated operation. Any input arguments passed to the helper function are forwarded to the kernel when the operation is executed.

The kernels used to bind the operation are searched in kernels::DEV_TYPE namespace, where DEV_TYPE is replaced by omp, cuda, hip, dpcpp and reference.

Parameters

_name	operation name
_kernel	kernel which will be bound to the operation

Example

 {c++}
// define the omp, cuda, hip and reference kernels which will be bound to the
// operation
namespace kernels {
namespace omp {
void my_kernel(int x) {
     // omp code
}
}
namespace cuda {
void my_kernel(int x) {
     // cuda code
}
}
namespace hip {
void my_kernel(int x) {
     // hip code
}
}
namespace dpcpp {
void my_kernel(int x) {
     // dpcpp code
}
}
namespace reference {
void my_kernel(int x) {
    // reference code
}
}
 
// Bind the kernels to the operation
GKO_REGISTER_OPERATION(my_op, my_kernel);
 
int main() {
    // create executors
    auto omp = OmpExecutor::create();
    auto cuda = CudaExecutor::create(0, omp);
    auto hip = HipExecutor::create(0, omp);
    auto dpcpp = DpcppExecutor::create(0, omp);
    auto ref = ReferenceExecutor::create();
 
    // create the operation
    auto op = make_my_op(5); // x = 5
 
    omp->run(op);  // run omp kernel
    cuda->run(op);  // run cuda kernel
    hip->run(op);  // run hip kernel
    dpcpp->run(op);  // run DPC++ kernel
    ref->run(op);  // run reference kernel
}