DPC++ Runtime
Runtime libraries for oneAPI Data Parallel C++
cl::sycl::handler Class Reference

Command group handler class. More...

#include <CL/sycl/handler.hpp>

Classes

struct  ShouldEnableSetArg
 

Public Types

template<typename T >
using remove_cv_ref_t = typename detail::remove_cv_t< detail::remove_reference_t< T > >
 
template<typename U , typename T >
using is_same_type = std::is_same< remove_cv_ref_t< U >, remove_cv_ref_t< T > >
 

Public Member Functions

 handler (const handler &)=delete
 
 handler (handler &&)=delete
 
handleroperator= (const handler &)=delete
 
handleroperator= (handler &&)=delete
 
void use_kernel_bundle (const kernel_bundle< bundle_state::executable > &ExecBundle)
 
template<typename DataT , int Dims, access::mode AccMode, access::target AccTarget>
void require (accessor< DataT, Dims, AccMode, AccTarget, access::placeholder::true_t > Acc)
 Requires access to the memory object associated with the placeholder accessor. More...
 
void depends_on (event Event)
 Registers event dependencies on this command group. More...
 
void depends_on (const std::vector< event > &Events)
 Registers event dependencies on this command group. More...
 
template<typename T >
detail::enable_if_t< ShouldEnableSetArg< T >::value, void > set_arg (int ArgIndex, T &&Arg)
 Sets argument for OpenCL interoperability kernels. More...
 
template<typename DataT , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder>
void set_arg (int ArgIndex, accessor< DataT, Dims, AccessMode, AccessTarget, IsPlaceholder > Arg)
 
template<typename... Ts>
void set_args (Ts &&... Args)
 Sets arguments for OpenCL interoperability kernels. More...
 
template<typename KernelName = detail::auto_name, typename KernelType >
void single_task (KernelType KernelFunc)
 Defines and invokes a SYCL kernel function as a function object type. More...
 
template<typename KernelName = detail::auto_name, typename KernelType >
void parallel_for (range< 1 > NumWorkItems, KernelType KernelFunc)
 
template<typename KernelName = detail::auto_name, typename KernelType >
void parallel_for (range< 2 > NumWorkItems, KernelType KernelFunc)
 
template<typename KernelName = detail::auto_name, typename KernelType >
void parallel_for (range< 3 > NumWorkItems, KernelType KernelFunc)
 
template<typename FuncT >
 __SYCL_DEPRECATED ("run_on_host_intel() is deprecated, use host_task() instead") void run_on_host_intel(FuncT Func)
 Defines and invokes a SYCL kernel on host device. More...
 
template<typename FuncT >
detail::enable_if_t< detail::check_fn_signature< detail::remove_reference_t< FuncT >, void()>::value||detail::check_fn_signature< detail::remove_reference_t< FuncT >, void(interop_handle)>::value > host_task (FuncT &&Func)
 Enqueues a command to the SYCL runtime to invoke Func once. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void parallel_for (range< Dims > NumWorkItems, id< Dims > WorkItemOffset, _KERNELFUNCPARAM(KernelFunc))
 Defines and invokes a SYCL kernel function for the specified range and offset. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void parallel_for (nd_range< Dims > ExecutionRange, _KERNELFUNCPARAM(KernelFunc))
 Defines and invokes a SYCL kernel function for the specified nd_range. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims, typename Reduction >
void parallel_for (range< Dims > Range, Reduction Redu, _KERNELFUNCPARAM(KernelFunc))
 Defines and invokes a SYCL kernel function for the specified nd_range. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims, typename Reduction >
detail::enable_if_t< Reduction::has_fast_atomics > parallel_for (nd_range< Dims > Range, Reduction Redu, _KERNELFUNCPARAM(KernelFunc))
 Implements parallel_for() accepting nd_range Range and one reduction object. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims, typename Reduction >
detail::enable_if_t< Reduction::has_atomic_add_float64 > parallel_for (nd_range< Dims > Range, Reduction Redu, _KERNELFUNCPARAM(KernelFunc))
 Implements parallel_for() accepting nd_range Range and one reduction object. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims, typename Reduction >
detail::enable_if_t<!Reduction::has_fast_atomics &&!Reduction::has_atomic_add_float64 > parallel_for (nd_range< Dims > Range, Reduction Redu, _KERNELFUNCPARAM(KernelFunc))
 Defines and invokes a SYCL kernel function for the specified nd_range. More...
 
template<typename KernelName , typename KernelType , int Dims, typename Reduction >
detail::enable_if_t<!Reduction::has_fast_atomics > parallel_for_Impl (nd_range< Dims > Range, Reduction Redu, KernelType KernelFunc)
 
template<typename KernelName = detail::auto_name, int Dims, typename... RestT>
std::enable_if_t<(sizeof...(RestT) >=3 &&ext::oneapi::detail::AreAllButLastReductions< RestT... >::value)> parallel_for (nd_range< Dims > Range, RestT... Rest)
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void parallel_for_work_group (range< Dims > NumWorkGroups, _KERNELFUNCPARAM(KernelFunc))
 Hierarchical kernel invocation method of a kernel defined as a lambda encoding the body of each work-group to launch. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void parallel_for_work_group (range< Dims > NumWorkGroups, range< Dims > WorkGroupSize, _KERNELFUNCPARAM(KernelFunc))
 Hierarchical kernel invocation method of a kernel defined as a lambda encoding the body of each work-group to launch. More...
 
void single_task (kernel Kernel)
 Invokes a SYCL kernel. More...
 
void parallel_for (range< 1 > NumWorkItems, kernel Kernel)
 
void parallel_for (range< 2 > NumWorkItems, kernel Kernel)
 
void parallel_for (range< 3 > NumWorkItems, kernel Kernel)
 
template<int Dims>
void parallel_for (range< Dims > NumWorkItems, id< Dims > WorkItemOffset, kernel Kernel)
 Defines and invokes a SYCL kernel function for the specified range and offsets. More...
 
template<int Dims>
void parallel_for (nd_range< Dims > NDRange, kernel Kernel)
 Defines and invokes a SYCL kernel function for the specified range and offsets. More...
 
template<typename KernelName = detail::auto_name, typename KernelType >
void single_task (kernel Kernel, _KERNELFUNCPARAM(KernelFunc))
 Defines and invokes a SYCL kernel function. More...
 
template<typename FuncT >
 __SYCL_DEPRECATED ("interop_task() is deprecated, use host_task() instead") void interop_task(FuncT Func)
 Invokes a lambda on the host. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void parallel_for (kernel Kernel, range< Dims > NumWorkItems, _KERNELFUNCPARAM(KernelFunc))
 Defines and invokes a SYCL kernel function for the specified range. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void parallel_for (kernel Kernel, range< Dims > NumWorkItems, id< Dims > WorkItemOffset, _KERNELFUNCPARAM(KernelFunc))
 Defines and invokes a SYCL kernel function for the specified range and offsets. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void parallel_for (kernel Kernel, nd_range< Dims > NDRange, _KERNELFUNCPARAM(KernelFunc))
 Defines and invokes a SYCL kernel function for the specified range and offsets. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void parallel_for_work_group (kernel Kernel, range< Dims > NumWorkGroups, _KERNELFUNCPARAM(KernelFunc))
 Hierarchical kernel invocation method of a kernel. More...
 
template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void parallel_for_work_group (kernel Kernel, range< Dims > NumWorkGroups, range< Dims > WorkGroupSize, _KERNELFUNCPARAM(KernelFunc))
 Hierarchical kernel invocation method of a kernel. More...
 
template<typename T_Src , typename T_Dst , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void copy (accessor< T_Src, Dims, AccessMode, AccessTarget, IsPlaceholder > Src, std::shared_ptr< T_Dst > Dst)
 Copies the content of memory object accessed by Src into the memory pointed by Dst. More...
 
template<typename T_Src , typename T_Dst , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void copy (std::shared_ptr< T_Src > Src, accessor< T_Dst, Dims, AccessMode, AccessTarget, IsPlaceholder > Dst)
 Copies the content of memory pointed by Src into the memory object accessed by Dst. More...
 
template<typename T_Src , typename T_Dst , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void copy (accessor< T_Src, Dims, AccessMode, AccessTarget, IsPlaceholder > Src, T_Dst *Dst)
 Copies the content of memory object accessed by Src into the memory pointed by Dst. More...
 
template<typename T_Src , typename T_Dst , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void copy (const T_Src *Src, accessor< T_Dst, Dims, AccessMode, AccessTarget, IsPlaceholder > Dst)
 Copies the content of memory pointed by Src into the memory object accessed by Dst. More...
 
template<typename T_Src , int Dims_Src, access::mode AccessMode_Src, access::target AccessTarget_Src, typename T_Dst , int Dims_Dst, access::mode AccessMode_Dst, access::target AccessTarget_Dst, access::placeholder IsPlaceholder_Src = access::placeholder::false_t, access::placeholder IsPlaceholder_Dst = access::placeholder::false_t>
void copy (accessor< T_Src, Dims_Src, AccessMode_Src, AccessTarget_Src, IsPlaceholder_Src > Src, accessor< T_Dst, Dims_Dst, AccessMode_Dst, AccessTarget_Dst, IsPlaceholder_Dst > Dst)
 Copies the content of memory object accessed by Src to the memory object accessed by Dst. More...
 
template<typename T , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void update_host (accessor< T, Dims, AccessMode, AccessTarget, IsPlaceholder > Acc)
 Provides guarantees that the memory object accessed via Acc is updated on the host after command group object execution is complete. More...
 
template<typename T , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t, typename PropertyListT = property_list>
void fill (accessor< T, Dims, AccessMode, AccessTarget, IsPlaceholder, PropertyListT > Dst, const T &Pattern)
 Fills memory pointed by accessor with the pattern given. More...
 
template<typename T >
void fill (void *Ptr, const T &Pattern, size_t Count)
 Fills the specified memory with the specified pattern. More...
 
void ext_oneapi_barrier ()
 Prevents any commands submitted afterward to this queue from executing until all commands previously submitted to this queue have entered the complete state. More...
 
void barrier ()
 Prevents any commands submitted afterward to this queue from executing until all commands previously submitted to this queue have entered the complete state. More...
 
void ext_oneapi_barrier (const std::vector< event > &WaitList)
 Prevents any commands submitted afterward to this queue from executing until all events in WaitList have entered the complete state. More...
 
void barrier (const std::vector< event > &WaitList)
 Prevents any commands submitted afterward to this queue from executing until all events in WaitList have entered the complete state. More...
 
void memcpy (void *Dest, const void *Src, size_t Count)
 Copies data from one memory region to another, both pointed by USM pointers. More...
 
template<typename T >
void copy (const T *Src, T *Dest, size_t Count)
 Copies data from one memory region to another, both pointed by USM pointers. More...
 
void memset (void *Dest, int Value, size_t Count)
 Fills the memory pointed by a USM pointer with the value specified. More...
 
void prefetch (const void *Ptr, size_t Count)
 Provides hints to the runtime library that data should be made available on a device earlier than Unified Shared Memory would normally require it to be available. More...
 
void mem_advise (const void *Ptr, size_t Length, int Advice)
 Provides additional information to the underlying runtime about how different allocations are used. More...
 

Friends

class detail::queue_impl
 
template<typename DataT , int Dims, access::mode AccMode, access::target AccTarget, access::placeholder isPlaceholder, typename PropertyListT >
class accessor
 
template<typename DataT , int Dimensions, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder>
class detail::image_accessor
 
class stream
 
class detail::stream_impl
 
template<typename T , class BinaryOperation , int Dims, bool IsUSM, access::placeholder IsPlaceholder>
class ext::oneapi::detail::reduction_impl
 
class ::MockHandler
 
device detail::getDeviceFromHandler (handler &)
 
void detail::associateWithHandler (handler &, detail::AccessorBaseHost *, access::target)
 

Detailed Description

Command group handler class.

Objects of the handler class collect information about command group, such as kernel, requirements to the memory, arguments for the kernel.

sycl::queue::submit([](handler &CGH){
CGH.require(Accessor1); // Adds a requirement to the memory object.
CGH.setArg(0, Accessor2); // Registers accessor given as an argument to
// the kernel + adds a requirement to the memory
// object.
CGH.setArg(1, N); // Registers value given as an argument to the
// kernel.
// The following registers KernelFunctor to be a kernel that will be
// executed in case of queue is bound to the host device, Kernel - for
// an OpenCL device. This function clearly indicates that command group
// represents kernel execution.
CGH.parallel_for(KernelFunctor, Kernel);
});

The command group can represent absolutely different operations. Depending on the operation we need to store different data. But, in most cases, it's impossible to say what kind of operation we need to perform until the very end. So, handler class contains all fields simultaneously, then during "finalization" it constructs CG object, that represents specific operation, passing fields that are required only.

See also
queue
program
kernel

Definition at line 361 of file handler.hpp.

Member Typedef Documentation

◆ is_same_type

template<typename U , typename T >
using cl::sycl::handler::is_same_type = std::is_same<remove_cv_ref_t<U>, remove_cv_ref_t<T> >

Definition at line 1372 of file handler.hpp.

◆ remove_cv_ref_t

Definition at line 1369 of file handler.hpp.

Constructor & Destructor Documentation

◆ handler() [1/2]

cl::sycl::handler::handler ( const handler )
delete

◆ handler() [2/2]

cl::sycl::handler::handler ( handler &&  )
delete

Member Function Documentation

◆ __SYCL_DEPRECATED() [1/2]

template<typename FuncT >
cl::sycl::handler::__SYCL_DEPRECATED ( "interop_task() is  deprecated,
use host_task() instead  
)
inline

Invokes a lambda on the host.

Dependencies are satisfied on the host.

Parameters
Funcis a lambda that is executed on the host

Definition at line 2056 of file handler.hpp.

◆ __SYCL_DEPRECATED() [2/2]

template<typename FuncT >
cl::sycl::handler::__SYCL_DEPRECATED ( "run_on_host_intel() is  deprecated,
use host_task() instead  
)
inline

Defines and invokes a SYCL kernel on host device.

Parameters
Funcis a SYCL kernel function defined by lambda function or a named function object type.

Definition at line 1475 of file handler.hpp.

◆ barrier() [1/2]

void cl::sycl::handler::barrier ( )
inline

Prevents any commands submitted afterward to this queue from executing until all commands previously submitted to this queue have entered the complete state.

Definition at line 2532 of file handler.hpp.

◆ barrier() [2/2]

void cl::sycl::handler::barrier ( const std::vector< event > &  WaitList)

Prevents any commands submitted afterward to this queue from executing until all events in WaitList have entered the complete state.

If WaitList is empty, then the barrier has no effect.

Parameters
WaitListis a vector of valid SYCL events that need to complete before barrier command can be executed.

Definition at line 685 of file handler.cpp.

References ext_oneapi_barrier().

◆ copy() [1/6]

template<typename T_Src , typename T_Dst , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void cl::sycl::handler::copy ( accessor< T_Src, Dims, AccessMode, AccessTarget, IsPlaceholder >  Src,
std::shared_ptr< T_Dst >  Dst 
)
inline

Copies the content of memory object accessed by Src into the memory pointed by Dst.

Source must have at least as many bytes as the range accessed by Dst.

Parameters
Srcis a source SYCL accessor.
Dstis a smart pointer to destination memory.

Definition at line 2270 of file handler.hpp.

Referenced by cl::sycl::ext::oneapi::detail::reduSaveFinalResultToUserMem(), and cl::sycl::ext::oneapi::detail::reduSaveFinalResultToUserMemHelper().

◆ copy() [2/6]

template<typename T_Src , typename T_Dst , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void cl::sycl::handler::copy ( accessor< T_Src, Dims, AccessMode, AccessTarget, IsPlaceholder >  Src,
T_Dst *  Dst 
)
inline

Copies the content of memory object accessed by Src into the memory pointed by Dst.

Source must have at least as many bytes as the range accessed by Dst.

Parameters
Srcis a source SYCL accessor.
Dstis a pointer to destination memory.

Definition at line 2319 of file handler.hpp.

References cl::sycl::detail::getSyclObjImpl().

◆ copy() [3/6]

template<typename T_Src , int Dims_Src, access::mode AccessMode_Src, access::target AccessTarget_Src, typename T_Dst , int Dims_Dst, access::mode AccessMode_Dst, access::target AccessTarget_Dst, access::placeholder IsPlaceholder_Src = access::placeholder::false_t, access::placeholder IsPlaceholder_Dst = access::placeholder::false_t>
void cl::sycl::handler::copy ( accessor< T_Src, Dims_Src, AccessMode_Src, AccessTarget_Src, IsPlaceholder_Src >  Src,
accessor< T_Dst, Dims_Dst, AccessMode_Dst, AccessTarget_Dst, IsPlaceholder_Dst >  Dst 
)
inline

Copies the content of memory object accessed by Src to the memory object accessed by Dst.

Dst must have at least as many bytes as the range accessed by Src.

Parameters
Srcis a source SYCL accessor.
Dstis a destination SYCL accessor.

Definition at line 2399 of file handler.hpp.

References cl::sycl::accessor< DataT, Dimensions, AccessMode, AccessTarget, IsPlaceholder, PropertyListT >::get_size(), and cl::sycl::detail::getSyclObjImpl().

◆ copy() [4/6]

template<typename T >
void cl::sycl::handler::copy ( const T Src,
T Dest,
size_t  Count 
)
inline

Copies data from one memory region to another, both pointed by USM pointers.

No operations is done if

Parameters
Countis zero. An exception is thrown if either
Destor
Srcis nullptr. The behavior is undefined if any of the pointer parameters is invalid.
Srcis a USM pointer to the source memory.
Destis a USM pointer to the destination memory.
Countis a number of elements of type T to copy.

Definition at line 2571 of file handler.hpp.

References cl::sycl::detail::memcpy().

◆ copy() [5/6]

template<typename T_Src , typename T_Dst , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void cl::sycl::handler::copy ( const T_Src *  Src,
accessor< T_Dst, Dims, AccessMode, AccessTarget, IsPlaceholder >  Dst 
)
inline

Copies the content of memory pointed by Src into the memory object accessed by Dst.

Source must have at least as many bytes as the range accessed by Dst.

Parameters
Srcis a pointer to source memory.
Dstis a destination SYCL accessor.

Definition at line 2358 of file handler.hpp.

References cl::sycl::detail::getSyclObjImpl().

◆ copy() [6/6]

template<typename T_Src , typename T_Dst , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void cl::sycl::handler::copy ( std::shared_ptr< T_Src >  Src,
accessor< T_Dst, Dims, AccessMode, AccessTarget, IsPlaceholder >  Dst 
)
inline

Copies the content of memory pointed by Src into the memory object accessed by Dst.

Source must have at least as many bytes as the range accessed by Dst.

Parameters
Srcis a smart pointer to source memory.
Dstis a destination SYCL accessor.

Definition at line 2295 of file handler.hpp.

◆ depends_on() [1/2]

void cl::sycl::handler::depends_on ( const std::vector< event > &  Events)

Registers event dependencies on this command group.

Parameters
Eventsis a vector of valid SYCL events to wait on.

Definition at line 781 of file handler.cpp.

References cl::sycl::detail::getSyclObjImpl(), cl::sycl::invalid, and cl::sycl::make_error_code().

◆ depends_on() [2/2]

void cl::sycl::handler::depends_on ( event  Event)

Registers event dependencies on this command group.

Parameters
Eventis a valid SYCL event to wait on.

Definition at line 772 of file handler.cpp.

References cl::sycl::detail::getSyclObjImpl(), cl::sycl::invalid, and cl::sycl::make_error_code().

Referenced by cl::sycl::queue::fill(), cl::sycl::queue::parallel_for(), cl::sycl::queue::prefetch(), cl::sycl::ext::oneapi::detail::reduSaveFinalResultToUserMemHelper(), and cl::sycl::queue::single_task().

◆ ext_oneapi_barrier() [1/2]

void cl::sycl::handler::ext_oneapi_barrier ( )
inline

Prevents any commands submitted afterward to this queue from executing until all commands previously submitted to this queue have entered the complete state.

Definition at line 2523 of file handler.hpp.

Referenced by barrier(), and cl::sycl::queue::ext_oneapi_submit_barrier().

◆ ext_oneapi_barrier() [2/2]

void cl::sycl::handler::ext_oneapi_barrier ( const std::vector< event > &  WaitList)

Prevents any commands submitted afterward to this queue from executing until all events in WaitList have entered the complete state.

If WaitList is empty, then the barrier has no effect.

Parameters
WaitListis a vector of valid SYCL events that need to complete before barrier command can be executed.

Definition at line 675 of file handler.cpp.

References cl::sycl::detail::CG::BarrierWaitlist.

◆ fill() [1/2]

template<typename T , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t, typename PropertyListT = property_list>
void cl::sycl::handler::fill ( accessor< T, Dims, AccessMode, AccessTarget, IsPlaceholder, PropertyListT >  Dst,
const T Pattern 
)
inline

Fills memory pointed by accessor with the pattern given.

If the operation is submitted to queue associated with OpenCL device and accessor points to one dimensional memory object then use special type for filling. Otherwise fill using regular kernel.

Parameters
Dstis a destination SYCL accessor.
Patternis a value to be used to fill the memory.

Definition at line 2471 of file handler.hpp.

References cl::sycl::accessor< DataT, Dimensions, AccessMode, AccessTarget, IsPlaceholder, PropertyListT >::get_range(), and cl::sycl::detail::getSyclObjImpl().

Referenced by cl::sycl::queue::fill().

◆ fill() [2/2]

template<typename T >
void cl::sycl::handler::fill ( void *  Ptr,
const T Pattern,
size_t  Count 
)
inline

Fills the specified memory with the specified pattern.

Parameters
Ptris the pointer to the memory to fill
Patternis the pattern to fill into the memory. T should be trivially copyable.
Countis the number of times to fill Pattern into Ptr.

Definition at line 2510 of file handler.hpp.

◆ host_task()

template<typename FuncT >
detail::enable_if_t< detail::check_fn_signature<detail::remove_reference_t<FuncT>, void()>::value || detail::check_fn_signature<detail::remove_reference_t<FuncT>, void(interop_handle)>::value> cl::sycl::handler::host_task ( FuncT &&  Func)
inline

Enqueues a command to the SYCL runtime to invoke Func once.

Definition at line 1495 of file handler.hpp.

◆ mem_advise()

void cl::sycl::handler::mem_advise ( const void *  Ptr,
size_t  Length,
int  Advice 
)

Provides additional information to the underlying runtime about how different allocations are used.

Parameters
Ptris a USM pointer to the allocation.
Lengthis a number of bytes in the allocation.
Adviceis a device-defined advice for the specified allocation.

Definition at line 727 of file handler.cpp.

References cl::sycl::detail::CG::AdviseUSM, cl::sycl::detail::convertToExtendedMembers(), cl::sycl::detail::HANDLER_MEM_ADVICE, and cl::sycl::detail::GlobalHandler::instance().

◆ memcpy()

void cl::sycl::handler::memcpy ( void *  Dest,
const void *  Src,
size_t  Count 
)

Copies data from one memory region to another, both pointed by USM pointers.

No operations is done if

Parameters
Countis zero. An exception is thrown if either
Destor
Srcis nullptr. The behavior is undefined if any of the pointer parameters is invalid.
Destis a USM pointer to the destination memory.
Srcis a USM pointer to the source memory.
Countis a number of bytes to copy.

Definition at line 704 of file handler.cpp.

References cl::sycl::detail::CG::CopyUSM.

◆ memset()

void cl::sycl::handler::memset ( void *  Dest,
int  Value,
size_t  Count 
)

Fills the memory pointed by a USM pointer with the value specified.

No operations is done if

Parameters
Countis zero. An exception is thrown if
Destis nullptr. The behavior is undefined if
Destis invalid.
Destis a USM pointer to the memory to fill.
Valueis a value to be set. Value is cast as an unsigned char.
Countis a number of bytes to fill.

Definition at line 712 of file handler.cpp.

References cl::sycl::detail::CG::FillUSM.

◆ operator=() [1/2]

handler& cl::sycl::handler::operator= ( const handler )
delete

◆ operator=() [2/2]

handler& cl::sycl::handler::operator= ( handler &&  )
delete

◆ parallel_for() [1/18]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void cl::sycl::handler::parallel_for ( kernel  Kernel,
nd_range< Dims >  NDRange,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Defines and invokes a SYCL kernel function for the specified range and offsets.

Parameters
Kernelis a SYCL kernel that is executed on a SYCL device (except for the host device).
NDRangeis a ND-range defining global and local sizes as well as offset.
KernelFuncis a lambda that is used if device, queue is bound to, is a host device.

Definition at line 2148 of file handler.hpp.

References cl::sycl::kernel::get_kernel_bundle(), and cl::sycl::detail::getSyclObjImpl().

◆ parallel_for() [2/18]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void cl::sycl::handler::parallel_for ( kernel  Kernel,
range< Dims >  NumWorkItems,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Defines and invokes a SYCL kernel function for the specified range.

Parameters
Kernelis a SYCL kernel that is executed on a SYCL device (except for the host device).
NumWorkItemsis a range defining indexing space.
KernelFuncis a lambda that is used if device, queue is bound to, is a host device.

Definition at line 2072 of file handler.hpp.

References cl::sycl::kernel::get_kernel_bundle(), and cl::sycl::detail::getSyclObjImpl().

◆ parallel_for() [3/18]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void cl::sycl::handler::parallel_for ( kernel  Kernel,
range< Dims >  NumWorkItems,
id< Dims >  WorkItemOffset,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Defines and invokes a SYCL kernel function for the specified range and offsets.

Parameters
Kernelis a SYCL kernel that is executed on a SYCL device (except for the host device).
NumWorkItemsis a range defining indexing space.
WorkItemOffsetis an offset to be applied to each work item index.
KernelFuncis a lambda that is used if device, queue is bound to, is a host device.

Definition at line 2110 of file handler.hpp.

References cl::sycl::detail::getSyclObjImpl().

◆ parallel_for() [4/18]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void cl::sycl::handler::parallel_for ( nd_range< Dims >  ExecutionRange,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Defines and invokes a SYCL kernel function for the specified nd_range.

The SYCL kernel function is defined as a lambda function or a named function object type and given an id or item for indexing in the indexing space defined by range. If it is a named function object and the function object type is globally visible, there is no need for the developer to provide a kernel name for it.

Parameters
ExecutionRangeis a ND-range defining global and local sizes as well as offset.
KernelFuncis a SYCL kernel function.

Definition at line 1555 of file handler.hpp.

◆ parallel_for() [5/18]

template<int Dims>
void cl::sycl::handler::parallel_for ( nd_range< Dims >  NDRange,
kernel  Kernel 
)
inline

Defines and invokes a SYCL kernel function for the specified range and offsets.

The SYCL kernel function is defined as SYCL kernel object.

Parameters
NDRangeis a ND-range defining global and local sizes as well as offset.
Kernelis a SYCL kernel function.

Definition at line 2009 of file handler.hpp.

References cl::sycl::detail::getSyclObjImpl().

◆ parallel_for() [6/18]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims, typename Reduction >
detail::enable_if_t<Reduction::has_fast_atomics> cl::sycl::handler::parallel_for ( nd_range< Dims >  Range,
Reduction  Redu,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Implements parallel_for() accepting nd_range Range and one reduction object.

This version uses fast sycl::atomic operations to update reduction variable at the end of each work-group work.

Definition at line 1639 of file handler.hpp.

◆ parallel_for() [7/18]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims, typename Reduction >
detail::enable_if_t<Reduction::has_atomic_add_float64> cl::sycl::handler::parallel_for ( nd_range< Dims >  Range,
Reduction  Redu,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Implements parallel_for() accepting nd_range Range and one reduction object.

This version is a specialization for the add operator. It performs runtime checks for device aspect "atomic64"; if found, fast sycl::atomic_ref operations are used to update the reduction at the end of each work-group work. Otherwise the default implementation is used.

Definition at line 1673 of file handler.hpp.

References cl::sycl::detail::getDeviceFromHandler(), and cl::sycl::device::has().

◆ parallel_for() [8/18]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims, typename Reduction >
detail::enable_if_t<!Reduction::has_fast_atomics && !Reduction::has_atomic_add_float64> cl::sycl::handler::parallel_for ( nd_range< Dims >  Range,
Reduction  Redu,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Defines and invokes a SYCL kernel function for the specified nd_range.

Performs reduction operation specified in Redu.

The SYCL kernel function is defined as a lambda function or a named function object type and given an id or item for indexing in the indexing space defined by Range. If it is a named function object and the function object type is globally visible, there is no need for the developer to provide a kernel name for it.

TODO: Support HOST. The kernels called by this parallel_for() may use some functionality that is not yet supported on HOST such as: barrier(), and ext::oneapi::reduce() that also may be used in more optimized implementations waiting for their turn of code-review.

Definition at line 1715 of file handler.hpp.

◆ parallel_for() [9/18]

template<typename KernelName = detail::auto_name, int Dims, typename... RestT>
std::enable_if_t< (sizeof...(RestT) >= 3 && ext::oneapi::detail::AreAllButLastReductions<RestT...>::value)> cl::sycl::handler::parallel_for ( nd_range< Dims >  Range,
RestT...  Rest 
)
inline

◆ parallel_for() [10/18]

void cl::sycl::handler::parallel_for ( range< 1 >  NumWorkItems,
kernel  Kernel 
)
inline

Definition at line 1967 of file handler.hpp.

◆ parallel_for() [11/18]

template<typename KernelName = detail::auto_name, typename KernelType >
void cl::sycl::handler::parallel_for ( range< 1 >  NumWorkItems,
KernelType  KernelFunc 
)
inline

◆ parallel_for() [12/18]

void cl::sycl::handler::parallel_for ( range< 2 >  NumWorkItems,
kernel  Kernel 
)
inline

Definition at line 1971 of file handler.hpp.

◆ parallel_for() [13/18]

template<typename KernelName = detail::auto_name, typename KernelType >
void cl::sycl::handler::parallel_for ( range< 2 >  NumWorkItems,
KernelType  KernelFunc 
)
inline

Definition at line 1454 of file handler.hpp.

◆ parallel_for() [14/18]

void cl::sycl::handler::parallel_for ( range< 3 >  NumWorkItems,
kernel  Kernel 
)
inline

Definition at line 1975 of file handler.hpp.

◆ parallel_for() [15/18]

template<typename KernelName = detail::auto_name, typename KernelType >
void cl::sycl::handler::parallel_for ( range< 3 >  NumWorkItems,
KernelType  KernelFunc 
)
inline

Definition at line 1463 of file handler.hpp.

◆ parallel_for() [16/18]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void cl::sycl::handler::parallel_for ( range< Dims >  NumWorkItems,
id< Dims >  WorkItemOffset,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Defines and invokes a SYCL kernel function for the specified range and offset.

The SYCL kernel function is defined as a lambda function or a named function object type and given an id or item for indexing in the indexing space defined by range. If it is a named function object and the function object type is globally visible, there is no need for the developer to provide a kernel name for it.

Parameters
NumWorkItemsis a range defining indexing space.
WorkItemOffsetis an offset to be applied to each work item index.
KernelFuncis a SYCL kernel function.

Definition at line 1523 of file handler.hpp.

◆ parallel_for() [17/18]

template<int Dims>
void cl::sycl::handler::parallel_for ( range< Dims >  NumWorkItems,
id< Dims >  WorkItemOffset,
kernel  Kernel 
)
inline

Defines and invokes a SYCL kernel function for the specified range and offsets.

The SYCL kernel function is defined as SYCL kernel object.

Parameters
NumWorkItemsis a range defining indexing space.
WorkItemOffsetis an offset to be applied to each work item index.
Kernelis a SYCL kernel function.

Definition at line 1989 of file handler.hpp.

References cl::sycl::detail::getSyclObjImpl().

◆ parallel_for() [18/18]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims, typename Reduction >
void cl::sycl::handler::parallel_for ( range< Dims >  Range,
Reduction  Redu,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Defines and invokes a SYCL kernel function for the specified nd_range.

The SYCL kernel function is defined as a lambda function or a named function object type and given an id for indexing in the indexing space defined by range Range. The parameter Redu contains the object creted by the reduction() function and defines the type and operation used in the corresponding argument of 'reducer' type passed to lambda/functor function.

Definition at line 1588 of file handler.hpp.

References cl::sycl::ext::oneapi::detail::reduGetMaxNumConcurrentWorkGroups(), and cl::sycl::ext::oneapi::detail::reduGetMaxWGSize().

◆ parallel_for_Impl()

template<typename KernelName , typename KernelType , int Dims, typename Reduction >
detail::enable_if_t<!Reduction::has_fast_atomics> cl::sycl::handler::parallel_for_Impl ( nd_range< Dims >  Range,
Reduction  Redu,
KernelType  KernelFunc 
)
inline

◆ parallel_for_work_group() [1/4]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void cl::sycl::handler::parallel_for_work_group ( kernel  Kernel,
range< Dims >  NumWorkGroups,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Hierarchical kernel invocation method of a kernel.

This version of parallel_for_work_group takes two parameters representing the same kernel. The first one - Kernel - is a compiled form of the second one - kernelFunc, which is the source form of the kernel. The same source kernel can be compiled multiple times yielding multiple kernel class objects accessible via the program class interface.

Parameters
Kernelis a compiled SYCL kernel.
NumWorkGroupsis a range describing the number of work-groups in each dimension.
KernelFuncis a lambda representing kernel.

Definition at line 2190 of file handler.hpp.

References cl::sycl::kernel::get_kernel_bundle(), and cl::sycl::detail::getSyclObjImpl().

◆ parallel_for_work_group() [2/4]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void cl::sycl::handler::parallel_for_work_group ( kernel  Kernel,
range< Dims >  NumWorkGroups,
range< Dims >  WorkGroupSize,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Hierarchical kernel invocation method of a kernel.

This version of parallel_for_work_group takes two parameters representing the same kernel. The first one - Kernel - is a compiled form of the second one - kernelFunc, which is the source form of the kernel. The same source kernel can be compiled multiple times yielding multiple kernel class objects accessible via the program class interface.

Parameters
Kernelis a compiled SYCL kernel.
NumWorkGroupsis a range describing the number of work-groups in each dimension.
WorkGroupSizeis a range describing the size of work-groups in each dimension.
KernelFuncis a lambda representing kernel.

Definition at line 2229 of file handler.hpp.

References cl::sycl::kernel::get_kernel_bundle(), and cl::sycl::detail::getSyclObjImpl().

◆ parallel_for_work_group() [3/4]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void cl::sycl::handler::parallel_for_work_group ( range< Dims >  NumWorkGroups,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Hierarchical kernel invocation method of a kernel defined as a lambda encoding the body of each work-group to launch.

Lambda may contain multiple calls to parallel_for_work_item(...) methods representing the execution on each work-item. Launches NumWorkGroups work-groups of runtime-defined size.

Parameters
NumWorkGroupsis a range describing the number of work-groups in each dimension.
KernelFuncis a lambda representing kernel.

Definition at line 1893 of file handler.hpp.

◆ parallel_for_work_group() [4/4]

template<typename KernelName = detail::auto_name, typename KernelType , int Dims>
void cl::sycl::handler::parallel_for_work_group ( range< Dims >  NumWorkGroups,
range< Dims >  WorkGroupSize,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Hierarchical kernel invocation method of a kernel defined as a lambda encoding the body of each work-group to launch.

Lambda may contain multiple calls to parallel_for_work_item(...) methods representing the execution on each work-item. Launches NumWorkGroups work-groups of WorkGroupSize size.

Parameters
NumWorkGroupsis a range describing the number of work-groups in each dimension.
WorkGroupSizeis a range describing the size of work-groups in each dimension.
KernelFuncis a lambda representing kernel.

Definition at line 1925 of file handler.hpp.

◆ prefetch()

void cl::sycl::handler::prefetch ( const void *  Ptr,
size_t  Count 
)

Provides hints to the runtime library that data should be made available on a device earlier than Unified Shared Memory would normally require it to be available.

Parameters
Ptris a USM pointer to the memory to be prefetched to the device.
Countis a number of bytes to be prefetched.

Definition at line 720 of file handler.cpp.

References cl::sycl::detail::CG::PrefetchUSM.

Referenced by cl::sycl::queue::prefetch().

◆ require()

template<typename DataT , int Dims, access::mode AccMode, access::target AccTarget>
void cl::sycl::handler::require ( accessor< DataT, Dims, AccMode, AccTarget, access::placeholder::true_t Acc)
inline

Requires access to the memory object associated with the placeholder accessor.

The command group has a requirement to gain access to the given memory object before executing.

Parameters
Accis a SYCL accessor describing required memory region.

Definition at line 1348 of file handler.hpp.

References cl::sycl::detail::associateWithHandler().

◆ set_arg() [1/2]

template<typename DataT , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder>
void cl::sycl::handler::set_arg ( int  ArgIndex,
accessor< DataT, Dims, AccessMode, AccessTarget, IsPlaceholder >  Arg 
)
inline

Definition at line 1401 of file handler.hpp.

◆ set_arg() [2/2]

template<typename T >
detail::enable_if_t<ShouldEnableSetArg<T>::value, void> cl::sycl::handler::set_arg ( int  ArgIndex,
T &&  Arg 
)
inline

Sets argument for OpenCL interoperability kernels.

Registers Arg passed as argument # ArgIndex.

Parameters
ArgIndexis a positional number of argument to be set.
Argis an argument value to be set.

Definition at line 1394 of file handler.hpp.

◆ set_args()

template<typename... Ts>
void cl::sycl::handler::set_args ( Ts &&...  Args)
inline

Sets arguments for OpenCL interoperability kernels.

Registers pack of arguments(Args) with indexes starting from 0.

Parameters
Argsare argument values to be set.

Definition at line 1411 of file handler.hpp.

◆ single_task() [1/3]

void cl::sycl::handler::single_task ( kernel  Kernel)
inline

Invokes a SYCL kernel.

Executes exactly once. The kernel invocation method has no functors and cannot be called on host.

Parameters
Kernelis a SYCL kernel object.

Definition at line 1953 of file handler.hpp.

References cl::sycl::kernel::get_kernel_bundle(), and cl::sycl::detail::getSyclObjImpl().

◆ single_task() [2/3]

template<typename KernelName = detail::auto_name, typename KernelType >
void cl::sycl::handler::single_task ( kernel  Kernel,
_KERNELFUNCPARAM(KernelFunc  
)
inline

Defines and invokes a SYCL kernel function.

Parameters
Kernelis a SYCL kernel that is executed on a SYCL device (except for the host device).
KernelFuncis a lambda that is used if device, queue is bound to, is a host device.

Definition at line 2027 of file handler.hpp.

References cl::sycl::kernel::get_kernel_bundle(), and cl::sycl::detail::getSyclObjImpl().

◆ single_task() [3/3]

template<typename KernelName = detail::auto_name, typename KernelType >
void cl::sycl::handler::single_task ( KernelType  KernelFunc)
inline

Defines and invokes a SYCL kernel function as a function object type.

If it is a named function object and the function object type is globally visible, there is no need for the developer to provide a kernel name for it.

Parameters
KernelFuncis a SYCL kernel function.

Definition at line 1424 of file handler.hpp.

Referenced by cl::sycl::ext::oneapi::detail::reduSaveFinalResultToUserMem().

◆ update_host()

template<typename T , int Dims, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder = access::placeholder::false_t>
void cl::sycl::handler::update_host ( accessor< T, Dims, AccessMode, AccessTarget, IsPlaceholder >  Acc)
inline

Provides guarantees that the memory object accessed via Acc is updated on the host after command group object execution is complete.

Parameters
Accis a SYCL accessor that needs to be updated on host.

Definition at line 2444 of file handler.hpp.

References cl::sycl::detail::getSyclObjImpl().

◆ use_kernel_bundle()

void cl::sycl::handler::use_kernel_bundle ( const kernel_bundle< bundle_state::executable > &  ExecBundle)

Friends And Related Function Documentation

◆ ::MockHandler

friend class ::MockHandler
friend

Definition at line 2688 of file handler.hpp.

◆ accessor

template<typename DataT , int Dims, access::mode AccMode, access::target AccTarget, access::placeholder isPlaceholder, typename PropertyListT >
friend class accessor
friend

Definition at line 2662 of file handler.hpp.

◆ detail::associateWithHandler

◆ detail::getDeviceFromHandler

◆ detail::image_accessor

template<typename DataT , int Dimensions, access::mode AccessMode, access::target AccessTarget, access::placeholder IsPlaceholder>
friend class detail::image_accessor
friend

Definition at line 2667 of file handler.hpp.

◆ detail::queue_impl

Definition at line 2657 of file handler.hpp.

◆ detail::stream_impl

friend class detail::stream_impl
friend

Definition at line 2670 of file handler.hpp.

◆ ext::oneapi::detail::reduction_impl

template<typename T , class BinaryOperation , int Dims, bool IsUSM, access::placeholder IsPlaceholder>
friend class ext::oneapi::detail::reduction_impl
friend

Definition at line 2675 of file handler.hpp.

◆ stream

friend class stream
friend

Definition at line 2669 of file handler.hpp.


The documentation for this class was generated from the following files:
cl::sycl::queue::submit
event submit(T CGF _CODELOCPARAM(&CodeLoc))
Submits a command group function object to the queue, in order to be scheduled for execution on the d...
Definition: queue.hpp:251