Configuration, environment and tuning

Overview

Runtime settings captured from the environment and the tuning constants.

Lower-level functions (algorithm-specific variants, workspace queries, validation and helpers): Configuration: lower-level API.

Functions

settings()

const Settings & batchlas::settings

(

)

The process-wide settings.

The environment is read once, under std::call_once, on the first call. Thread-safe, and safe to call from a static initialiser.

Returns

a reference valid for the life of the process. Its contents change under configure() and detail::reload_settings(), so do not cache fields across a call that could do either, and never hoist a field into a function-local static.

configure()

void batchlas::configure

(

const Settings &

s

)

Install s as the settings, for an embedding application that wants to stop inheriting ambient process state.

What is installed is the base, not a lock: a later detail::reload_settings() (every ScopedEnvVar triggers one) re-reads the environment on top of it, so a knob set here and not exported holds for the life of the process, and a knob something explicitly exports still wins. The unsafe group is not gated here.

Parameters

s	the complete settings to install

Precondition

No batchlas::Queue has been constructed yet in this process.

Exceptions

batchlas::api_misuse

(a std::runtime_error) if a Queue already exists; nothing is changed.

reload_settings()

void batchlas::detail::reload_settings

(

)

Re-read the environment on top of the last configure() (or the defaults).

ScopedEnvVar calls this from its constructor and destructor, which is how a test's pinned knob takes effect and then stops leaking into later tests.

Warning

A raw ::setenv does not reach it. A reload between a *_buffer_size() query and its solve can under-size the workspace. Not thread-safe with respect to concurrent settings() readers: call it from a test body or benchmark setup only.

Topics
	Configuration: lower-level API
	Per-size tuning lookups, environment parsers and internal hooks behind settings() and configure().

Files
file	include/batchlas/settings.hh
	Every BATCHLAS_* environment variable the library reads, captured once into batchlas::Settings, plus the programmatic override configure().
file	include/batchlas/tuning_params.hh
	Tuning constants, bucketed by problem order n, with runtime BATCHLAS_TUNE_* overrides.
file	include/batchlas/util/env.hh
	The shared environment-variable parsers and the ScopedEnvVar RAII setter.

Classes
class	batchlas::EnvValue
	A raw captured environment value, shaped like the std::getenv call it replaces. More...
struct	batchlas::RoutingSettings
	The route pins: BATCHLAS_<OP>_ROUTE, one raw string per op that selects a kernel. More...
struct	batchlas::SelectionSettings
	Which kernel or algorithm runs, for the knobs outside the route pins. More...
struct	batchlas::GeometrySettings
	Launch geometry, block widths, iteration counts and tuning thresholds. More...
struct	batchlas::GeometrySettings::TuneSettings
	The runtime overrides of include/batchlas/tuning_params.hh (BATCHLAS_TUNE_*). More...
struct	batchlas::DiagnosticsSettings
	Tracing, dumping, profiling and the opt-in checks. More...
struct	batchlas::DiagnosticsSettings::DumpBandR1Settings
	The BATCHLAS_DUMP_BANDR1_* band-reduction dump family. More...
struct	batchlas::UnsafeSettings
	The overrides that remove a guarantee: setting one can make a correct program crash, hang or silently compute wrong numbers. More...
struct	batchlas::Settings
	Everything BatchLAS reads from its environment, in one value. More...
class	batchlas::ScopedEnvVar
	Sets (or unsets) an environment variable for a scope and restores it on exit. More...