1 /*
2 * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package hat;
26
27
28 import hat.backend.Backend;
29 import hat.buffer.Buffer;
30 import hat.buffer.BufferAllocator;
31 import hat.buffer.BufferTracker;
32 import hat.ifacemapper.BoundSchema;
33 import hat.ifacemapper.SegmentMapper;
34 import hat.optools.OpTk;
35
36 import java.lang.invoke.MethodHandles;
37 import java.lang.reflect.Method;
38
39 import jdk.incubator.code.Op;
40 import jdk.incubator.code.Quotable;
41 import jdk.incubator.code.Quoted;
42 import jdk.incubator.code.dialect.java.JavaOp;
43
44 import java.util.HashMap;
45 import java.util.Map;
46 import java.util.ServiceLoader;
47 import java.util.function.Consumer;
48 import java.util.function.Predicate;
49
50 import static hat.backend.Backend.FIRST;
51
52
53 /**
54 * This class provides the developer facing view of HAT, and wraps a <a href="backend/Backend.html">Backend</a> capable of
55 * executing <b>NDRange</b> style execution.
56 * <p/>
57 * An Accelerator is provided a <a href="java/lang/invoke/MethodHandles.Lookup.html">MethodHandles.Lookup</a> with visibility to the
58 * compute to be performed.
59 * <p/>
60 * As well we either a <a href="backend/Backend.html">Backend</a> directly
61 * <pre>
62 * Accelerator accelerator =
63 * new Accelerator(MethodHandles.lookup(),
64 * new JavaMultiThreadedBackend());
65 * </pre>
66 * or a {@code java.util.function.Predicate<Backend>} which can be used to select the required {@code Backend}
67 * loaded via Javas ServiceLoader mechanism
68 * {@code}
69 * <pre>
70 * Accelerator accelerator =
71 * new Accelerator(MethodHandles.lookup(),
72 * be -> be.name().startsWith("OpenCL));
73 * </pre>}
74 *
75 * @author Gary Frost
76 */
77 public class Accelerator implements BufferAllocator, BufferTracker {
78 public MethodHandles.Lookup lookup;
79 public final Backend backend;
80
81 private final Map<Method, hat.ComputeContext> cache = new HashMap<>();
82
83 public KernelContext range(NDRange ndRange) {
84 return new KernelContext(ndRange);
85 }
86
87 protected Accelerator(MethodHandles.Lookup lookup, ServiceLoader.Provider<Backend> provider) {
88 this(lookup, provider.get());
89 }
90 public Accelerator(MethodHandles.Lookup lookup) {
91 this(lookup, FIRST);
92 }
93
94 /**
95 * @param lookup
96 * @param backend
97 */
98 public Accelerator(MethodHandles.Lookup lookup, Backend backend) {
99 this.lookup = lookup;
100 this.backend = backend;
101 }
102
103 /**
104 * @param lookup
105 * @param backendPredicate
106 */
107 public Accelerator(MethodHandles.Lookup lookup, Predicate<Backend> backendPredicate) {
108 this(lookup, Backend.getBackend(backendPredicate));
109 }
110
111 @Override
112 public <T extends Buffer> T allocate(SegmentMapper<T> segmentMapper, BoundSchema<T> boundShema) {
113 return backend.allocate(segmentMapper, boundShema);
114 }
115
116 @Override
117 public void preMutate(Buffer b) {
118 if (backend instanceof BufferTracker) {
119 ((BufferTracker) backend).preMutate(b);
120 }
121 }
122
123 @Override
124 public void postMutate(Buffer b) {
125 if (backend instanceof BufferTracker) {
126 ((BufferTracker) backend).postMutate(b);
127 }
128 }
129
130 @Override
131 public void preAccess(Buffer b) {
132 if (backend instanceof BufferTracker) {
133 ((BufferTracker) backend).preAccess(b);
134 }
135 }
136
137 @Override
138 public void postAccess(Buffer b) {
139 if (backend instanceof BufferTracker) {
140 ((BufferTracker) backend).postAccess(b);
141 }
142 }
143
144 /**
145 * An interface used for wrapping the compute entrypoint of work to be performed by the Accelerator.
146 * <p/>
147 * So given a ComputeClass such as...
148 * <pre>
149 * public class MyComputeClass {
150 * @ CodeReflection
151 * public static void addDeltaKernel(KernelContext kc, S32Array arrayOfInt, int delta) {
152 * arrayOfInt.array(kc.x, arrayOfInt.array(kc.x)+delta);
153 * }
154 *
155 * @ CodeReflection
156 * static public void doSomeWork(final ComputeContext cc, S32Array arrayOfInt) {
157 * }
158 * }
159 * </pre>
160 * The accelerator will be passed the doSomeWork entrypoint, wrapped in a {@code QuotableComputeContextConsumer}
161 * <pre>
162 * accelerator.compute(cc ->
163 * MyCompute.doSomeWork(cc, arrayOfInt)
164 * );
165 * </pre>
166 */
167 public interface QuotableComputeContextConsumer extends Quotable, Consumer<ComputeContext> {
168 }
169 // convenience
170 public Config config(){
171 return backend.config();
172 }
173
174 /**
175 * This method provides the Accelerator with the {@code Compute Entrypoint} from a Compute class.
176 * <p>
177 * The entrypoint is wrapped in a <a href="QuotableComputeContextConsumer.html">QuotableComputeContextConsumer</a> lambda.
178 *
179 * <pre>
180 * accelerator.compute(cc ->
181 * MyCompute.doSomeWork(cc, intArray)
182 * )
183 * </pre>
184 */
185 public void compute(QuotableComputeContextConsumer quotableComputeContextConsumer) {
186 Quoted quoted = Op.ofQuotable(quotableComputeContextConsumer).orElseThrow();
187 JavaOp.LambdaOp lambda = (JavaOp.LambdaOp) quoted.op();
188 Method method = OpTk.methodOrThrow(lookup,OpTk.getQuotableTargetInvokeOpWrapper(lambda));
189 // Create (or get cached) a compute context which closes over compute entryppint and reachable kernels.
190 // The models of all compute and kernel methods are passed to the backend during creation
191 // The backend may well mutate the models.
192 // It will also use this opportunity to generate ISA specific code for the kernels.
193 ComputeContext computeContext = cache.computeIfAbsent(method, (_) -> new ComputeContext(this, method));
194 // Here we get the captured values from the Quotable
195 Object[] args = OpTk.getQuotableCapturedValues(lambda,quoted, method);
196 args[0] = computeContext;
197 // now ask the backend to execute
198 backend.dispatchCompute(computeContext, args);
199 }
200 }