Tpetra: Add a way to query environment variables

[mhoemmen]

@trilinos/tpetra

Add a way for Tpetra to query environment variables. This would be useful for making more debug options available at run time, so that users wouldn't have to recompile their release build of Trilinos in order to get some useful debug information. It would also be useful for debugging issues like #423, which relate to downstream packages or applications making incorrect assumptions (e.g., that stride == local # rows, which is not true if padding is enabled).

It may make sense to cache results of looking up an environment variable, in order to avoid overhead of system calls.

It would make sense to design this as a singleton class. This would make it easier to ensure thread safety by locking use of getenv(). POSIX getenv() does not promise thread safety:

http://pubs.opengroup.org/onlinepubs/009695399/functions/getenv.html

though Linux's implementation of getenv() does promise thread safety:

http://man7.org/linux/man-pages/man3/getenv.3.html

[mhoemmen]

Here is the interface I would like (omitting details relating to singleton initialization and finalization; use atexit() hook to finalize). Put in a new header file called Tpetra_Details_Environment.hpp in tpetra/core/src.

namespace Tpetra {
namespace Details {

class Environment {
public:
  //! Get singleton instance
  static Environment& getInstance ();

  /// \brief Does the given variable exist?
  ///
  /// This is nonconst because the implementation
  /// reserves the right to cache results.
  bool variableExists (const std::string& variableName);

  /// \brief Get value of the given variable.
  ///
  /// This is nonconst because the implementation
  /// reserves the right to cache results.
  ///
  /// \return If the variable does not exist in the environment,
  ///   return "".  Else, return the variable's value, as a string.
  std::string getValue (const std::string& variableName);

private:
  //! The singleton instance
  static Environment* theInstance_;
};

} // namespace Details
} // namespace Tpetra

[srajama1]

Thinking out loud : Can this be in Trilinos name space and in a place like Teuchos ? Seems much more useful at the larger scale.

[krcb]

Could std::getenv be of use here? Since CXX11 this function is thread-safe as long as no other function modifies the environment:

http://en.cppreference.com/w/cpp/utility/program/getenv

[mhoemmen]

@srajama1 wrote:

Thinking out loud : Can this be in Trilinos name space and in a place like Teuchos ? Seems much more useful at the larger scale.

We could test in Tpetra first, then deploy in Teuchos once we're confident that it works. Breaking Teuchos is even higher consequence than breaking Tpetra :-)

[mhoemmen]

@krcb wrote:

Could std::getenv be of use here? Since CXX11 this function is thread-safe as long as no other function modifies the environment . . .

Yes; thanks!

[mhoemmen]

Progress report: @tjfulle wrote an initial implementation and stand-alone test. I reviewed the implementation and gave some comments on refining the interface. Next step after that is to integrate this into Trilinos' unit test framework.

[tjfulle]

Commit 347c81a of my fork of Trilinos adds this feature. @mhoemmen, do you want to take a look at it before I put through an official pull request?

[mhoemmen]

@tjfulle wrote:

@mhoemmen, do you want to take a look at it before I put through an official pull request?

I just added some comments to that commit. Thanks!

[mhoemmen]

I'm calling this closed. Thanks @tjfulle !