1/* Copyright 2019 Google LLC. All Rights Reserved.
2
3Licensed under the Apache License, Version 2.0 (the "License");
4you may not use this file except in compliance with the License.
5You may obtain a copy of the License at
6
7 http://www.apache.org/licenses/LICENSE-2.0
8
9Unless required by applicable law or agreed to in writing, software
10distributed under the License is distributed on an "AS IS" BASIS,
11WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12See the License for the specific language governing permissions and
13limitations 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
23namespace ruy {
24
25class Ctx;
26class CtxImpl;
27class ThreadPool;
28enum class Path : std::uint8_t;
29enum class Tuning;
30enum 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.
37class 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