Struct Config 

pub struct Config<D: ConfigDefault> {
    pub(crate) name: &'static str,
    pub(crate) desc: &'static str,
    pub(crate) default: D,
    pub(crate) scope: ParameterScope,
}

A handle to a dynamically updatable configuration value.

This represents a strongly-typed named config of type T. It may be registered to a set of such configs with ConfigSet::add and then later used to retrieve the latest value at any time with Self::get.

The supported types are bool, usize, Duration, and String, as well as Option variants of these as necessary.

Fields

name: &'static str

desc: &'static str

default: D

scope: ParameterScope

Implementations

impl<D: ConfigDefault> Config<D>

pub const fn new( name: &'static str, default: D, desc: &'static str, scope: ParameterScope, ) -> Self

Constructs a handle for a config of type T.

It is best practice, but not strictly required, for the name to be globally unique within a process.

scope declares where the config’s value may be overridden. It is a required parameter rather than a builder step so that every new config makes the choice deliberately. ParameterScope documents how to pick one from the config’s read sites.

TODO(cfg): Add some sort of categorization of config purpose here: e.g. limited-lifetime rollout flag, CYA, magic number that we never expect to tune, magic number that we DO expect to tune, etc. This could be used to power something like a --future-default-flags for CI, to replace part or all of the manually maintained list.

TODO(cfg): See if we can make this more Rust-y and take these params as a struct (the obvious thing hits some issues with const combined with Drop).

pub fn name(&self) -> &str

The name of this config.

pub fn desc(&self) -> &str

The description of this config.

pub fn scope(&self) -> ParameterScope

The ParameterScope of this config.

pub fn default(&self) -> &D

The default value of this config.

pub fn get(&self, set: &ConfigSet) -> D::ConfigType

Returns the latest value of this config within the given set.

Panics if this config was not previously registered to the set.

TODO(cfg): Decide if this should be a method on ConfigSet instead to match the precedent of BTreeMap/HashMap::get taking a key. It’s like this initially because it was thought that the Config definition was the more important “noun” and also that rustfmt would maybe work better on this ordering.

pub fn get_with_overrides( &self, set: &ConfigSet, overrides: Option<&ConfigUpdates>, ) -> D::ConfigType

Returns the value of this config within the given set, with overrides layered on top.

This is how environmentd must read a ParameterScope::Replica config whose value it ships to one specific replica: the set holds the environment-wide value and overrides holds that replica’s scoped overrides, which win. Reading such a config with Self::get instead makes its scope declaration a silent no-op.

Panics if this config was not previously registered to the set. An override whose type does not match the config’s is logged and ignored, rather than panicking a read site that is often on a critical path.

pub fn handle(&self, set: &ConfigSet) -> ConfigValHandle<D::ConfigType>

Returns a handle to the value of this config in the given set.

This allows users to amortize the cost of the name lookup.

pub(crate) fn shared<'a>(&self, set: &'a ConfigSet) -> &'a ConfigValAtomic

Returns the shared value of this config in the given set.

pub fn parse_val(&self, val: &str) -> Result<ConfigVal, String>

Parse a string value for this config.

Trait Implementations

impl<D: Clone + ConfigDefault> Clone for Config<D>

fn clone(&self) -> Config<D>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<D: Debug + ConfigDefault> Debug for Config<D>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.