lance_core/utils/
io_stats.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright The Lance Authors
3
4use std::ops::Range;
5
6/// A sink that records I/O requests as they are submitted to storage.
7///
8/// This lives in `lance-core` so that the encoding layer (`lance-encoding`) and
9/// the I/O layer (`lance-io`) can both refer to it without depending on one
10/// another.  It lets a caller attach a lightweight counter to a file reader and
11/// measure the exact bytes/IOPS performed for a bounded scope (e.g. a single
12/// query); see `lance_io::scheduler::IoStats` for the concrete implementation.
13///
14/// # When to use this
15///
16/// Lance also exposes two *process-wide, cumulative* I/O accounting facilities:
17/// the global scheduler counters (`lance_io::scheduler::iops_counter` /
18/// `bytes_read_counter`) and the object-store `IOTracker` wrapper used in tests.
19/// Both aggregate every read in the process and cannot attribute I/O to a single
20/// bounded scope.  Prefer an `IoStatsRecorder` when you need the *exact* I/O of
21/// one operation (e.g. a single query): attach it to a reader with
22/// `with_io_stats`, then read the snapshot when the scope ends.  It re-uses the
23/// reader's cached metadata, so measuring costs no extra file opens and does not
24/// disturb the global counters.
25pub trait IoStatsRecorder: std::fmt::Debug + Send + Sync {
26    /// Record one completed request, given the byte ranges as actually
27    /// submitted to storage (i.e. after any coalescing/splitting), so the
28    /// counts reflect physical I/O.
29    fn record_request(&self, ranges: &[Range<u64>]);
30}
lance_core/utils/io_stats.rs

lance_core/utils/
io_stats.rs
