> What exactly is this flushing

It clears `@cache`, `@used` and the environment list.

> what data is cached

Whenever `settings[thing]` is called, the settings object consults `@values` makes the thing and caches a copy in `@cache`. As long as no  member of `@values` changes, the settings object can return results directly from the cache without re-computing them. Similarly, we also cache a list of `Environment` objects which are also dependent on the contents of `@values` for things like `modulepath`.

> and when/why should it be flushed?

Prior to f4e229e `run_mode` was stored in `@values` and every call to `set_value` performed this cache flush. After that commit, `run_mode` is now stored in an attribute: `@preferred_run_mode_name` and the cache flush has to be triggered by changes in that attribute in addition to changes in `@values`. For example, this is required to allow Faces to shift from `:user` mode to `:master` mode and have a `production` environment that actually has the `modulepath` set in the `[master]` section of `puppet.conf.

Otherwise, they get a cached copy of the environment with values from the `[user]` section or defaults.