Trait RuntimeConfig 

pub trait RuntimeConfig:
    Default
    + Clone
    + Serialize
    + DeserializeOwned
    + Send
    + Sync
    + 'static {
    // Required methods
    fn storage() -> &'static Mutex<Option<Arc<Self>>>;
    fn file_names() -> &'static [&'static str];

    // Provided methods
    fn section_file_names() -> &'static [(&'static str, &'static str)] { ... }
    fn override_from_env(self) -> Self { ... }
    fn on_loaded(&self) { ... }
    fn get() -> Arc<Self>  { ... }
    fn set(config: Self) { ... }
    fn try_set(config: Self) -> bool { ... }
    fn save_default<P>(path: P) -> Result<(), Error>
       where P: AsRef<Path> { ... }
    fn from_current_dir() -> Self { ... }
    fn from_file_path<P>(path: P) -> Result<Self, Error>
       where P: AsRef<Path> { ... }
    fn from_section_file_path<P>(path: P, section: &str) -> Result<Self, Error>
       where P: AsRef<Path> { ... }
}

Trait for runtime configurations potentially loaded from a TOML file.

Implementors provide a global storage slot and the set of file names to search for; the trait supplies the lookup, lazy-initialization, and serialization logic.

The singleton stored in [Config::storage] is initialized on the first call to [Config::get] by walking up the current working directory looking for any of the names returned by [Config::file_names]. If none is found, Default is used.

Required Methods

fn storage() -> &'static Mutex<Option<Arc<Self>>>

Global storage for the configuration singleton.

Each implementor must declare its own static slot, because Rust traits cannot own statics directly.

fn file_names() -> &'static [&'static str]

File names searched in each directory during [Config::from_current_dir].

The first existing file wins.

Provided Methods

fn section_file_names() -> &'static [(&'static str, &'static str)]

File names searched in each directory, where only a specific TOML section is loaded instead of the whole file.

Each entry is (file_name, section_name) and the section must deserialize to Self. Checked after [Config::file_names] at each directory level.

fn override_from_env(self) -> Self

Hook to override fields from environment variables after loading from disk.

The default implementation returns self unchanged.

fn on_loaded(&self)

Hook invoked exactly once, when the configuration singleton is first initialized — whether loaded from disk in RuntimeConfig::get or installed with RuntimeConfig::set / RuntimeConfig::try_set.

Use it to apply configuration to global state (stream policy, bundle installation, …). Runs while the storage lock is held so that no concurrent RuntimeConfig::get can observe the configuration before the hook completed. Consequently the hook must not call RuntimeConfig::get, RuntimeConfig::set or RuntimeConfig::try_set — that would deadlock.

fn get() -> Arc<Self>

Retrieves the current configuration, loading it from the current directory if not set.

If no configuration is set, it attempts to load one from any of [Config::file_names] in the current directory or its parents. If no file is found, a default configuration is used.

Notes

Calling this function is somewhat expensive, because of a global static lock. The config format is optimized for parsing, not for consumption. A good practice is to use a local static atomic value that you can populate with the appropriate value from the config during initialization.

fn set(config: Self)

Sets the configuration to the provided value.

Panics

Panics if the configuration has already been set or read, as it cannot be overridden.

Warning

This method must be called at the start of the program, before any calls to [Config::get]. Attempting to set the configuration after it has been initialized will cause a panic.

fn try_set(config: Self) -> bool

Sets the configuration to the provided value, unless it has already been set or read — in which case the existing configuration is kept and false is returned.

Use this from libraries that want to provide a computed default without overriding a configuration the application set first.

fn save_default<P>(path: P) -> Result<(), Error>

where P: AsRef<Path>,

Save the default configuration to the provided file path.

fn from_current_dir() -> Self

Loads configuration from any of [Config::file_names] in the current directory or its parents.

Traverses up the directory tree until a valid configuration file is found or the root is reached. Returns a default configuration if no file is found.

fn from_file_path<P>(path: P) -> Result<Self, Error>

where P: AsRef<Path>,

Loads configuration from a specified file path.

A file that does not parse is reported and skipped rather than fatal: configuration keys change between releases, and a stale cubecl.toml left in a checkout must not abort the application that reads it.

fn from_section_file_path<P>(path: P, section: &str) -> Result<Self, Error>

where P: AsRef<Path>,

Loads configuration from a specific TOML section of the file at the given path.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl RuntimeConfig for CubeClRuntimeConfig