Compute Library
 21.05
CLScheduler.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2021 Arm Limited.
3  *
4  * SPDX-License-Identifier: MIT
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in all
14  * copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22  * SOFTWARE.
23  */
24 #ifndef ARM_COMPUTE_CLSCHEDULER_H
25 #define ARM_COMPUTE_CLSCHEDULER_H
26 
30 #include "arm_compute/core/Error.h"
31 #include "arm_compute/core/Types.h"
37 
38 namespace arm_compute
39 {
40 class ICLKernel;
41 class ICLTuner;
42 /** Provides global access to a CL context and command queue. */
43 class CLScheduler final
44 {
45 public:
46  /** Constructor */
47  CLScheduler();
48  /** Prevent instances of this class from being copied (As this class contains pointers) */
49  CLScheduler(const CLScheduler &) = delete;
50  /** Prevent instances of this class from being copied (As this class contains pointers) */
51  CLScheduler &operator=(const CLScheduler &) = delete;
52  /** Default destructor */
53  ~CLScheduler() = default;
54  /** Access the scheduler singleton.
55  * This method has been deprecated and will be removed in future releases
56  * @return The scheduler
57  */
58  static CLScheduler &get();
59  /** Initialises the context and command queue used by the scheduler to default values
60  * and sets a default device and kernel path for the @ref CLKernelLibrary.
61  *
62  * @param[in] cl_tuner (Optional) Pointer to ICLTuner (default=nullptr)
63  * @param[in] gemm_h (Optional) Pointer to CLGEMMHeuristicsHandle (default = nullptr)
64  * @param[in] cl_backend_type (Optional) Type of backend to use (default = CLBackendType::Native)
65  */
66  void default_init(ICLTuner *cl_tuner = nullptr, CLGEMMHeuristicsHandle *gemm_h = nullptr, CLBackendType cl_backend_type = CLBackendType::Native);
67  /** Initialises the scheduler with context and device provided by the user
68  *
69  * @param[in] device OpenCL device to be used
70  * @param[in] ctx OpenCL ctx to be used
71  * @param[in] cl_tuner (Optional) Pointer to ICLTuner (default=nullptr)
72  * @param[in] gemm_h (Optional) Pointer to CLGEMMHeuristicsHandle (default = nullptr)
73  */
74  void default_init_with_context(cl::Device &device, cl::Context &ctx, ICLTuner *cl_tuner = nullptr, CLGEMMHeuristicsHandle *gemm_h = nullptr);
75 
76  /** Schedule the execution of the passed kernel if possible.
77  *
78  * @param[in] kernel Kernel to execute.
79  * @param[in] flush (Optional) Specifies if the command queue will be flushed after running the kernel.
80  */
81  void enqueue(ICLKernel &kernel, bool flush = true);
82  /** Schedule the execution of the passed kernel if possible.
83  *
84  * @param[in] kernel Kernel to execute.
85  * @param[in] tensors Vector containing the tensors to operate on.
86  * @param[in] flush (Optional) Specifies if the command queue will be flushed after running the kernel.
87  */
88  void enqueue_op(ICLKernel &kernel, ITensorPack &tensors, bool flush = true);
89 
90  /** Initialises the context and command queue to be used by the scheduler.
91  *
92  * @param[in] context A CL context.
93  * @param[in] queue A CL command queue.
94  * @param[in] device A CL device.
95  * @param[in] cl_tuner (Optional) Pointer to OpenCL tuner (default=nullptr)
96  * Note: It is caller's responsibility to release the allocated memory for CLTuner
97  * @param[in] gemm_h (Optional) Pointer to CLGEMMHeuristicsHandle (default = nullptr)
98  * @param[in] cl_backend_type (Optional) Type of backend to use (default = CLBackendType::Native)
99  */
100  void init(cl::Context context, cl::CommandQueue queue, const cl::Device &device, ICLTuner *cl_tuner = nullptr, CLGEMMHeuristicsHandle *gemm_h = nullptr,
101  CLBackendType cl_backend_type = CLBackendType::Native);
102 
103  /** Accessor for the associated CL context.
104  *
105  * @return A CL context.
106  */
107  cl::Context &context();
108 
109  /** Accessor for the associated CL command queue.
110  *
111  * @return A CL command queue.
112  */
113  cl::CommandQueue &queue();
114 
115  /** Get the target GPU.
116  *
117  * @return The target GPU.
118  */
119  GPUTarget target() const;
120 
121  /** Accessor for the associated CLGEMMHeuristicsHandle
122  *
123  * @return Pointer to CLGEMMHeuristicsHandle
124  */
126 
127  /** Accessor to set the CL context to be used by the scheduler.
128  *
129  * @param[in] context A CL context.
130  */
131  void set_context(cl::Context context);
132 
133  /** Accessor to set the CL command queue to be used by the scheduler.
134  *
135  * @param[in] queue A CL command queue.
136  */
137  void set_queue(cl::CommandQueue queue);
138 
139  /** Accessor to set target GPU to be used by the scheduler.
140  *
141  * @param[in] target The target GPU.
142  */
144 
145  /** Accessor to set the CL tuner to be used by the scheduler.
146  *
147  * @param[in] tuner A CL tuner
148  */
149  void set_tuner(ICLTuner *tuner);
150 
151  /** Blocks until all commands in the associated command queue have finished. */
152  void sync();
153 
154  /** Enqueues a marker into the associated command queue and return the event.
155  *
156  * @return An event that can be waited on to block the executing thread.
157  */
158  cl::Event enqueue_sync_event();
159 
160  /** Tunes OpenCL kernel
161  *
162  * @param[in] kernel Kernel to tune
163  */
164  void tune_kernel_static(ICLKernel &kernel);
165 
166  bool is_initialised() const;
167 
168 private:
169  void enqueue_common(ICLKernel &kernel, ITensorPack &tensors, bool flush);
170  /** Flag to ensure symbols initialisation is happening before Scheduler creation */
171  static std::once_flag _initialize_symbols;
172 
173  cl::Context _context;
174  cl::CommandQueue _queue;
175  GPUTarget _target;
176  bool _is_initialised;
177  ICLTuner *_cl_tuner;
178  CLGEMMHeuristicsHandle *_gemm_heuristics;
179  CLBackendType _backend_type;
180 };
181 } // namespace arm_compute
182 #endif /* ARM_COMPUTE_CLSCHEDULER_H */
void set_target(GPUTarget target)
Accessor to set target GPU to be used by the scheduler.
Definition: CLScheduler.cpp:60
static CLScheduler & get()
Access the scheduler singleton.
GPUTarget target() const
Get the target GPU.
Definition: CLScheduler.cpp:45
void set_context(cl::Context context)
Accessor to set the CL context to be used by the scheduler.
void default_init_with_context(cl::Device &device, cl::Context &ctx, ICLTuner *cl_tuner=nullptr, CLGEMMHeuristicsHandle *gemm_h=nullptr)
Initialises the scheduler with context and device provided by the user.
void default_init(ICLTuner *cl_tuner=nullptr, CLGEMMHeuristicsHandle *gemm_h=nullptr, CLBackendType cl_backend_type=CLBackendType::Native)
Initialises the context and command queue used by the scheduler to default values and sets a default ...
CLScheduler & operator=(const CLScheduler &)=delete
Prevent instances of this class from being copied (As this class contains pointers)
~CLScheduler()=default
Default destructor.
bool is_initialised() const
Definition: CLScheduler.cpp:90
Common interface for all the OpenCL kernels.
Definition: ICLKernel.h:46
CLGEMMHeuristicsHandle * gemm_heuristics() const
Accessor for the associated CLGEMMHeuristicsHandle.
Definition: CLScheduler.cpp:50
Copyright (c) 2017-2021 Arm Limited.
cl::Context & context()
Accessor for the associated CL context.
Definition: CLScheduler.cpp:32
cl::Event enqueue_sync_event()
Enqueues a marker into the associated command queue and return the event.
Definition: CLScheduler.cpp:75
Interface used to tune the local work-group size of OpenCL kernels.
void enqueue_op(ICLKernel &kernel, ITensorPack &tensors, bool flush=true)
Schedule the execution of the passed kernel if possible.
void set_tuner(ICLTuner *tuner)
Accessor to set the CL tuner to be used by the scheduler.
Definition: CLScheduler.cpp:65
cl::CommandQueue & queue()
Accessor for the associated CL command queue.
Definition: CLScheduler.cpp:39
void enqueue(ICLKernel &kernel, bool flush=true)
Schedule the execution of the passed kernel if possible.
void set_queue(cl::CommandQueue queue)
Accessor to set the CL command queue to be used by the scheduler.
Definition: CLScheduler.cpp:55
CLScheduler()
Constructor.
Definition: CLScheduler.cpp:97
void sync()
Blocks until all commands in the associated command queue have finished.
Definition: CLScheduler.cpp:70
Handle for loading and retrieving GEMM heuristics.
CLBackendType
List the possible OpenCL backends.
Definition: CLTypes.h:63
GPUTarget
Available GPU Targets.
Definition: GPUTarget.h:34
Provides global access to a CL context and command queue.
Definition: CLScheduler.h:43
Wrapper to configure the Khronos OpenCL C++ header.
Tensor packing service.
Definition: ITensorPack.h:37
Basic interface for tuning the OpenCL kernels.
Definition: ICLTuner.h:34
void tune_kernel_static(ICLKernel &kernel)
Tunes OpenCL kernel.
Definition: CLScheduler.cpp:82
void init(cl::Context context, cl::CommandQueue queue, const cl::Device &device, ICLTuner *cl_tuner=nullptr, CLGEMMHeuristicsHandle *gemm_h=nullptr, CLBackendType cl_backend_type=CLBackendType::Native)
Initialises the context and command queue to be used by the scheduler.