Environment Variable Guidelines
WORK IN PROGRESS
The following material is a work in progress and should not be considered complete or ready for public use.
The runtime is affected by certain environment variables. This guide attempts to set out the conditions under which you should create environment variables to control certain runtime behaviour, and what to call them.
In general environment variables exist in a single namespace visible to a process as a whole. Given the single namespace environment variables are best used to present process-wide global values that affect the entire process. One example of a process-wide global value would be the default thread stack size if no other API is used to adjust the thread stack size.
If there is a process-wide global value that impacts the runtime behaviour and it would be useful to change without recompiling the application then this may be a candidate for exposing through an environment variable.
If there is a per-thread, per-lock, per-critical-section, or other finer grained value that impacts the runtime behaviour, then it is not likely a good candidate to expose via an environment variable. The problem with using an environment variable to change the behaviour of a thread is that the thread identifier is not known until runtime and thus one is unable to easily express to which thread the environment variables applies. It is still possible to associate a set of global defaults with a context, but it would require a more complex framework.
One or all of these options?
- Processed by an extra library
- We define an API for manipulating the behaviour. Create a shared library that calls the API functions if an environment variable is set. Preload the environment variable.
- Processed by ld.so
- Should env vars all get processed when ld starts up? ld is already walking the entire list of env vars to detect it's own env vars. Adding more to the o(n^2) walk would not be that worse for performance.
- Processed at time of use
- Should env vars only get parsed when they are needed by the library and at that point stored into a global variable? This means that all functions that are affected by the environment variable would have to check for an uninitialized value, initialize as required, and then use it. This may be problematic with threads present.