1 | /* Copyright 2019 Google LLC. All Rights Reserved. |
2 | |
3 | Licensed under the Apache License, Version 2.0 (the "License"); |
4 | you may not use this file except in compliance with the License. |
5 | You may obtain a copy of the License at |
6 | |
7 | http://www.apache.org/licenses/LICENSE-2.0 |
8 | |
9 | Unless required by applicable law or agreed to in writing, software |
10 | distributed under the License is distributed on an "AS IS" BASIS, |
11 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
12 | See the License for the specific language governing permissions and |
13 | limitations under the License. |
14 | ==============================================================================*/ |
15 | |
16 | // Context is the user-facing context class. |
17 | |
18 | #ifndef RUY_RUY_CONTEXT_H_ |
19 | #define RUY_RUY_CONTEXT_H_ |
20 | |
21 | #include <cstdint> |
22 | |
23 | namespace ruy { |
24 | |
25 | class Ctx; |
26 | class CtxImpl; |
27 | class ThreadPool; |
28 | enum class Path : std::uint8_t; |
29 | enum class Tuning; |
30 | enum class PerformanceAdvisory; |
31 | |
32 | // A Context holds runtime information used by Ruy. It holds runtime resources |
33 | // such as the workers thread pool and the allocator (which holds buffers for |
34 | // temporary data), as well as runtime options controlling which Paths are |
35 | // enabled (typically based on which instruction sets are detected) and how |
36 | // many threads to use. |
37 | class Context final { |
38 | public: |
39 | Context(); |
40 | ~Context(); |
41 | |
42 | // Returns the Path enum value that corresponds to the code path used by |
43 | // the last ruy::Mul with this Context. |
44 | Path last_used_path() const; |
45 | |
46 | // Control of whether to use kernels tuned for in-order or out-of-order CPU |
47 | // cores. The default is auto-detection, so these methods should only be used |
48 | // to override that auto-detection if it's not working as intended or for |
49 | // testing. |
50 | Tuning explicit_tuning() const; |
51 | void set_explicit_tuning(Tuning value); |
52 | |
53 | // The thread pool held by this context to dispatch a ruy::Mul to worker |
54 | // threads. |
55 | // |
56 | // By default, threads may spin-wait for a few milliseconds before reverting |
57 | // to passive wait. This can be controlled by |
58 | // `mutable_thread_pool()->set_spin_milliseconds(value)`. |
59 | const ThreadPool& thread_pool() const; |
60 | ThreadPool* mutable_thread_pool(); |
61 | |
62 | // Controls the maximum number of threads to be used by ruy::Mul with this |
63 | // Context. The number of threads in the pool will be that value minus one, |
64 | // as the remaining portion of the work is done directly on the calling |
65 | // thread. |
66 | // |
67 | // This defaults to 1. Multi-threading in ruy is always opt-in. There is |
68 | // no auto-detection of hardware concurrency. That is on purpose, ruy focuses |
69 | // on mobile applications where such concepts are difficult to define |
70 | // (e.g. ARM big.LITTLE). |
71 | int max_num_threads() const; |
72 | void set_max_num_threads(int value); |
73 | |
74 | // Returns true of the last ruy::Mul using this Context flagged the specified |
75 | // `advisory`. This is reset by each ruy::Mul call. |
76 | bool performance_advisory(PerformanceAdvisory advisory) const; |
77 | |
78 | // When using Matrix::set_cache_policy(), this Context will keep a cache of |
79 | // pre-packed matrix data. This function clears that cache. |
80 | void ClearPrepackedCache(); |
81 | |
82 | // Override auto-detection of supported code paths. |
83 | // |
84 | // Passing `paths == Path::kNone` means reverting to the default behavior. |
85 | // This will trigger auto-detection on the next use. |
86 | // |
87 | // Other values will override auto-detection with the explicitly provided set |
88 | // of paths. |
89 | // |
90 | // Paths in kNonArchPaths are always implicitly supported. |
91 | void set_runtime_enabled_paths(Path paths); |
92 | |
93 | // Returns the set of Path's that are available. |
94 | Path get_runtime_enabled_paths(); |
95 | |
96 | private: |
97 | CtxImpl* const impl_; |
98 | |
99 | const Ctx& ctx() const; |
100 | Ctx* mutable_ctx(); |
101 | |
102 | friend const Ctx* get_ctx(const Context*); |
103 | friend Ctx* get_ctx(Context*); |
104 | |
105 | // Disallow copy |
106 | Context(const Context&) = delete; |
107 | }; |
108 | |
109 | } // end namespace ruy |
110 | |
111 | #endif // RUY_RUY_CONTEXT_H_ |
112 | |