\doxysection{Executors }
\hypertarget{group__Executor}{}\label{group__Executor}\index{Executors@{Executors}}


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


Collaboration diagram for Executors:\+
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=350pt]{group__Executor}
\end{center}
\end{figure}
\doxysubsubsection*{Topics}
\begin{DoxyCompactItemize}
\item 
\doxymbox{\hyperlink{group__exec__cuda}{CUDA Executor}}
\begin{DoxyCompactList}\small\item\em A module dedicated to the implementation and usage of the CUDA executor in Ginkgo. \end{DoxyCompactList}\item 
\doxymbox{\hyperlink{group__exec__dpcpp}{DPC++ Executor}}
\begin{DoxyCompactList}\small\item\em A module dedicated to the implementation and usage of the DPC++ executor in Ginkgo. \end{DoxyCompactList}\item 
\doxymbox{\hyperlink{group__exec__hip}{HIP Executor}}
\begin{DoxyCompactList}\small\item\em A module dedicated to the implementation and usage of the HIP executor in Ginkgo. \end{DoxyCompactList}\item 
\doxymbox{\hyperlink{group__exec__omp}{Open\+MP Executor}}
\begin{DoxyCompactList}\small\item\em A module dedicated to the implementation and usage of the Open\+MP executor in Ginkgo. \end{DoxyCompactList}\item 
\doxymbox{\hyperlink{group__exec__ref}{Reference Executor}}
\begin{DoxyCompactList}\small\item\em A module dedicated to the implementation and usage of the Reference executor in Ginkgo. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsubsection*{Classes}
\begin{DoxyCompactItemize}
\item 
class \doxymbox{\hyperlink{classgko_1_1Operation}{gko::\+\+Operation}}
\begin{DoxyCompactList}\small\item\em Operations can be used to define functionalities whose implementations differ among devices. \end{DoxyCompactList}\item 
class \doxymbox{\hyperlink{classgko_1_1Executor}{gko::\+\+Executor}}
\begin{DoxyCompactList}\small\item\em The first step in using the Ginkgo library consists of creating an executor. \end{DoxyCompactList}\item 
class \doxymbox{\hyperlink{classgko_1_1executor__deleter}{gko::\+executor\+\_\+deleter$<$ T $>$}}
\begin{DoxyCompactList}\small\item\em This is a deleter that uses an executor\textquotesingle{}s {\ttfamily free} method to deallocate the data. \end{DoxyCompactList}\item 
class \doxymbox{\hyperlink{classgko_1_1OmpExecutor}{gko::\+\+Omp\+Executor}}
\begin{DoxyCompactList}\small\item\em This is the \doxylink{classgko_1_1Executor}{Executor} subclass which represents the Open\+MP device (typically CPU). \end{DoxyCompactList}\item 
class \doxymbox{\hyperlink{classgko_1_1ReferenceExecutor}{gko::\+\+Reference\+Executor}}
\begin{DoxyCompactList}\small\item\em This is a specialization of the \doxylink{classgko_1_1OmpExecutor}{Omp\+Executor}, which runs the reference implementations of the kernels used for debugging purposes. \end{DoxyCompactList}\item 
class \doxymbox{\hyperlink{classgko_1_1CudaExecutor}{gko::\+\+Cuda\+Executor}}
\begin{DoxyCompactList}\small\item\em This is the \doxylink{classgko_1_1Executor}{Executor} subclass which represents the CUDA device. \end{DoxyCompactList}\item 
class \doxymbox{\hyperlink{classgko_1_1HipExecutor}{gko::\+\+Hip\+Executor}}
\begin{DoxyCompactList}\small\item\em This is the \doxylink{classgko_1_1Executor}{Executor} subclass which represents the HIP enhanced device. \end{DoxyCompactList}\item 
class \doxymbox{\hyperlink{classgko_1_1DpcppExecutor}{gko::\+\+Dpcpp\+Executor}}
\begin{DoxyCompactList}\small\item\em This is the \doxylink{classgko_1_1Executor}{Executor} subclass which represents a DPC++ enhanced device. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsubsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\+\#define \doxymbox{\hyperlink{group__Executor_ga7f2c119ff9f4f51c7f8e2d5dbbbbd044}{GKO\+\_\+\+REGISTER\+\_\+\+OPERATION}}(\+\_\+name,  \+\_\+kernel)
\begin{DoxyCompactList}\small\item\em Binds a set of device-\/specific kernels to an Operation. \end{DoxyCompactList}\item 
\+\#define \doxymbox{\hyperlink{group__Executor_gae20be793db14dfd6249a315281201550}{GKO\+\_\+\+REGISTER\+\_\+\+HOST\+\_\+\+OPERATION}}(\+\_\+name,  \+\_\+kernel)
\begin{DoxyCompactList}\small\item\em Binds a host-\/side kernel (independent of executor type) to an Operation. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{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.\hypertarget{group__Executor_exec_1}{}\doxysubsection{\texorpdfstring{Executors in Ginkgo.}{Executors in Ginkgo.}}\label{group__Executor_exec_1}
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:\+


\begin{DoxyItemize}
\item \doxylink{group__exec__omp}{Open\+MP Executor} specifies that the data should be stored and the associated operations executed on an Open\+MP-\/supporting device (e.\+g. host CPU);
\item \doxylink{group__exec__cuda}{CUDA Executor} specifies that the data should be stored and the operations executed on the NVIDIA GPU accelerator;
\item \doxylink{group__exec__hip}{HIP Executor} uses the HIP library to compile code for either NVIDIA or AMD GPU accelerator;
\item \doxylink{group__exec__dpcpp}{DPC++ Executor} uses the DPC++ compiler for any DPC++ supported hardware (e.\+g. Intel CPUs, GPU, FPGAs, ...);
\item \doxylink{group__exec__ref}{Reference Executor} executes a non-\/optimized reference implementation, which can be used to debug the library. 
\end{DoxyItemize}

\label{doc-define-members}
\Hypertarget{group__Executor_doc-define-members}
\doxysubsection{Macro Definition Documentation}
\Hypertarget{group__Executor_gae20be793db14dfd6249a315281201550}\index{Executors@{Executors}!GKO\_REGISTER\_HOST\_OPERATION@{GKO\_REGISTER\_HOST\_OPERATION}}
\index{GKO\_REGISTER\_HOST\_OPERATION@{GKO\_REGISTER\_HOST\_OPERATION}!Executors@{Executors}}
\doxysubsubsection{\texorpdfstring{GKO\_REGISTER\_HOST\_OPERATION}{GKO\_REGISTER\_HOST\_OPERATION}}
{\footnotesize\ttfamily \label{group__Executor_gae20be793db14dfd6249a315281201550} 
\+\#define GKO\+\_\+\+REGISTER\+\_\+\+HOST\+\_\+\+OPERATION(\begin{DoxyParamCaption}\item[{}]{\+\_\+name}{, }\item[{}]{\+\_\+kernel}{}\end{DoxyParamCaption})}

{\bfseries Value:\+}
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{template}\ <\textcolor{keyword}{typename}...\ Args>\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \(\backslash\)}
\DoxyCodeLine{\textcolor{keyword}{auto}\ make\_\#\#\_name(Args\&\&...\ args)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \(\backslash\)}
\DoxyCodeLine{\{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \(\backslash\)}
\DoxyCodeLine{\ \ \ \ return\ ::gko::detail::make\_register\_operation(\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \(\backslash\)}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \#\_kernel,\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \(\backslash\)}
\DoxyCodeLine{\ \ \ \ \ \ \ \ [\&args...](\textcolor{keyword}{auto})\ \{\ \_kernel(std::forward<Args>(args)...);\ \});\ \ \ \ \ \(\backslash\)}
\DoxyCodeLine{\}\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \(\backslash\)}
\DoxyCodeLine{static\_assert(\textcolor{keyword}{true},\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \(\backslash\)}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \textcolor{stringliteral}{"{}This\ assert\ is\ used\ to\ counter\ the\ false\ positive\ extra\ "{}}\ \(\backslash\)}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \textcolor{stringliteral}{"{}semi-\/colon\ warnings"{}})}

\end{DoxyCode}


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.


\begin{DoxyParams}{Parameters}
{\em \+\_\+name} & operation name \\
\hline
{\em \+\_\+kernel} & kernel which will be bound to the operation\\
\hline
\end{DoxyParams}
\hypertarget{group__Executor_autotoc_md73}{}\doxysubsubsection{\texorpdfstring{Example}{Example}}\label{group__Executor_autotoc_md73}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void}\ host\_kernel(\textcolor{keywordtype}{int})\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ do\ some\ expensive\ computations}}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{//\ Bind\ the\ kernels\ to\ the\ operation}}
\DoxyCodeLine{\doxymbox{\hyperlink{group__Executor_gae20be793db14dfd6249a315281201550}{GKO\_REGISTER\_HOST\_OPERATION}}(my\_op,\ host\_kernel);}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ main()\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ create\ executor}}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ ref\ =\ ReferenceExecutor::create();}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ create\ the\ operation}}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ op\ =\ make\_my\_op(5);\ \textcolor{comment}{//\ x\ =\ 5}}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ ref-\/>run(op);\ \ \textcolor{comment}{//\ run\ host\ kernel}}
\DoxyCodeLine{\}}

\end{DoxyCode}
 \Hypertarget{group__Executor_ga7f2c119ff9f4f51c7f8e2d5dbbbbd044}\index{Executors@{Executors}!GKO\_REGISTER\_OPERATION@{GKO\_REGISTER\_OPERATION}}
\index{GKO\_REGISTER\_OPERATION@{GKO\_REGISTER\_OPERATION}!Executors@{Executors}}
\doxysubsubsection{\texorpdfstring{GKO\_REGISTER\_OPERATION}{GKO\_REGISTER\_OPERATION}}
{\footnotesize\ttfamily \label{group__Executor_ga7f2c119ff9f4f51c7f8e2d5dbbbbd044} 
\+\#define GKO\+\_\+\+REGISTER\+\_\+\+OPERATION(\begin{DoxyParamCaption}\item[{}]{\+\_\+name}{, }\item[{}]{\+\_\+kernel}{}\end{DoxyParamCaption})}



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 {\ttfamily kernels::\+\+DEV\+\_\+\+TYPE} namespace, where {\ttfamily DEV\+\_\+\+TYPE} is replaced by {\ttfamily omp}, {\ttfamily cuda}, {\ttfamily hip}, {\ttfamily dpcpp} and {\ttfamily reference}.


\begin{DoxyParams}{Parameters}
{\em \+\_\+name} & operation name \\
\hline
{\em \+\_\+kernel} & kernel which will be bound to the operation\\
\hline
\end{DoxyParams}
\hypertarget{group__Executor_autotoc_md72}{}\doxysubsubsection{\texorpdfstring{Example}{Example}}\label{group__Executor_autotoc_md72}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{//\ define\ the\ omp,\ cuda,\ hip\ and\ reference\ kernels\ which\ will\ be\ bound\ to\ the}}
\DoxyCodeLine{\textcolor{comment}{//\ operation}}
\DoxyCodeLine{\textcolor{keyword}{namespace\ }kernels\ \{}
\DoxyCodeLine{\textcolor{keyword}{namespace\ }omp\ \{}
\DoxyCodeLine{\textcolor{keywordtype}{void}\ my\_kernel(\textcolor{keywordtype}{int}\ x)\ \{}
\DoxyCodeLine{\ \ \ \ \ \textcolor{comment}{//\ omp\ code}}
\DoxyCodeLine{\}}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keyword}{namespace\ }cuda\ \{}
\DoxyCodeLine{\textcolor{keywordtype}{void}\ my\_kernel(\textcolor{keywordtype}{int}\ x)\ \{}
\DoxyCodeLine{\ \ \ \ \ \textcolor{comment}{//\ cuda\ code}}
\DoxyCodeLine{\}}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keyword}{namespace\ }hip\ \{}
\DoxyCodeLine{\textcolor{keywordtype}{void}\ my\_kernel(\textcolor{keywordtype}{int}\ x)\ \{}
\DoxyCodeLine{\ \ \ \ \ \textcolor{comment}{//\ hip\ code}}
\DoxyCodeLine{\}}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keyword}{namespace\ }dpcpp\ \{}
\DoxyCodeLine{\textcolor{keywordtype}{void}\ my\_kernel(\textcolor{keywordtype}{int}\ x)\ \{}
\DoxyCodeLine{\ \ \ \ \ \textcolor{comment}{//\ dpcpp\ code}}
\DoxyCodeLine{\}}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keyword}{namespace\ }reference\ \{}
\DoxyCodeLine{\textcolor{keywordtype}{void}\ my\_kernel(\textcolor{keywordtype}{int}\ x)\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ reference\ code}}
\DoxyCodeLine{\}}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{//\ Bind\ the\ kernels\ to\ the\ operation}}
\DoxyCodeLine{\doxymbox{\hyperlink{group__Executor_ga7f2c119ff9f4f51c7f8e2d5dbbbbd044}{GKO\_REGISTER\_OPERATION}}(my\_op,\ my\_kernel);}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ main()\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ create\ executors}}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ omp\ =\ OmpExecutor::create();}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ cuda\ =\ CudaExecutor::create(0,\ omp);}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ hip\ =\ HipExecutor::create(0,\ omp);}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ dpcpp\ =\ DpcppExecutor::create(0,\ omp);}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ ref\ =\ ReferenceExecutor::create();}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ create\ the\ operation}}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ op\ =\ make\_my\_op(5);\ \textcolor{comment}{//\ x\ =\ 5}}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ omp-\/>run(op);\ \ \textcolor{comment}{//\ run\ omp\ kernel}}
\DoxyCodeLine{\ \ \ \ cuda-\/>run(op);\ \ \textcolor{comment}{//\ run\ cuda\ kernel}}
\DoxyCodeLine{\ \ \ \ hip-\/>run(op);\ \ \textcolor{comment}{//\ run\ hip\ kernel}}
\DoxyCodeLine{\ \ \ \ dpcpp-\/>run(op);\ \ \textcolor{comment}{//\ run\ DPC++\ kernel}}
\DoxyCodeLine{\ \ \ \ ref-\/>run(op);\ \ \textcolor{comment}{//\ run\ reference\ kernel}}
\DoxyCodeLine{\}}

\end{DoxyCode}
 \input{group__exec__cuda}
\input{group__exec__dpcpp}
\input{group__exec__hip}
\input{group__exec__omp}
\input{group__exec__ref}
