mysql_handler/engine/
cost_estimate.rs

1// Copyright (C) 2026 ren-yamanashi
2//
3// This program is free software; you can redistribute it and/or modify
4// it under the terms of the GNU General Public License, version 2.0,
5// as published by the Free Software Foundation.
6//
7// This program is designed to work with certain software (including
8// but not limited to OpenSSL) that is licensed under separate terms,
9// as designated in a particular file or component or in included license
10// documentation. The authors of this program hereby grant you an additional
11// permission to link the program and your derivative works with the
12// separately licensed software that they have either included with
13// the program or referenced in the documentation.
14//
15// This program is distributed in the hope that it will be useful,
16// but WITHOUT ANY WARRANTY; without even the implied warranty of
17// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18// GNU General Public License for more details.
19//
20// You should have received a copy of the GNU General Public License
21// along with this program; if not, see <https://www.gnu.org/licenses/>.
22
23//! Cost-estimate value an engine reports for the optimizer's cost methods.
24
25/// A cost estimate an engine reports to the optimizer, mirroring MySQL's
26/// `Cost_estimate`.
27///
28/// The first three components are time-consuming costs the optimizer sums to
29/// compare access paths: I/O, CPU, and import (remote) cost. The fourth,
30/// memory cost, tracks bytes the engine expects to allocate and is kept apart
31/// from the time-based total. All four use MySQL's internal cost units.
32///
33/// Returned as `Some` from [`table_scan_cost`], [`index_scan_cost`], and
34/// [`read_cost`]; the shim assembles a `Cost_estimate` from the components.
35/// This is distinct from the opaque [`crate::sys::CostEstimate`], which is a
36/// borrowed handle to a live MySQL accumulator the binding cannot construct.
37///
38/// [`table_scan_cost`]: crate::engine::StorageEngine::table_scan_cost
39/// [`index_scan_cost`]: crate::engine::StorageEngine::index_scan_cost
40/// [`read_cost`]: crate::engine::StorageEngine::read_cost
41///
42/// # Examples
43///
44/// ```
45/// use mysql_handler::engine::CostEstimate;
46///
47/// let cost = CostEstimate::new(10.0, 2.0, 0.0, 0.0);
48/// assert_eq!(cost.io_cost(), 10.0);
49/// assert_eq!(cost.cpu_cost(), 2.0);
50/// ```
51#[derive(Debug, Clone, Copy, PartialEq)]
52#[non_exhaustive]
53pub struct CostEstimate {
54    io: f64,
55    cpu: f64,
56    import: f64,
57    mem: f64,
58}
59
60impl CostEstimate {
61    /// Build a cost estimate from its I/O, CPU, import, and memory components,
62    /// each in MySQL's internal cost units.
63    #[must_use]
64    pub const fn new(io_cost: f64, cpu_cost: f64, import_cost: f64, mem_cost: f64) -> Self {
65        Self {
66            io: io_cost,
67            cpu: cpu_cost,
68            import: import_cost,
69            mem: mem_cost,
70        }
71    }
72
73    /// Cost of the I/O operations the access path performs.
74    #[must_use]
75    pub const fn io_cost(&self) -> f64 {
76        self.io
77    }
78
79    /// Cost of the CPU work the access path performs.
80    #[must_use]
81    pub const fn cpu_cost(&self) -> f64 {
82        self.cpu
83    }
84
85    /// Cost of remote (import) operations the access path performs.
86    #[must_use]
87    pub const fn import_cost(&self) -> f64 {
88        self.import
89    }
90
91    /// Memory the access path expects to use, in bytes.
92    #[must_use]
93    pub const fn mem_cost(&self) -> f64 {
94        self.mem
95    }
96}
97
98#[cfg(test)]
99mod tests {
100    use super::CostEstimate;
101
102    #[test]
103    fn accessors_return_constructor_components() {
104        let cost = CostEstimate::new(1.5, 2.5, 3.5, 4.5);
105        assert_eq!(cost.io_cost().to_bits(), 1.5_f64.to_bits());
106        assert_eq!(cost.cpu_cost().to_bits(), 2.5_f64.to_bits());
107        assert_eq!(cost.import_cost().to_bits(), 3.5_f64.to_bits());
108        assert_eq!(cost.mem_cost().to_bits(), 4.5_f64.to_bits());
109    }
110}
mysql_handler/engine/cost_estimate.rs

mysql_handler/engine/
cost_estimate.rs
