cubecl_runtime/tune/
operation.rs

1use alloc::boxed::Box;
2use alloc::string::String;
3use alloc::sync::Arc;
4use alloc::vec::Vec;
5use core::fmt::{Debug, Display};
6use core::hash::Hash;
7use cubecl_common::hash::StableHasher;
8
9use alloc::format;
10
11use crate::tune::{Bounds, BoundsGenerator, Eviction, Evictor};
12
13use super::{
14    AutotuneError, input_generator::InputGenerator, key_generator::KeyGenerator,
15    tune_inputs::TuneInputs,
16};
17use super::{Tunable, TunePlan};
18
19/// A type-erased delegate for a tunable function.
20///
21/// The lifetime `'inp` is the lifetime of the input data, the function must be defined such that
22/// it can be called for any lifetime `inp` and produce a `Result<Out, AutotuneError>`.
23type TuneDelegate<I, Out> =
24    dyn for<'inp> Fn(<I as TuneInputs>::At<'inp>) -> Result<Out, AutotuneError> + Send + Sync;
25
26/// A named, type-erased tunable function stored in a [`TunableSet`]. Constructed via
27/// [`Tunable::new`](super::Tunable::new); callers don't name this type directly.
28#[derive(new)]
29pub struct TuneFn<I: TuneInputs, Out> {
30    pub(crate) name: String,
31    func: Box<TuneDelegate<I, Out>>,
32}
33
34impl<I: TuneInputs, Out: 'static> TuneFn<I, Out> {
35    /// Run the wrapped function on the given inputs.
36    pub fn execute<'a>(&self, inputs: <I as TuneInputs>::At<'a>) -> Result<Out, AutotuneError> {
37        (self.func)(inputs)
38    }
39}
40
41/// A set of candidate tunable functions for autotune, sharing a key generator and an
42/// input generator. See [`TuneInputs`] for the `F` parameter.
43pub struct TunableSet<K: AutotuneKey, F: TuneInputs, Output: 'static> {
44    tunables: Vec<Tunable<K, F, Output>>,
45    key_gen: Arc<dyn KeyGenerator<K, F> + Send + Sync>,
46    input_gen: Arc<dyn InputGenerator<K, F> + Send + Sync>,
47    bounds_gen: Option<Arc<dyn BoundsGenerator<K, F> + Send + Sync>>,
48    eviction: Option<Arc<dyn Eviction<K, F> + Send + Sync>>,
49    short_circuit: bool,
50}
51
52impl<K: AutotuneKey, F: TuneInputs, Output: 'static> TunableSet<K, F, Output> {
53    /// The number of tunables in the set.
54    pub fn len(&self) -> usize {
55        self.tunables.len()
56    }
57
58    /// Whether this set contains no tunables.
59    pub fn is_empty(&self) -> bool {
60        self.tunables.is_empty()
61    }
62
63    /// Create a tunable set from a key generator and an input generator.
64    pub fn new(key_gen: impl KeyGenerator<K, F>, input_gen: impl InputGenerator<K, F>) -> Self {
65        Self {
66            tunables: Default::default(),
67            input_gen: Arc::new(input_gen),
68            key_gen: Arc::new(key_gen),
69            bounds_gen: None,
70            eviction: None,
71            short_circuit: true,
72        }
73    }
74
75    /// Shorthand for [`new`](Self::new) with a [`CloneInputGenerator`]: benchmarks run
76    /// on clones of the real call inputs.
77    pub fn new_cloning_inputs(key_gen: impl KeyGenerator<K, F>) -> Self {
78        Self::new(key_gen, super::CloneInputGenerator)
79    }
80
81    /// Register a tunable with this tunable set.
82    pub fn with(mut self, tunable: Tunable<K, F, Output>) -> Self {
83        self.tunables.push(tunable);
84        self
85    }
86
87    /// Sets the autotune bounds for this set.
88    pub fn with_bounds(mut self, bounds: Arc<dyn BoundsGenerator<K, F> + Send + Sync>) -> Self {
89        self.bounds_gen = Some(bounds);
90        self
91    }
92
93    /// Sets what runs before every measured sample, so the candidates are timed reading
94    /// memory rather than the cache the previous sample left warm. See [`Eviction`].
95    pub fn with_eviction(mut self, eviction: Arc<dyn Eviction<K, F> + Send + Sync>) -> Self {
96        self.eviction = Some(eviction);
97        self
98    }
99
100    /// Set whether bounds-based short-circuiting is enabled.
101    pub fn with_short_circuit(mut self, enabled: bool) -> Self {
102        self.short_circuit = enabled;
103        self
104    }
105
106    /// Whether short-circuiting is enabled for this set.
107    pub fn is_short_circuit_enabled(&self) -> bool {
108        self.short_circuit
109    }
110
111    /// All candidate operations in this set, in registration order.
112    pub fn autotunables(&self) -> impl Iterator<Item = &TuneFn<F, Output>> {
113        self.tunables.iter().map(|tunable| &tunable.function)
114    }
115
116    /// Returns the [autotune plan](TunePlan) for the given set.
117    pub(crate) fn plan(&self, key: &K) -> TunePlan {
118        TunePlan::new(key, &self.tunables)
119    }
120
121    /// Returns the operation for the given index, matching the order returned by
122    /// `autotunables`. Tunables are tried in order, so index 0 should be a good default.
123    pub fn fastest(&self, fastest_index: usize) -> &TuneFn<F, Output> {
124        &self.tunables[fastest_index].function
125    }
126
127    /// Compute a checksum that invalidates outdated cached auto-tune results when the
128    /// set of tunable names changes.
129    pub fn compute_checksum(&self) -> String {
130        let mut checksum = String::new();
131        for tune in &self.tunables {
132            checksum += &tune.function.name;
133        }
134        format!("{:x}", StableHasher::hash_one(&checksum))
135    }
136
137    /// Generate a key from a set of inputs
138    pub fn generate_key<'a>(&self, inputs: &F::At<'a>) -> K {
139        self.key_gen.generate(inputs)
140    }
141
142    /// Generate a set of test inputs from a key and reference inputs.
143    pub fn generate_inputs<'a>(&self, key: &K, inputs: &F::At<'a>) -> F::At<'a> {
144        self.input_gen.generate(key, inputs)
145    }
146
147    /// The eviction registered on this set, bound to `key` and the reference `inputs`, if
148    /// any: what a benchmark loop runs before each of its samples.
149    pub(crate) fn evictor<'i>(&self, key: &K, inputs: &F::At<'i>) -> Option<Box<Evictor<'i>>> {
150        let eviction = self.eviction.clone()?;
151        let key = key.clone();
152        let inputs = inputs.clone();
153        Some(Box::new(move || eviction.evict(&key, &inputs)))
154    }
155
156    /// The throughput bounds registered on this set, if any.
157    pub fn bounds(&self, key: &K, inputs: &F::At<'_>) -> Option<Bounds> {
158        self.bounds_gen.as_ref().map(|f| f.generate(key, inputs))
159    }
160}
161
162#[cfg(serializable)]
163/// Trait alias, serializable for the persistent cache and the autotune log
164pub trait AutotuneKey:
165    Clone
166    + Debug
167    + PartialEq
168    + Eq
169    + Hash
170    + Display
171    + serde::Serialize
172    + serde::de::DeserializeOwned
173    + Send
174    + Sync
175    + 'static
176{
177}
178#[cfg(not(serializable))]
179/// Trait alias
180pub trait AutotuneKey:
181    Clone + Debug + PartialEq + Eq + Hash + Display + Send + Sync + 'static
182{
183}
184
185impl AutotuneKey for String {}
cubecl_runtime/tune/operation.rs

cubecl_runtime/tune/
operation.rs
