Unify environment variable management (#235)

* Add environment variable configuration infrastructure
  - Namespace rocshmem::envvar
  - Track all config env vars in per-category lists
  - Remove duplicates from list of allowed env var types
  - Reject negative inputs for unsigned integer types
  - Accept empty strings for std::string
  - Print error source location using C++20 std::source_location
  - Unit tests
* Port environment variables
  - ROCSHMEM_UNIQUEID_WITH_MPI
  - ROCSHMEM_RO_DISABLE_IPC
  - ROCSHMEM_BOOTSTRAP_TIMEOUT
  - ROCSHMEM_BOOTSTRAP_HOSTID
  - ROCSHMEM_BOOTSTRAP_SOCKET_IFNAME
  - ROCSHMEM_RO_PROGRESS_DELAY
  - ROCSHMEM_BOOTSTRAP_SOCKET_FAMILY
  - ROCSHMEM_MAX_NUM_CONTEXTS
    + Merge the independent per-backend copies into a single variable
      that is used by all three backends (IPC, RO, GDA).
    + Set default to 32 (for GDA); prior default for IPC and RO was 1024.
  - ROCSHMEM_MAX_NUM_HOST_CONTEXTS
  - ROCSHMEM_MAX_WF_BUFFERS
  - ROCSHMEM_SQ_SIZE
  - ROCSHMEM_RO_NET_CPU_QUEUE
    + Renamed from RO_NET_CPU_QUEUE
    + Change env var input type to bool, default to false
    + Invert code logic: setting RO_NET_CPU_QUEUE to anything
      would /disable/ a variable gpu_queue, which defaulted to true.
      Variable is now named config::ro::net_cpu_queue,
      with all prior checks for gpu_queue inverted.
  - ROCSHMEM_USE_IB_HCA
  - ROCSHMEM_HEAP_SIZE
    + Defaults to 1L << 30 i.e. 1 GiB,
      from default heap size in memory/heap_memory.hpp.
  - ROCSHMEM_MAX_NUM_TEAMS
    + Unlike other env vars, this can be referenced from devices.
    + Function currently narrows from size_t to int: uses need to be audited
      for safety and correctness in using size_t directly.
  - ROCSHMEM_GDA_ALTERNATE_QP_PORTS
* New env var ROCSHMEM_DEBUG
  - Debug levels:
    + NONE
    + VERSION
    + WARN
    + INFO
    + TRACE
  - Currently unused - will be added later
  - Mirrors RCCL debug control
* Remove rocshmem::rocshmem_env_config
* Change interface for GetClosestNicToGpu
  to accept const char** instead of char**:
  the pointed-to string does not need to be modified
  - Files were not audited for inclusion of util.hpp only for env vars
---------
Signed-off-by: Omri Mor <Omri.Mor@amd.com>

tests/unit_tests/CMakeLists.txt

@@ -63,6 +63,7 @@ target_sources(
     free_list_gtest.cpp
     wavefront_size_gtest.cpp
     atomic_wf_queue_gtest.cpp
+    envvar_gtest.cpp
 )
 
 if (USE_IPC)

tests/unit_tests/envvar_gtest.cpp

@@ -0,0 +1,283 @@
+/******************************************************************************
+ * Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *****************************************************************************/
+
+#include <limits>
+
+#include "envvar_gtest.hpp"
+
+using namespace rocshmem;
+
+using VarTypes = ::testing::Types<bool,
+                                  uint32_t,
+                                  size_t,
+                                  int64_t,
+                                  std::string,
+                                  envvar::types::socket_family,
+                                  envvar::types::debug_level>;
+
+TYPED_TEST_SUITE(EnvVarUnsetTestFixture, VarTypes);
+TYPED_TEST_SUITE(EnvVarSetTestFixture, VarTypes);
+
+TYPED_TEST(EnvVarUnsetTestFixture, name) {
+  EXPECT_EQ(this->var_.get_name(), this->var_full_name_);
+}
+
+TYPED_TEST(EnvVarUnsetTestFixture, doc) {
+  EXPECT_EQ(this->var_.get_doc(), this->var_doc_);
+}
+
+TYPED_TEST(EnvVarUnsetTestFixture, is_default) {
+  EXPECT_TRUE(this->var_.is_default());
+  EXPECT_EQ(this->var_.get_value(), this->var_.get_default());
+}
+
+TYPED_TEST(EnvVarSetTestFixture, is_default) {
+  EXPECT_FALSE(this->var_.is_default());
+  EXPECT_EQ(this->var_.get_value(), this->var_.get_default());
+}
+
+TEST_F(EnvVarTestFixture, string_custom_default) {
+  const std::string default_value_{"This is the default value."};
+  const envvar::var<std::string> var_{this->var_name_, this->var_doc_, default_value_};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), default_value_);
+}
+
+TEST_F(EnvVarTestFixture, parse_integer) {
+  this->setenv("1073741824");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), 1L << 30);
+}
+
+TEST_F(EnvVarTestFixture, parse_integer_notaninteger) {
+  this->setenv("Ceci n'est pas un entier.");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_, 1L << 30};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_value(), 1L << 30);
+}
+
+TEST_F(EnvVarTestFixture, parse_integer_large) {
+  this->setenv("9223372036854775807");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), std::numeric_limits<int64_t>::max());
+}
+
+TEST_F(EnvVarTestFixture, parse_integer_too_large) {
+  this->setenv("9223372036854775808");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), var_.get_default());
+}
+
+TEST_F(EnvVarTestFixture, parse_integer_negative) {
+  this->setenv("-1073741824");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), -1L << 30);
+}
+
+TEST_F(EnvVarTestFixture, parse_integer_negative_large) {
+  this->setenv("-9223372036854775808");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), std::numeric_limits<int64_t>::min());
+}
+
+TEST_F(EnvVarTestFixture, parse_integer_negative_too_large) {
+  this->setenv("-9223372036854775809");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), var_.get_default());
+}
+
+TEST_F(EnvVarTestFixture, parse_integer_hex) {
+  this->setenv("0x40000000");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), 1L << 30);
+}
+
+TEST_F(EnvVarTestFixture, parse_integer_hex_only) {
+  this->setenv("0x40000000");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_,
+                                  envvar::parser::parse_hex<int64_t>{}};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), 1L << 30);
+}
+
+// parse_hex<> interprets input digits as hexadecimal, even without 0x prefix
+TEST_F(EnvVarTestFixture, parse_integer_hex_only_noprefix) {
+  this->setenv("40000000");
+  const envvar::var<int64_t> var_{this->var_name_, this->var_doc_,
+                                  envvar::parser::parse_hex<int64_t>{}};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), 1L << 30);
+}
+
+TEST_F(EnvVarTestFixture, parse_unsigned_integer) {
+  this->setenv("1073741824");
+  const envvar::var<uint32_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), 1L << 30);
+}
+
+TEST_F(EnvVarTestFixture, parse_unsigned_integer_negative) {
+  this->setenv("-1");
+  const envvar::var<uint32_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), var_.get_default());
+}
+
+TEST_F(EnvVarTestFixture, parse_unsigned_large) {
+  this->setenv("4294967296");
+  const envvar::var<uint32_t> var_{this->var_name_, this->var_doc_};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), 0);
+  EXPECT_EQ(var_.get_value(), var_.get_default());
+}
+
+TEST_F(EnvVarTestFixture, parse_bool_zero) {
+  this->setenv("0");
+  const envvar::var<bool> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), false);
+  EXPECT_EQ(var_.get_value(), false);
+}
+
+TEST_F(EnvVarTestFixture, parse_bool_one) {
+  this->setenv("1");
+  const envvar::var<bool> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), false);
+  EXPECT_EQ(var_.get_value(), true);
+}
+
+TEST_F(EnvVarTestFixture, parse_bool_negative) {
+  this->setenv("-1");
+  const envvar::var<bool> var_{this->var_name_, this->var_doc_};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), false);
+  EXPECT_EQ(var_.get_value(), false);
+}
+
+TEST_F(EnvVarTestFixture, parse_bool_two) {
+  this->setenv("2");
+  const envvar::var<bool> var_{this->var_name_, this->var_doc_};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), false);
+  EXPECT_EQ(var_.get_value(), false);
+}
+
+TEST_F(EnvVarTestFixture, parse_bool_false) {
+  this->setenv("false");
+  const envvar::var<bool> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), false);
+  EXPECT_EQ(var_.get_value(), false);
+}
+
+TEST_F(EnvVarTestFixture, parse_bool_true) {
+  this->setenv("true");
+  const envvar::var<bool> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), false);
+  EXPECT_EQ(var_.get_value(), true);
+}
+
+TEST_F(EnvVarTestFixture, parse_bool_other) {
+  this->setenv("other");
+  const envvar::var<bool> var_{this->var_name_, this->var_doc_};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), false);
+  EXPECT_EQ(var_.get_value(), false);
+}
+
+TEST_F(EnvVarTestFixture, parse_socket_family_unspec) {
+  this->setenv("UNSPEC");
+  const envvar::var<envvar::types::socket_family> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), envvar::types::socket_family::UNSPEC);
+  EXPECT_EQ(var_.get_value(), envvar::types::socket_family::UNSPEC);
+}
+
+TEST_F(EnvVarTestFixture, parse_socket_family_af_unspec) {
+  this->setenv("AF_UNSPEC");
+  const envvar::var<envvar::types::socket_family> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), envvar::types::socket_family::UNSPEC);
+  EXPECT_EQ(var_.get_value(), envvar::types::socket_family::UNSPEC);
+}
+
+TEST_F(EnvVarTestFixture, parse_socket_family_inet) {
+  this->setenv("INET");
+  const envvar::var<envvar::types::socket_family> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), envvar::types::socket_family::UNSPEC);
+  EXPECT_EQ(var_.get_value(), envvar::types::socket_family::INET);
+}
+
+TEST_F(EnvVarTestFixture, parse_socket_family_af_inet) {
+  this->setenv("AF_INET");
+  const envvar::var<envvar::types::socket_family> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), envvar::types::socket_family::UNSPEC);
+  EXPECT_EQ(var_.get_value(), envvar::types::socket_family::INET);
+}
+
+TEST_F(EnvVarTestFixture, parse_socket_family_inet6) {
+  this->setenv("INET6");
+  const envvar::var<envvar::types::socket_family> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), envvar::types::socket_family::UNSPEC);
+  EXPECT_EQ(var_.get_value(), envvar::types::socket_family::INET6);
+}
+
+TEST_F(EnvVarTestFixture, parse_socket_family_af_inet6) {
+  this->setenv("AF_INET6");
+  const envvar::var<envvar::types::socket_family> var_{this->var_name_, this->var_doc_};
+  EXPECT_FALSE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), envvar::types::socket_family::UNSPEC);
+  EXPECT_EQ(var_.get_value(), envvar::types::socket_family::INET6);
+}
+
+TEST_F(EnvVarTestFixture, parse_socket_family_nonesense) {
+  this->setenv("'Twas brillig, and the slithy toves, did gyre and gimble in the wabe.");
+  const envvar::var<envvar::types::socket_family> var_{this->var_name_, this->var_doc_};
+  EXPECT_TRUE(var_.is_default());
+  EXPECT_EQ(var_.get_default(), envvar::types::socket_family::UNSPEC);
+  EXPECT_EQ(var_.get_value(), var_.get_default());
+}

tests/unit_tests/envvar_gtest.hpp

@@ -0,0 +1,97 @@
+/******************************************************************************
+ * Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ *****************************************************************************/
+
+#ifndef ROCSHMEM_ENVVAR_GTEST_HPP
+#define ROCSHMEM_ENVVAR_GTEST_HPP
+
+#include <cstdlib>
+#include <sstream>
+#include <string>
+
+#include "gtest/gtest.h"
+#include "../src/envvar.hpp"
+
+namespace rocshmem {
+
+class EnvVarTestFixture : public ::testing::Test
+{
+  public:
+    static constexpr envvar::category::tag category_ = envvar::category::tag::ROCSHMEM;
+    static constexpr const char* var_name_ = "GTEST";
+    static constexpr const char* var_prefix_ = envvar::category::prefix<category_>;
+    static inline const std::string var_full_name_{std::string(var_prefix_).append("_").append(var_name_)};
+    static constexpr const char* var_doc_ = "Test envvar documentation: documents the test envvar.";
+
+    static int setenv(const char* value) {
+      return ::setenv(var_full_name_.c_str(), value, true);
+    }
+
+    static int setenv(const std::string& value) {
+      return setenv(value.c_str());
+    }
+
+    static int unsetenv() {
+      return ::unsetenv(var_full_name_.c_str());
+    }
+
+  protected:
+    static void SetUpTestSuite() {
+      unsetenv();
+    }
+
+    static void TearDownTestSuite() {
+      unsetenv();
+    }
+
+    void SetUp() override {
+      unsetenv();
+    }
+
+    void TearDown() override {
+      unsetenv();
+    }
+};
+
+template <typename T>
+class EnvVarUnsetTestFixture : public EnvVarTestFixture
+{
+  protected:
+    const envvar::var<T> var_{var_name_, var_doc_};
+};
+
+template <typename T>
+class EnvVarSetTestFixture : public EnvVarTestFixture
+{
+  protected:
+    const envvar::var<T> var_{var_name_, var_doc_};
+
+    static void SetUpTestSuite() {
+      std::ostringstream oss{};
+      oss << T{};
+      setenv(oss.str());
+    }
+};
+} // namespace rocshmem
+
+#endif // ROCSHMEM_ENVVAR_GTEST_HPP