defaults.hpp

Go to the documentation of this file.

/*
 * Copyright (c) 2022-2024, NVIDIA CORPORATION.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#pragma once
 
#include <algorithm>
#include <cstddef>
#include <cstdlib>
#include <sstream>
#include <stdexcept>
#include <string>
 
#include <BS_thread_pool.hpp>
 
#include <kvikio/shim/cufile.hpp>
 
namespace kvikio {
enum class CompatMode : uint8_t {
  OFF,  
  ON,   
  AUTO,  
};
 
namespace detail {
inline CompatMode parse_compat_mode_str(std::string_view compat_mode_str)
{
  // Convert to lowercase
  std::string tmp{compat_mode_str};
  std::transform(
    tmp.begin(), tmp.end(), tmp.begin(), [](unsigned char c) { return std::tolower(c); });
 
  CompatMode res{};
  if (tmp == "on" || tmp == "true" || tmp == "yes" || tmp == "1") {
    res = CompatMode::ON;
  } else if (tmp == "off" || tmp == "false" || tmp == "no" || tmp == "0") {
    res = CompatMode::OFF;
  } else if (tmp == "auto") {
    res = CompatMode::AUTO;
  } else {
    throw std::invalid_argument("Unknown compatibility mode: " + std::string{tmp});
  }
  return res;
}
 
template <typename T>
T getenv_or(std::string_view env_var_name, T default_val)
{
  const auto* env_val = std::getenv(env_var_name.data());
  if (env_val == nullptr) { return default_val; }
 
  std::stringstream sstream(env_val);
  T converted_val;
  sstream >> converted_val;
  if (sstream.fail()) {
    throw std::invalid_argument("unknown config value " + std::string{env_var_name} + "=" +
                                std::string{env_val});
  }
  return converted_val;
}
 
template <>
inline bool getenv_or(std::string_view env_var_name, bool default_val)
{
  const auto* env_val = std::getenv(env_var_name.data());
  if (env_val == nullptr) { return default_val; }
  try {
    // Try parsing `env_var_name` as a integer
    return static_cast<bool>(std::stoi(env_val));
  } catch (const std::invalid_argument&) {
  }
  // Convert to lowercase
  std::string str{env_val};
  // Special considerations regarding the case conversion:
  // - std::tolower() is not an addressable function. Passing it to std::transform() as
  //   a function pointer, if the compile turns out successful, causes the program behavior
  //   "unspecified (possibly ill-formed)", hence the lambda. ::tolower() is addressable
  //   and does not have this problem, but the following item still applies.
  // - To avoid UB in std::tolower() or ::tolower(), the character must be cast to unsigned char.
  std::transform(
    str.begin(), str.end(), str.begin(), [](unsigned char c) { return std::tolower(c); });
  // Trim whitespaces
  std::stringstream trimmer;
  trimmer << str;
  str.clear();
  trimmer >> str;
  // Match value
  if (str == "true" || str == "on" || str == "yes") { return true; }
  if (str == "false" || str == "off" || str == "no") { return false; }
  throw std::invalid_argument("unknown config value " + std::string{env_var_name} + "=" +
                              std::string{env_val});
}
 
template <>
inline CompatMode getenv_or(std::string_view env_var_name, CompatMode default_val)
{
  auto* env_val = std::getenv(env_var_name.data());
  if (env_val == nullptr) { return default_val; }
  return parse_compat_mode_str(env_val);
}
 
}  // namespace detail
 
class defaults {
 private:
  BS::thread_pool _thread_pool{get_num_threads_from_env()};
  CompatMode _compat_mode;
  std::size_t _task_size;
  std::size_t _gds_threshold;
  std::size_t _bounce_buffer_size;
 
  static unsigned int get_num_threads_from_env()
  {
    const int ret = detail::getenv_or("KVIKIO_NTHREADS", 1);
    if (ret <= 0) {
      throw std::invalid_argument("KVIKIO_NTHREADS has to be a positive integer greater than zero");
    }
    return ret;
  }
 
  defaults()
  {
    // Determine the default value of `compat_mode`
    {
      _compat_mode = detail::getenv_or("KVIKIO_COMPAT_MODE", CompatMode::AUTO);
    }
    // Determine the default value of `task_size`
    {
      const ssize_t env = detail::getenv_or("KVIKIO_TASK_SIZE", 4 * 1024 * 1024);
      if (env <= 0) {
        throw std::invalid_argument(
          "KVIKIO_TASK_SIZE has to be a positive integer greater than zero");
      }
      _task_size = env;
    }
    // Determine the default value of `gds_threshold`
    {
      const ssize_t env = detail::getenv_or("KVIKIO_GDS_THRESHOLD", 1024 * 1024);
      if (env < 0) {
        throw std::invalid_argument("KVIKIO_GDS_THRESHOLD has to be a positive integer");
      }
      _gds_threshold = env;
    }
    // Determine the default value of `bounce_buffer_size`
    {
      const ssize_t env = detail::getenv_or("KVIKIO_BOUNCE_BUFFER_SIZE", 16 * 1024 * 1024);
      if (env <= 0) {
        throw std::invalid_argument(
          "KVIKIO_BOUNCE_BUFFER_SIZE has to be a positive integer greater than zero");
      }
      _bounce_buffer_size = env;
    }
  }
 
  KVIKIO_EXPORT static defaults* instance()
  {
    static defaults _instance;
    return &_instance;
  }
 
 public:
  [[nodiscard]] static CompatMode compat_mode() { return instance()->_compat_mode; }
 
  static void compat_mode_reset(CompatMode compat_mode) { instance()->_compat_mode = compat_mode; }
 
  static CompatMode infer_compat_mode_if_auto(CompatMode compat_mode)
  {
    if (compat_mode == CompatMode::AUTO) {
      static auto inferred_compat_mode_for_auto = []() -> CompatMode {
        return is_cufile_available() ? CompatMode::OFF : CompatMode::ON;
      }();
      return inferred_compat_mode_for_auto;
    }
    return compat_mode;
  }
 
  static bool is_compat_mode_preferred(CompatMode compat_mode)
  {
    return compat_mode == CompatMode::ON ||
           (compat_mode == CompatMode::AUTO &&
            defaults::infer_compat_mode_if_auto(compat_mode) == CompatMode::ON);
  }
 
  static bool is_compat_mode_preferred() { return is_compat_mode_preferred(compat_mode()); }
 
  [[nodiscard]] static BS::thread_pool& thread_pool() { return instance()->_thread_pool; }
 
  [[nodiscard]] static unsigned int thread_pool_nthreads()
  {
    return thread_pool().get_thread_count();
  }
 
  static void thread_pool_nthreads_reset(unsigned int nthreads)
  {
    if (nthreads == 0) {
      throw std::invalid_argument("number of threads must be a positive integer greater than zero");
    }
    thread_pool().reset(nthreads);
  }
 
  [[nodiscard]] static std::size_t task_size() { return instance()->_task_size; }
 
  static void task_size_reset(std::size_t nbytes)
  {
    if (nbytes == 0) {
      throw std::invalid_argument("task size must be a positive integer greater than zero");
    }
    instance()->_task_size = nbytes;
  }
 
  [[nodiscard]] static std::size_t gds_threshold() { return instance()->_gds_threshold; }
 
  static void gds_threshold_reset(std::size_t nbytes) { instance()->_gds_threshold = nbytes; }
 
  [[nodiscard]] static std::size_t bounce_buffer_size() { return instance()->_bounce_buffer_size; }
 
  static void bounce_buffer_size_reset(std::size_t nbytes)
  {
    if (nbytes == 0) {
      throw std::invalid_argument(
        "size of the bounce buffer must be a positive integer greater than zero");
    }
    instance()->_bounce_buffer_size = nbytes;
  }
};
 
}  // namespace kvikio