VecGeom/management/Environment.h

0001 //----------------------------------*-C++-*----------------------------------//
0002 // Copyright 2022-2023 UT-Battelle, LLC, and other Celeritas developers.
0003 // See the top-level COPYRIGHT file for details.
0004 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
0005 //---------------------------------------------------------------------------//
0006 //! \file VecGeom/management/Environment.h
0007 //---------------------------------------------------------------------------//
0008 #pragma once
0009
0010 #include <functional>
0011 #include <iosfwd>
0012 #include <string>
0013 #include <unordered_map>
0014 #include <utility>
0015 #include <vector>
0016
0017 namespace vecgeom {
0018
0019 //---------------------------------------------------------------------------//
0020 /*!
0021  * Interrogate and extend environment variables.
0022  *
0023  * This class can be interrogated to find which environment variables have been
0024  * accessed, and it can be manually set up with variables for testing.
0025  *
0026  * Unlike the standard environment which returns a null pointer for an *unset*
0027  * variable, this returns an empty string.
0028  *
0029  * \note This class is not thread-safe on its own. The \c vecgeom::getenv
0030  * free function however is safe, although it should only be used in setup
0031  * (single-thread) steps.
0032  */
0033 class Environment {
0034 private:
0035   using Container = std::unordered_map<std::string, std::string>;
0036
0037 public:
0038   //!@{
0039   //! \name Type aliases
0040   using key_type       = Container::key_type;
0041   using mapped_type    = Container::mapped_type;
0042   using value_type     = Container::value_type;
0043   using const_iterator = Container::const_iterator;
0044   using VecKVRef       = std::vector<std::reference_wrapper<value_type>>;
0045   //!@}
0046
0047 public:
0048   // Construct with defaults
0049   Environment() = default;
0050
0051   // Get an environment variable from current or system environments
0052   inline mapped_type const &operator[](key_type const &);
0053
0054   // Insert possibly new environment variables (not thread-safe)
0055   void insert(value_type const &value);
0056
0057   //! Get an ordered (by access) vector of key/value pairs
0058   VecKVRef const &ordered_environment() const { return ordered_; }
0059
0060   // Remove all entries
0061   void clear();
0062
0063   // Insert (not overriding!) from another environment
0064   void merge(Environment const &other);
0065
0066 private:
0067   std::unordered_map<key_type, mapped_type> vars_;
0068   VecKVRef ordered_;
0069
0070   mapped_type const &load_from_getenv(key_type const &);
0071 };
0072
0073 //---------------------------------------------------------------------------//
0074 // FREE FUNCTIONS
0075 //---------------------------------------------------------------------------//
0076
0077 // Access a static global environment variable
0078 Environment &environment();
0079
0080 // Thread-safe access to environment variables
0081 std::string const &getenv(std::string const &key);
0082
0083 // Write the accessed environment variables to a stream
0084 std::ostream &operator<<(std::ostream &, Environment const &);
0085
0086 //---------------------------------------------------------------------------//
0087 // INLINE DEFINITIONS
0088 //---------------------------------------------------------------------------//
0089 /*!
0090  * Get an environment variable from current or system enviroments.
0091  */
0092 auto Environment::operator[](key_type const &env_var) -> mapped_type const &
0093 {
0094   auto iter = vars_.find(env_var);
0095   if (iter == vars_.end()) {
0096     return this->load_from_getenv(env_var);
0097   }
0098   return iter->second;
0099 }
0100
0101 //---------------------------------------------------------------------------//
0102 } // namespace vecgeom