diff options
Diffstat (limited to 'crates/tor-memquota/src')
| -rw-r--r-- | crates/tor-memquota/src/config.rs | 324 | ||||
| -rw-r--r-- | crates/tor-memquota/src/internal_prelude.rs | 2 | ||||
| -rw-r--r-- | crates/tor-memquota/src/mtracker.rs | 2 |
3 files changed, 303 insertions, 25 deletions
diff --git a/crates/tor-memquota/src/config.rs b/crates/tor-memquota/src/config.rs index 763316b64..cd71a57b1 100644 --- a/crates/tor-memquota/src/config.rs +++ b/crates/tor-memquota/src/config.rs @@ -1,5 +1,10 @@ //! Configuration (private module) +use std::sync::LazyLock; + +use sysinfo::{MemoryRefreshKind, System}; +use tracing::warn; + use crate::internal_prelude::*; /// We want to support at least this many participants with a cache each @@ -21,13 +26,16 @@ define_derive_deftly! { impl ConfigBuilder { $( - ${when approx_equal($ftype, { Option::<Qty> })} + ${when approx_equal($ftype, { Option::<ExplicitOrAuto<Qty>> })} ${fattrs doc} /// /// (Setter method.) - pub fn $fname(&mut self, value: usize) -> &mut Self { - self.$fname = Some(Qty(value)); + // We use `value: impl Into<ExplicitOrAuto<usize>>` to avoid breaking users who used the + // previous `value: usize`. But this isn't 100% foolproof, for example if a user used + // `$fname(foo.into())`, which will fail type inference. + pub fn $fname(&mut self, value: impl Into<ExplicitOrAuto<usize>>) -> &mut Self { + self.$fname = Some(value.into().map(Qty)); self } ) @@ -54,17 +62,26 @@ pub struct Config(pub(crate) IfEnabled<ConfigInner>); pub struct ConfigBuilder { /// Maximum memory usage tolerated before reclamation starts /// - /// Setting this to `usize::MAX` disables the memory quota - /// (and that's the default). + /// Setting this to `usize::MAX` disables the memory quota. + /// + /// The default is "auto", + /// which uses a value derived from the total system memory. + /// It should not be assumed that the value used for "auto" + /// will remain stable across different versions of this library. /// /// Note that this is not a hard limit. /// See Approximate in [the overview](crate). - max: Option<Qty>, + max: Option<ExplicitOrAuto<Qty>>, /// Reclamation will stop when memory use is reduced to below this value /// - /// Default is 75% of the maximum. - low_water: Option<Qty>, + /// Default is "auto", which uses 75% of the maximum. + /// It should not be assumed that the value used for "auto" + /// will remain stable across different versions of this library. + /// + /// If set to an explicit value, + /// then `max` must be set to an explicit value as well. + low_water: Option<ExplicitOrAuto<Qty>>, } /// Configuration, if enabled @@ -77,7 +94,7 @@ pub struct ConfigBuilder { pub(crate) struct ConfigInner { /// Maximum memory usage /// - /// Guaranteed not to be `MAX`, since we're anbled + /// Guaranteed not to be `MAX`, since we're enabled pub max: Qty, /// Low water @@ -98,8 +115,9 @@ impl Config { /// /// Ad-hoc accessor for testing purposes. /// (ideally we'd use `visibility` to make fields `pub`, but that doesn't work.) - #[cfg(feature = "testing")] - pub fn inner(&self) -> Option<&ConfigInner> { + #[cfg(any(test, feature = "testing"))] + #[cfg_attr(feature = "testing", visibility::make(pub))] + fn inner(&self) -> Option<&ConfigInner> { self.0.as_ref().into_enabled() } } @@ -107,21 +125,38 @@ impl Config { impl ConfigBuilder { /// Builds a new `Config` from a builder /// - /// Returns an error unless at least `max` has been specified, - /// or if the fields values are invalid or inconsistent. + /// Returns an error if the fields values are invalid or inconsistent. pub fn build(&self) -> Result<Config, ConfigBuildError> { - let max = self.max.unwrap_or(Qty::MAX); + // both options default to "auto" + let max = self.max.unwrap_or(ExplicitOrAuto::Auto); + let low_water = self.low_water.unwrap_or(ExplicitOrAuto::Auto); - if max == Qty::MAX { - if self.low_water.is_some() { + // `MAX` indicates "disabled". + // TODO: Should we add a new "enabled" config option instead of using a sentinel value? + // But this would be a breaking change. Or maybe we should always enable the memquota + // machinery even if the user chooses an unreasonably large value, and not give users a way + // to disable it. + if max == ExplicitOrAuto::Explicit(Qty::MAX) { + // If it should be disabled, but the user provided an explicit value for `low_water`. + if matches!(low_water, ExplicitOrAuto::Explicit(_)) { return Err(ConfigBuildError::Inconsistent { fields: vec!["max".into(), "low_water".into()], - problem: "low_water supplied, but max omitted".into(), + problem: "low_water supplied, but max indicates that we should disable the memory quota".into(), }); }; return Ok(Config(IfEnabled::Noop)); } + // We don't want the user to set "auto" for `max`, but an explicit value for `low_water`. + // Otherwise this config is prone to breaking since a `max` of "auto" may change as system + // memory is removed (either physically or if running in a VM/container). + if matches!(max, ExplicitOrAuto::Auto) && matches!(low_water, ExplicitOrAuto::Explicit(_)) { + return Err(ConfigBuildError::Inconsistent { + fields: vec!["max".into(), "low_water".into()], + problem: "max is \"auto\", but low_water is set to an explicit quantity".into(), + }); + } + let enabled = EnabledToken::new_if_compiled_in() // .ok_or_else(|| ConfigBuildError::NoCompileTimeSupport { @@ -129,10 +164,18 @@ impl ConfigBuilder { problem: "cargo feature `memquota` disabled (in tor-memquota crate)".into(), })?; - let low_water = self.low_water.unwrap_or_else( - // - || Qty((*max as f32 * 0.75) as _), - ); + // The general logic is taken from c-tor (see `compute_real_max_mem_in_queues`). + // NOTE: Relays have an additional lower bound for explicitly given values (64 MiB), + // but we have no way of knowing whether we are a relay or not here. + let max = match max { + ExplicitOrAuto::Explicit(x) => x, + ExplicitOrAuto::Auto => compute_max_from_total_system_mem(total_available_memory()), + }; + + let low_water = match low_water { + ExplicitOrAuto::Explicit(x) => x, + ExplicitOrAuto::Auto => Qty((*max as f32 * 0.75) as _), + }; let config = ConfigInner { max, low_water }; @@ -160,6 +203,136 @@ impl ConfigBuilder { } } +/// Determine a max given the system's total available memory. +/// +/// This is used when `max` is configured as "auto". +/// It takes a `Result` so that we can handle the case where the total memory isn't available. +fn compute_max_from_total_system_mem(mem: Result<usize, MemQueryError>) -> Qty { + const MIB: usize = 1024 * 1024; + const GIB: usize = 1024 * 1024 * 1024; + + let mem = match mem { + Ok(x) => x, + Err(e) => { + warn!("Unable to get the total available memory. Using a constant max instead: {e}"); + + // Can't get the total available memory, + // so we return a max depending on whether the architecture is 32-bit or 64-bit. + return Qty({ + cfg_if::cfg_if! { + if #[cfg(target_pointer_width = "64")] { + 8 * GIB + } else { + 1 * GIB + } + } + }); + } + }; + + let mem = if mem >= 8 * GIB { + // From c-tor: + // + // > The idea behind this value is that the amount of RAM is more than enough + // > for a single relay and should allow the relay operator to run two relays + // > if they have additional bandwidth available. + (mem as f64 * 0.40) as usize + } else { + (mem as f64 * 0.75) as usize + }; + + // The (min, max) range to clamp `mem` to. + let clamp = { + cfg_if::cfg_if! { + if #[cfg(target_pointer_width = "64")] { + (256 * MIB, 8 * GIB) + } else { + (256 * MIB, 2 * GIB) + } + } + }; + + let mem = mem.clamp(clamp.0, clamp.1); + + Qty(mem) +} + +/// The total available memory in bytes. +/// +/// This is generally the amount of system RAM, +/// but we may also take into account other OS-specific limits such as cgroups. +/// +/// Returns `None` if we were unable to get the total available memory. +/// But see internal comments for details. +fn total_available_memory() -> Result<usize, MemQueryError> { + // The sysinfo crate says we should use only one `System` per application. + // But we're a library, so it's probably best to just make this global and reuse it. + // In reality getting the system memory probably shouldn't require persistent state, + // but since the internals of the sysinfo crate are opaque to us, + // we'll just follow their documentation and cache the `System`. + // + // NOTE: The sysinfo crate in practice gets more information than we ask for. + // For example `System::new()` will always query the `_SC_PAGESIZE` and `_SC_CLK_TCK` + // on Linux even though we only refresh the memory info below + // (see https://github.com/GuillaumeGomez/sysinfo/blob/fc31b411eea7b9983176399dc5be162786dec95b/src/unix/linux/system.rs#L152). + // This means that miri will fail to run on tests that build the config, even if the config uses + // explicit values. + static SYSTEM: LazyLock<Mutex<System>> = LazyLock::new(|| Mutex::new(System::new())); + let mut system = SYSTEM.lock().unwrap_or_else(|mut e| { + // The sysinfo crate has some internal panics which would poison this mutex. + // But we can easily reset it, rather than panicking ourselves if it's poisoned. + **e.get_mut() = System::new(); + SYSTEM.clear_poison(); + e.into_inner() + }); + + system.refresh_memory_specifics(MemoryRefreshKind::nothing().with_ram()); + + // It might be possible for 32-bit systems to return >usize::MAX due to PAE (I haven't looked + // into this), so we just saturate the value and don't consider this an error. + let mem = to_usize_saturating(system.total_memory()); + + // The sysinfo crate doesn't report errors, so the best we can do is guess that a value of 0 + // implies that it was unable to get the total memory. + // + // We also need to return early to prevent a panic below. + if mem == 0 { + return Err(MemQueryError::Unavailable); + } + + // Note: The docs for the sysinfo crate say: + // + // > You need to have run refresh_memory at least once before calling this method. + // + // But as implemented, it also panics if `sys.mem_total == 0` (for example if the refresh + // silently failed). + let Some(cgroups) = system.cgroup_limits() else { + // There is no cgroup (or we're a non-Linux platform). + return Ok(mem); + }; + + // The `cgroup_limits()` surprisingly doesn't actually return the unaltered cgroups limits. + // It also adjusts them depending on the total memory. + // Since this is all undocumented, we'll also do the same calculation here. + let mem = std::cmp::min(mem, to_usize_saturating(cgroups.total_memory)); + + Ok(mem) +} + +/// An error when we are unable to obtain the system's total available memory. +#[derive(Clone, Debug, thiserror::Error)] +enum MemQueryError { + /// The total available memory is unavailable. + #[error("total available memory is unavailable")] + Unavailable, +} + +/// Convert a `u64` to a `usize`, saturating if the value would overflow. +fn to_usize_saturating(x: u64) -> usize { + // this will be optimized to a no-op on 64-bit systems + x.try_into().unwrap_or(usize::MAX) +} + #[cfg(test)] mod test { // @@ begin test lint list maintained by maint/add_warning @@ @@ -180,6 +353,9 @@ mod test { use serde_json::json; #[test] + // A value of "auto" depends on the system memory, + // which typically results in libc calls or syscall that aren't supported by miri. + #[cfg_attr(miri, ignore)] fn configs() { let chk_ok_raw = |j, c| { let b: ConfigBuilder = serde_json::from_value(j).unwrap(); @@ -215,17 +391,119 @@ mod test { chk_err(j, "UNSUPPORTED"); }; + let chk_builds = |j| { + cfg_if::cfg_if! { + if #[cfg(feature = "memquota")] { + let b: ConfigBuilder = serde_json::from_value(j).unwrap(); + b.build().unwrap(); + } else { + chk_err(j, "UNSUPPORTED"); + } + } + }; + chk_ok(json! {{ "max": "8 MiB" }}, 8, 6); + chk_ok(json! {{ "max": "8 MiB", "low_water": "auto" }}, 8, 6); chk_ok(json! {{ "max": "8 MiB", "low_water": "4 MiB" }}, 8, 4); - chk_ok_raw(json! {{ }}, Config(IfEnabled::Noop)); + + // We don't know what the exact values will be since they are derived from the system + // memory. + chk_builds(json! {{ }}); + chk_builds(json! {{ "max": "auto" }}); + chk_builds(json! {{ "low_water": "auto" }}); + chk_builds(json! {{ "max": "auto", "low_water": "auto" }}); chk_err( json! {{ "low_water": "4 MiB" }}, - "low_water supplied, but max omitted", + "max is \"auto\", but low_water is set to an explicit quantity", ); chk_err( json! {{ "max": "8 MiB", "low_water": "8 MiB" }}, "inconsistent: low_water / max", ); + + // `usize::MAX` is a special value. + chk_err( + json! {{ "max": usize::MAX.to_string(), "low_water": "8 MiB" }}, + "low_water supplied, but max indicates that we should disable the memory quota", + ); + chk_builds(json! {{ "max": (usize::MAX - 1).to_string(), "low_water": "8 MiB" }}); + + // check that the builder works as expected + #[cfg(feature = "memquota")] + { + let mut b = Config::builder(); + b.max(ExplicitOrAuto::Explicit(100_000_000)); + if let Some(inner) = b.build().unwrap().inner() { + assert_eq!(inner.max, Qty(100_000_000)); + } + + let mut b = Config::builder(); + b.max(100_000_000); + if let Some(inner) = b.build().unwrap().inner() { + assert_eq!(inner.max, Qty(100_000_000)); + } + + let mut b = ConfigBuilder::default(); + b.max(ExplicitOrAuto::Auto); + b.build().unwrap(); + } + } + + /// Test the logic that computes the `max` when configured as "auto". + #[test] + // We do some `1 * X` operations below for readability. + #[allow(clippy::identity_op)] + fn auto_max() { + #[allow(unused)] + fn check_helper(val: Qty, expected_32: Qty, expected_64: Qty) { + assert_eq!(val, { + cfg_if::cfg_if! { + if #[cfg(target_pointer_width = "64")] { + expected_64 + } else if #[cfg(target_pointer_width = "32")] { + expected_32 + } else { + panic!("Unsupported architecture :("); + } + } + }); + } + + check_helper( + compute_max_from_total_system_mem(Err(MemQueryError::Unavailable)), + /* 32-bit */ Qty(1 * 1024 * 1024 * 1024), + /* 64-bit */ Qty(8 * 1024 * 1024 * 1024), + ); + check_helper( + compute_max_from_total_system_mem(Ok(8 * 1024 * 1024 * 1024)), + /* 32-bit */ Qty(2 * 1024 * 1024 * 1024), + /* 64-bit */ Qty(3435973836), + ); + check_helper( + compute_max_from_total_system_mem(Ok(7 * 1024 * 1024 * 1024)), + /* 32-bit */ Qty(2 * 1024 * 1024 * 1024), + /* 64-bit */ Qty(5637144576), + ); + check_helper( + compute_max_from_total_system_mem(Ok(1 * 1024 * 1024 * 1024)), + /* 32-bit */ Qty(805306368), + /* 64-bit */ Qty(805306368), + ); + check_helper( + compute_max_from_total_system_mem(Ok(7 * 1024)), + /* 32-bit */ Qty(256 * 1024 * 1024), + /* 64-bit */ Qty(256 * 1024 * 1024), + ); + check_helper( + compute_max_from_total_system_mem(Ok(0)), + /* 32-bit */ Qty(256 * 1024 * 1024), + /* 64-bit */ Qty(256 * 1024 * 1024), + ); + check_helper( + compute_max_from_total_system_mem(Ok(usize::MAX)), + /* 32-bit */ Qty(2 * 1024 * 1024 * 1024), + /* 64-bit */ Qty(8 * 1024 * 1024 * 1024), + ); } } diff --git a/crates/tor-memquota/src/internal_prelude.rs b/crates/tor-memquota/src/internal_prelude.rs index 5bddc6466..c4c358885 100644 --- a/crates/tor-memquota/src/internal_prelude.rs +++ b/crates/tor-memquota/src/internal_prelude.rs @@ -55,7 +55,7 @@ pub(crate) use { tor_async_utils::mpsc_channel_no_memquota, tor_async_utils::stream_peek::StreamUnobtrusivePeeker, tor_basic_utils::ByteQty as Qty, - tor_config::{ConfigBuildError, ReconfigureError}, + tor_config::{ConfigBuildError, ExplicitOrAuto, ReconfigureError}, tor_error::{error_report, internal, into_internal, trace_report, Bug, ErrorKind, HasKind}, tor_log_ratelim::log_ratelim, tor_rtcompat::{CoarseInstant, CoarseTimeProvider, DynTimeProvider}, diff --git a/crates/tor-memquota/src/mtracker.rs b/crates/tor-memquota/src/mtracker.rs index b3569376e..e2a8f053c 100644 --- a/crates/tor-memquota/src/mtracker.rs +++ b/crates/tor-memquota/src/mtracker.rs @@ -568,7 +568,7 @@ impl MemoryQuotaTracker { let for_task = Arc::downgrade(&tracker); runtime.spawn(reclaim::task(for_task, reclaim_rx, enabled))?; - info!(%max, %low_water, "memory quota tracking initialised"); + info!(%max, %low_water, "Memory quota tracking initialised"); Ok(tracker) } |