rtcx.cpp

/*
 * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 */

#include <cuda.h>
#include <cuda_runtime_api.h>
#include <nvtx3/nvtx3.hpp>

#include <dlfcn.h>
#include <fcntl.h>
#include <nvJitLink.h>
#include <nvrtc.h>
#include <rtcx.hpp>
#include <sys/mman.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <zstd.h>

#include <atomic>
#include <cerrno>
#include <cstring>
#include <filesystem>
#include <format>
#include <numeric>
#include <source_location>

#ifndef RTCX_STATIC_LINK_LIBNVRTC
#define RTCX_STATIC_LINK_LIBNVRTC 0
#endif

#ifndef RTCX_STATIC_LINK_LIBNVJITLINK
#define RTCX_STATIC_LINK_LIBNVJITLINK 0
#endif

#define RTCX_EXPECTS(condition_, reason_, exception_type_)                               \
  do {                                                                                   \
    if (!(condition_)) {                                                                 \
      throw exception_type_{::std::format("RTCX failure at: {}:{}: {}",                  \
                                          ::std::source_location::current().file_name(), \
                                          ::std::source_location::current().line(),      \
                                          (reason_))};                                   \
    }                                                                                    \
  } while (0)

#define RTCX_FAIL(reason_, exception_type_)                                            \
  do {                                                                                 \
    throw exception_type_{::std::format("RTCX failure at: {}:{}: {}",                  \
                                        ::std::source_location::current().file_name(), \
                                        ::std::source_location::current().line(),      \
                                        (reason_))};                                   \
  } while (0)

#define RTCX_CHECK_CUDA(...)                                                             \
  do {                                                                                   \
    ::CUresult result_ = (__VA_ARGS__);                                                  \
    if (result_ != ::CUDA_SUCCESS) {                                                     \
      char const* enum_str_;                                                             \
      RTCX_EXPECTS(::rtcx::cu->GetErrorString(result_, &enum_str_) == ::CUDA_SUCCESS,    \
                   "Unable to get CUDA error string",                                    \
                   std::runtime_error);                                                  \
      auto errstr_ = ::std::format("(cuda) expression `{}` failed, with error ({}): {}", \
                                   #__VA_ARGS__,                                         \
                                   static_cast<::std::int64_t>(result_),                 \
                                   enum_str_);                                           \
      RTCX_FAIL(errstr_, ::std::runtime_error);                                          \
    }                                                                                    \
  } while (0)

#define RTCX_CHECK_CUDART(...)                                                                 \
  do {                                                                                         \
    ::cudaError_t result_ = (__VA_ARGS__);                                                     \
    if (result_ != ::cudaSuccess) {                                                            \
      char const* enum_name_ = ::cudaGetErrorName(result_);                                    \
      char const* enum_msg_  = ::cudaGetErrorString(result_);                                  \
      auto errstr_ = ::std::format("(cudart) expression `{}` failed, with error ({}: {}): {}", \
                                   #__VA_ARGS__,                                               \
                                   static_cast<::std::int64_t>(result_),                       \
                                   enum_name_,                                                 \
                                   enum_msg_);                                                 \
      RTCX_FAIL(errstr_, ::std::runtime_error);                                                \
    }                                                                                          \
  } while (0)

#define RTCX_CHECK_NVRTC(...)                                                             \
  do {                                                                                    \
    ::nvrtcResult result_ = (__VA_ARGS__);                                                \
    if (result_ != ::NVRTC_SUCCESS) {                                                     \
      auto errstr_ = ::std::format("(nvrtc) expression `{}` failed, with error ({}): {}", \
                                   #__VA_ARGS__,                                          \
                                   static_cast<::std::int64_t>(result_),                  \
                                   ::rtcx::nvrtc->GetErrorString(result_));               \
      RTCX_FAIL(errstr_, ::std::runtime_error);                                           \
    }                                                                                     \
  } while (0)

#define RTCX_CHECK_NVJITLINK(...)                                                             \
  do {                                                                                        \
    ::nvJitLinkResult result_ = (__VA_ARGS__);                                                \
    if (result_ != ::NVJITLINK_SUCCESS) {                                                     \
      auto errstr_ = ::std::format("(nvJitLink) expression `{}` failed, with error ({}): {}", \
                                   #__VA_ARGS__,                                              \
                                   static_cast<::std::int64_t>(result_),                      \
                                   ::rtcx::nvJitLinkResult_string(result_));                  \
      RTCX_FAIL(errstr_, ::std::runtime_error);                                               \
    }                                                                                         \
  } while (0)

#define RTCX_FUNC_RANGE() \
  ::nvtx3::scoped_range_in<::rtcx::nvtx_domain> rtcx_func_range__ { __func__ }

namespace rtcx {
namespace {

struct nvtx_domain {
  static constexpr char const* name [[maybe_unused]] = "rtcx";
};

enum class object_type : std::uint8_t { LIBRARY, BLOB };

std::string_view object_tag(object_type type)
{
  switch (type) {
    case object_type::LIBRARY: return "cuLibrary";
    case object_type::BLOB: return "blob";
    default:
      RTCX_FAIL(std::format("Unrecognized object type: ({})", static_cast<std::int64_t>(type)),
                std::runtime_error);
  }
}

template <typename StringType>
std::string join_strings(std::span<StringType> strings, std::string_view separator)
{
  if (strings.empty()) { return {}; }

  if (strings.size() == 1) { return std::string{strings[0].begin(), strings[0].end()}; }

  auto total_size = std::transform_reduce(
    strings.begin(),
    strings.end(),
    size_t{0},
    [](size_t total, size_t str_size) { return total + str_size; },
    [](auto& str) { return str.size(); });

  auto separator_size = separator.size() * (strings.size() - 1);

  std::string result;
  result.reserve(total_size + separator_size);

  for (size_t i = 0; i < strings.size(); ++i) {
    result.append(strings[i].begin(), strings[i].end());
    if (i != (strings.size() - 1)) { result.append(separator); }
  }

  return result;
}

}  // namespace

void log_warning(std::string_view msg)
{
  std::fprintf(stderr, "[rtcx] warn: %.*s\n", static_cast<int>(msg.size()), msg.data());
}

void log_error(std::string_view msg)
{
  std::fprintf(stderr, "[rtcx] error: %.*s\n", static_cast<int>(msg.size()), msg.data());
}

#define FOR_EACH_CUDA_FUNC(DO_IT)       \
  DO_IT(GetErrorString)                 \
  DO_IT(GetErrorName)                   \
  DO_IT(Init)                           \
  DO_IT(OccupancyMaxPotentialBlockSize) \
  DO_IT(LaunchKernel)                   \
  DO_IT(LaunchKernelEx)                 \
  DO_IT(LaunchCooperativeKernel)        \
  DO_IT(KernelGetFunction)              \
  DO_IT(LibraryLoadData)                \
  DO_IT(LibraryLoadFromFile)            \
  DO_IT(LibraryGetKernel)               \
  DO_IT(LibraryUnload)

#define FOR_EACH_NVRTC_FUNC(DO_IT) \
  DO_IT(Version)                   \
  DO_IT(GetErrorString)            \
  DO_IT(CreateProgram)             \
  DO_IT(DestroyProgram)            \
  DO_IT(CompileProgram)            \
  DO_IT(GetPTXSize)                \
  DO_IT(GetPTX)                    \
  DO_IT(GetCUBINSize)              \
  DO_IT(GetCUBIN)                  \
  DO_IT(GetLTOIRSize)              \
  DO_IT(GetLTOIR)                  \
  DO_IT(GetProgramLogSize)         \
  DO_IT(GetProgramLog)             \
  DO_IT(AddNameExpression)         \
  DO_IT(GetLoweredName)

#define FOR_EACH_NVJITLINK_FUNC(DO_IT) \
  DO_IT(Version)                       \
  DO_IT(Create)                        \
  DO_IT(Destroy)                       \
  DO_IT(AddData)                       \
  DO_IT(AddFile)                       \
  DO_IT(Complete)                      \
  DO_IT(GetLinkedCubinSize)            \
  DO_IT(GetLinkedCubin)                \
  DO_IT(GetLinkedPtxSize)              \
  DO_IT(GetLinkedPtx)                  \
  DO_IT(GetErrorLogSize)               \
  DO_IT(GetErrorLog)                   \
  DO_IT(GetInfoLog)                    \
  DO_IT(GetInfoLogSize)

namespace {

std::string_view nvJitLinkResult_string(nvJitLinkResult result)
{
  switch (result) {
    case NVJITLINK_SUCCESS: return "NVJITLINK_SUCCESS";
    case NVJITLINK_ERROR_UNRECOGNIZED_OPTION: return "NVJITLINK_ERROR_UNRECOGNIZED_OPTION";
    case NVJITLINK_ERROR_MISSING_ARCH: return "NVJITLINK_ERROR_MISSING_ARCH";
    case NVJITLINK_ERROR_INVALID_INPUT: return "NVJITLINK_ERROR_INVALID_INPUT";
    case NVJITLINK_ERROR_PTX_COMPILE: return "NVJITLINK_ERROR_PTX_COMPILE";
    case NVJITLINK_ERROR_NVVM_COMPILE: return "NVJITLINK_ERROR_NVVM_COMPILE";
    case NVJITLINK_ERROR_INTERNAL: return "NVJITLINK_ERROR_INTERNAL";
    case NVJITLINK_ERROR_THREADPOOL: return "NVJITLINK_ERROR_THREADPOOL";
    case NVJITLINK_ERROR_UNRECOGNIZED_INPUT: return "NVJITLINK_ERROR_UNRECOGNIZED_INPUT";
    case NVJITLINK_ERROR_FINALIZE: return "NVJITLINK_ERROR_FINALIZE";
#if CUDA_VERSION >= 13000
    case NVJITLINK_ERROR_NULL_INPUT: return "NVJITLINK_ERROR_NULL_INPUT";
    case NVJITLINK_ERROR_INCOMPATIBLE_OPTIONS: return "NVJITLINK_ERROR_INCOMPATIBLE_OPTIONS";
    case NVJITLINK_ERROR_INCORRECT_INPUT_TYPE: return "NVJITLINK_ERROR_INCORRECT_INPUT_TYPE";
    case NVJITLINK_ERROR_ARCH_MISMATCH: return "NVJITLINK_ERROR_ARCH_MISMATCH";
    case NVJITLINK_ERROR_OUTDATED_LIBRARY: return "NVJITLINK_ERROR_OUTDATED_LIBRARY";
    case NVJITLINK_ERROR_MISSING_FATBIN: return "NVJITLINK_ERROR_MISSING_FATBIN";
    case NVJITLINK_ERROR_UNRECOGNIZED_ARCH: return "NVJITLINK_ERROR_UNRECOGNIZED_ARCH";
    case NVJITLINK_ERROR_UNSUPPORTED_ARCH: return "NVJITLINK_ERROR_UNSUPPORTED_ARCH";
    case NVJITLINK_ERROR_LTO_NOT_ENABLED: return "NVJITLINK_ERROR_LTO_NOT_ENABLED";
#endif
    default:
      RTCX_FAIL(
        std::format("Unrecognized nvJitLinkResult type: ({})", static_cast<std::int64_t>(result)),
        std::runtime_error);
  }
}

std::string_view binary_type_string(binary_type type)
{
  switch (type) {
    case binary_type::LTO_IR: return "LTO_IR";
    case binary_type::CUBIN: return "CUBIN";
    case binary_type::FATBIN: return "FATBIN";
    case binary_type::PTX: return "PTX";
    default:
      RTCX_FAIL(std::format("Unrecognized binary_type: ({})", static_cast<std::int64_t>(type)),
                std::runtime_error);
  }
}

nvJitLinkInputType to_nvjitlink_input_type(binary_type bin_type)
{
  switch (bin_type) {
    case binary_type::LTO_IR: return NVJITLINK_INPUT_LTOIR;
    case binary_type::CUBIN: return NVJITLINK_INPUT_CUBIN;
    case binary_type::FATBIN: return NVJITLINK_INPUT_FATBIN;
    case binary_type::PTX: return NVJITLINK_INPUT_PTX;
    default:
      RTCX_FAIL(std::format("Unrecognized binary type for linking: ({}) ",
                            static_cast<std::int64_t>(bin_type)),
                std::logic_error);
  }
}

[[maybe_unused]] void* load_dso(std::string_view base_name, std::span<std::string const> names)
{
  for (auto& name : names) {
    void* handle = ::dlopen(name.c_str(), RTLD_NOW | RTLD_LOCAL);
    if (handle != nullptr) { return handle; }
  }

  RTCX_FAIL(
    std::format(
      "Failed to load dynamic library `{}` (tried: {})", base_name, join_strings(names, ", ")),
    std::runtime_error);
}

[[maybe_unused]] void* get_dso_symbol(char const* lib_name, void* handle, char const* sym_name)
{
  void* sym = ::dlsym(handle, sym_name);
  if (sym == nullptr) {
    RTCX_FAIL(
      std::format(
        "Failed to load symbol `{}` from `{}`, error: `{}`", sym_name, lib_name, ::dlerror()),
      std::runtime_error);
  }
  return sym;
}

inline constexpr std::int32_t major_version(std::int32_t version) { return version / 1000; }

struct LibCuda {
  void* _handle = nullptr;

#define DO_IT(func) decltype(::cu##func)* func = nullptr;
  FOR_EACH_CUDA_FUNC(DO_IT)
#undef DO_IT

  explicit LibCuda(void* handle) : _handle(handle) { _load_symbols(); }
  LibCuda(LibCuda const&)            = delete;
  LibCuda(LibCuda&&)                 = delete;
  LibCuda& operator=(LibCuda const&) = delete;
  LibCuda& operator=(LibCuda&&)      = delete;
  ~LibCuda() { ::dlclose(_handle); }

  static void* _load()
  {
    std::string lib_names[] = {"libcuda.so.1"};  // NOLINT(modernize-avoid-c-arrays)
    return load_dso("libcuda.so", lib_names);
  }

 private:
  void _load_symbols()
  {
#define DO_IT(func) \
  this->func =      \
    reinterpret_cast<decltype(cu##func)*>(get_dso_symbol("libcuda", _handle, "cu" #func));

    FOR_EACH_CUDA_FUNC(DO_IT)

#undef DO_IT
  }
};

struct LibNVRTC {
  void* _handle = nullptr;

#define DO_IT(func) decltype(::nvrtc##func)* func = nullptr;
  FOR_EACH_NVRTC_FUNC(DO_IT)
#undef DO_IT

  explicit LibNVRTC(void* handle) : _handle(handle) { _load_symbols(); }
  LibNVRTC(LibNVRTC const&)            = delete;
  LibNVRTC(LibNVRTC&&)                 = delete;
  LibNVRTC& operator=(LibNVRTC const&) = delete;
  LibNVRTC& operator=(LibNVRTC&&)      = delete;
  ~LibNVRTC()
  {
#if !RTCX_STATIC_LINK_LIBNVRTC
    ::dlclose(_handle);
#endif
  }

  static void* _load()
  {
#if !RTCX_STATIC_LINK_LIBNVRTC
    auto expected_major_version = major_version(CUDA_VERSION);
    std::int32_t cuda_version;
    RTCX_CHECK_CUDART(::cudaRuntimeGetVersion(&cuda_version));
    std::int32_t major = major_version(cuda_version);
    RTCX_EXPECTS(expected_major_version == major,
                 std::format("LibNVRTC Compatibility Error: CUDA major version mismatch. Expected "
                             "major runtime version: {}, got major runtime version: {})",
                             expected_major_version,
                             major),
                 std::runtime_error);

    std::string lib_names[] =  // NOLINT(modernize-avoid-c-arrays)
      {std::format("libnvrtc.so.{}", major)};

    return load_dso("libnvrtc.so", lib_names);
#else
    return nullptr;
#endif
  }

 private:
  void _load_symbols()
  {
#if !RTCX_STATIC_LINK_LIBNVRTC
#define DO_IT(func) \
  this->func =      \
    reinterpret_cast<decltype(nvrtc##func)*>(get_dso_symbol("libnvrtc", _handle, "nvrtc" #func));
#else
#define DO_IT(func) this->func = ::nvrtc##func;
#endif

    FOR_EACH_NVRTC_FUNC(DO_IT)
#undef DO_IT
  }
};

struct LibNVJitLink {
  void* _handle = nullptr;

#define DO_IT(func) decltype(::nvJitLink##func)* func = nullptr;
  FOR_EACH_NVJITLINK_FUNC(DO_IT)
#undef DO_IT

  explicit LibNVJitLink(void* handle) : _handle(handle) { _load_symbols(); }
  LibNVJitLink(LibNVJitLink const&)            = delete;
  LibNVJitLink(LibNVJitLink&&)                 = delete;
  LibNVJitLink& operator=(LibNVJitLink const&) = delete;
  LibNVJitLink& operator=(LibNVJitLink&&)      = delete;
  ~LibNVJitLink()
  {
#if !RTCX_STATIC_LINK_LIBNVJITLINK
    ::dlclose(_handle);
#endif
  }

  static void* _load()
  {
#if !RTCX_STATIC_LINK_LIBNVJITLINK
    auto expected_major_version = major_version(CUDA_VERSION);
    std::int32_t cuda_version;
    RTCX_CHECK_CUDART(::cudaRuntimeGetVersion(&cuda_version));
    std::int32_t major = major_version(cuda_version);
    RTCX_EXPECTS(
      expected_major_version == major,
      std::format("LibNVJitLink Compatibility Error: CUDA major version mismatch. Expected "
                  "major runtime version: {}, got major runtime version: {})",
                  expected_major_version,
                  major),
      std::runtime_error);

    std::string lib_names[] =  // NOLINT(modernize-avoid-c-arrays)
      {std::format("libnvJitLink.so.{}", major)};

    return load_dso("libnvJitLink.so", lib_names);
#else
    return nullptr;
#endif
  }

 private:
  void _load_symbols()
  {
#if !RTCX_STATIC_LINK_LIBNVJITLINK
#define DO_IT(func)                                          \
  this->func = reinterpret_cast<decltype(nvJitLink##func)*>( \
    get_dso_symbol("libnvJitLink", _handle, "nvJitLink" #func));
#else
#define DO_IT(func) this->func = ::nvJitLink##func;
#endif

    FOR_EACH_NVJITLINK_FUNC(DO_IT)
#undef DO_IT
  }
};

static std::optional<LibCuda> cu;
static std::optional<LibNVRTC> nvrtc;
static std::optional<LibNVJitLink> nvjitlink;
static std::optional<std::once_flag> init_libraries_flag{std::in_place};
static std::optional<std::once_flag> teardown_libraries_flag{std::in_place};

}  // namespace

void initialize()
{
  RTCX_FUNC_RANGE();

  std::call_once(init_libraries_flag.value(), [] {
    cu.emplace(LibCuda::_load());
    RTCX_EXPECTS(
      cu->Init(0) == CUDA_SUCCESS, "Failed to initialize CUDA driver API", std::runtime_error);
    nvrtc.emplace(LibNVRTC::_load());
    nvjitlink.emplace(LibNVJitLink::_load());
  });
}

void teardown()
{
  RTCX_FUNC_RANGE();

  std::call_once(teardown_libraries_flag.value(), [] {
    nvjitlink.reset();
    nvrtc.reset();
    cu.reset();
    init_libraries_flag.reset();
    teardown_libraries_flag.reset();
    init_libraries_flag.emplace();
    teardown_libraries_flag.emplace();
  });
}

blob_t blob_t::from_buffer(byte_buffer buffer)
{
  auto size = buffer.size();
  auto data = buffer.release();
  return blob_t::from_parts(
    data, size, +[](std::uint8_t const* data, std::size_t) {
      ::free(const_cast<std::uint8_t*>(data));
    });
}

blob_t blob_t::from_static_data(std::span<std::uint8_t const> data)
{
  return blob_t::from_parts(data.data(), data.size(), blob_t::noop_deallocator);
}

namespace {
void log_nvrtc_result(compile_params const& params,
                      nvrtcProgram program,
                      nvrtcResult compile_result)
{
  if (program == nullptr) { return; }

  std::size_t log_size;
  if (auto errc = nvrtc->GetProgramLogSize(program, &log_size); errc != NVRTC_SUCCESS) {
    RTCX_FAIL(std::format("Failed to get NVRTC program log size with error ({}): {}",
                          static_cast<std::int64_t>(errc),
                          nvrtc->GetErrorString(errc)),
              std::runtime_error);
  }

  std::vector<char> log;

  if (log_size > 1) {
    log.resize(log_size);
    if (auto errc = nvrtc->GetProgramLog(program, log.data()); errc != NVRTC_SUCCESS) {
      RTCX_FAIL(std::format("Failed to get NVRTC program log with error ({}): {}",
                            static_cast<std::int64_t>(errc),
                            nvrtc->GetErrorString(errc)),
                std::runtime_error);
    }
  }

  log.resize(log_size == 0 ? 0 : (log_size - 1));

  auto status_str =
    (compile_result == NVRTC_SUCCESS && !log.empty()) ? "completed with" : "failed with";

  std::string headers_str;
  for (auto& header : params.header_include_names) {
    headers_str = std::format("{}\t{}\n", headers_str, header);
  }

  std::string options_str;
  for (auto& option : params.options) {
    options_str = std::format("{}\t{}\n", options_str, option);
  }

  if (log.empty()) { return; }

  auto msg = std::format(
    "NVRTC Compilation for `{}` {} ({}): {}.\nHeaders:\n{}\n\nOptions:\n{}\n\nLog:\n\t{}",
    params.name == nullptr ? "<unnamed>" : params.name,
    status_str,
    static_cast<std::int64_t>(compile_result),
    nvrtc->GetErrorString(compile_result),
    headers_str,
    options_str,
    std::string_view{log.data(), log.size()});

  if (compile_result != NVRTC_SUCCESS) {
    log_error(msg);
  } else {
    log_warning(msg);
  }
}

void log_nvJitLink_result(link_params const& params,
                          nvJitLinkHandle handle,
                          nvJitLinkResult link_result)
{
  if (handle == nullptr) { return; }

  std::size_t info_log_size;
  if (auto errc = nvjitlink->GetInfoLogSize(handle, &info_log_size); errc != NVJITLINK_SUCCESS) {
    RTCX_FAIL(std::format("Failed to get nvJitLink info log size with error ({}): {}",
                          static_cast<std::int64_t>(errc),
                          nvJitLinkResult_string(errc)),
              std::runtime_error);
  }

  std::vector<char> info_log;
  if (info_log_size > 1) {
    info_log.resize(info_log_size);
    if (auto errc = nvjitlink->GetInfoLog(handle, info_log.data()); errc != NVJITLINK_SUCCESS) {
      RTCX_FAIL(std::format("Failed to get nvJitLink info log with error ({}): {}",
                            static_cast<std::int64_t>(errc),
                            nvJitLinkResult_string(errc)),
                std::runtime_error);
    }
  }

  info_log.resize(info_log_size == 0 ? 0 : (info_log_size - 1));

  std::size_t error_log_size;
  if (auto errc = nvjitlink->GetErrorLogSize(handle, &error_log_size); errc != NVJITLINK_SUCCESS) {
    RTCX_FAIL(std::format("Failed to get nvJitLink error log size with error ({}): {}",
                          static_cast<std::int64_t>(errc),
                          nvJitLinkResult_string(errc)),
              std::runtime_error);
  }

  std::vector<char> error_log;

  if (error_log_size > 1) {
    error_log.resize(error_log_size);
    if (auto errc = nvjitlink->GetErrorLog(handle, error_log.data()); errc != NVJITLINK_SUCCESS) {
      RTCX_FAIL(std::format("Failed to get nvJitLink error log with error ({}): {}",
                            static_cast<std::int64_t>(errc),
                            nvJitLinkResult_string(errc)),
                std::runtime_error);
    }
  }

  error_log.resize(error_log_size == 0 ? 0 : (error_log_size - 1));

  if (info_log.empty() && error_log.empty()) { return; }

  std::string fragments_str;
  for (auto& frag : params.file_fragments) {
    fragments_str = std::format("{}\t{}\n", fragments_str, frag.path);
  }

  for (auto& frag : params.memory_fragments) {
    fragments_str =
      std::format("{}\t{}\n", fragments_str, frag.name == nullptr ? "<unnamed>" : frag.name);
  }

  std::string link_options_str;
  for (auto& option : params.link_options) {
    link_options_str = std::format("{}\t{}\n", link_options_str, option);
  }

  auto status_str = link_result == NVJITLINK_SUCCESS ? "completed with" : "failed with";

  auto msg = std::format(
    "(nvJitLink) Linking for `{}` ({}) {} error code ({}): {}.\nFragments: \n{}\n"
    "Link Options: \n{}\n\nInfo Log:\n\t{}\n\nError Log:\n\t{}\n\n",
    params.name == nullptr ? "<unnamed>" : params.name,
    binary_type_string(params.output_type),
    status_str,
    static_cast<std::int64_t>(link_result),
    nvJitLinkResult_string(link_result),
    fragments_str,
    link_options_str,
    std::string_view{info_log.data(), info_log.size()},
    std::string_view{error_log.data(), error_log.size()});

  bool needs_info_log =
    std::find_if(
      params.link_options.begin(), params.link_options.end(), [](std::string_view option) {
        return option == "--verbose" || option == "-time";
      }) != params.link_options.end();

  if (link_result == NVJITLINK_SUCCESS) {
    if (needs_info_log) { log_warning(msg); }
  } else {
    log_error(msg);
  }
}

}  // namespace

std::int32_t nvrtc_version()
{
  RTCX_FUNC_RANGE();

  std::int32_t major, minor;
  RTCX_CHECK_NVRTC(nvrtc->Version(&major, &minor));
  return major * 1000 + minor * 10;
}

std::int32_t nvjitlink_version()
{
  RTCX_FUNC_RANGE();

  std::uint32_t major, minor;
  RTCX_CHECK_NVJITLINK(nvjitlink->Version(&major, &minor));
  return static_cast<std::int32_t>(major * 1000 + minor * 10);
}

byte_buffer compile(compile_params const& params)
{
  RTCX_FUNC_RANGE();

  RTCX_EXPECTS(params.name != nullptr, "Fragment name must not be null", std::logic_error);
  RTCX_EXPECTS(params.source != nullptr, "Fragment source must not be null", std::logic_error);

  nvrtcProgram program = nullptr;
  RTCX_CHECK_NVRTC(nvrtc->CreateProgram(&program,
                                        params.source,
                                        params.name,
                                        static_cast<std::int32_t>(params.headers.size()),
                                        params.headers.data(),
                                        params.header_include_names.data()));

  RTCX_DEFER([&] { nvrtc->DestroyProgram(&program); });

  for (auto* name_expr : params.name_expressions) {
    RTCX_CHECK_NVRTC(nvrtc->AddNameExpression(program, name_expr));
  }

  auto compile_result = nvrtc->CompileProgram(
    program, static_cast<std::int32_t>(params.options.size()), params.options.data());
  log_nvrtc_result(params, program, compile_result);
  RTCX_CHECK_NVRTC(compile_result);

  switch (params.target_type) {
    case binary_type::CUBIN: {
      std::size_t cubin_size;
      RTCX_CHECK_NVRTC(nvrtc->GetCUBINSize(program, &cubin_size));
      auto cubin = byte_buffer::make(cubin_size);
      RTCX_CHECK_NVRTC(nvrtc->GetCUBIN(program, reinterpret_cast<char*>(cubin.data())));
      return cubin;
    } break;
    case binary_type::LTO_IR: {
      std::size_t lto_ir_size;
      RTCX_CHECK_NVRTC(nvrtc->GetLTOIRSize(program, &lto_ir_size));
      auto lto_ir = byte_buffer::make(lto_ir_size);
      RTCX_CHECK_NVRTC(nvrtc->GetLTOIR(program, reinterpret_cast<char*>(lto_ir.data())));
      return lto_ir;
    } break;
    case binary_type::PTX: {
      std::size_t ptx_size;
      RTCX_CHECK_NVRTC(nvrtc->GetPTXSize(program, &ptx_size));
      auto ptx = byte_buffer::make(ptx_size);
      RTCX_CHECK_NVRTC(nvrtc->GetPTX(program, reinterpret_cast<char*>(ptx.data())));
      return ptx;
    } break;
    default:
      RTCX_FAIL(std::format("Unsupported binary type for compiling fragment: {}",
                            binary_type_string(params.target_type)),
                std::logic_error);
  }
}

kernel_occupancy_config kernel_ref::max_occupancy_config(std::size_t dynamic_shared_memory_bytes,
                                                         std::int32_t block_size_limit) const
{
  std::int32_t min_grid_size;
  std::int32_t block_size;
  RTCX_CHECK_CUDA(cu->OccupancyMaxPotentialBlockSize(&min_grid_size,
                                                     &block_size,
                                                     reinterpret_cast<CUfunction>(handle_),
                                                     nullptr,
                                                     dynamic_shared_memory_bytes,
                                                     block_size_limit));

  return kernel_occupancy_config{.min_grid_size = static_cast<std::uint32_t>(min_grid_size),
                                 .block_size    = static_cast<std::uint32_t>(block_size)};
}

void kernel_ref::launch(cuda_dim3 grid_dim,
                        cuda_dim3 block_dim,
                        std::uint32_t shared_mem_bytes,
                        CUstream stream,
                        void** kernel_params) const
{
  RTCX_FUNC_RANGE();

  RTCX_EXPECTS(grid_dim.is_valid(), "Grid dimensions must be greater than zero", std::logic_error);
  RTCX_EXPECTS(
    block_dim.is_valid(), "Block dimensions must be greater than zero", std::logic_error);
  RTCX_EXPECTS(
    kernel_params != nullptr, "Kernel parameters pointer must not be null", std::logic_error);

  CUlaunchConfig cfg{.gridDimX       = grid_dim.x,
                     .gridDimY       = grid_dim.y,
                     .gridDimZ       = grid_dim.z,
                     .blockDimX      = block_dim.x,
                     .blockDimY      = block_dim.y,
                     .blockDimZ      = block_dim.z,
                     .sharedMemBytes = shared_mem_bytes,
                     .hStream        = stream,
                     .attrs          = nullptr,
                     .numAttrs       = 0};

  RTCX_CHECK_CUDA(
    cu->LaunchKernelEx(&cfg, reinterpret_cast<CUfunction>(handle_), kernel_params, nullptr));
}

void kernel_ref::launch_cooperative(cuda_dim3 grid_dim,
                                    cuda_dim3 block_dim,
                                    std::uint32_t shared_mem_bytes,
                                    CUstream stream,
                                    void** kernel_params) const
{
  RTCX_FUNC_RANGE();

  RTCX_EXPECTS(grid_dim.is_valid(), "Grid dimensions must be greater than zero", std::logic_error);
  RTCX_EXPECTS(
    block_dim.is_valid(), "Block dimensions must be greater than zero", std::logic_error);
  RTCX_EXPECTS(
    kernel_params != nullptr, "Kernel parameters pointer must not be null", std::logic_error);

  RTCX_CHECK_CUDA(cu->LaunchCooperativeKernel(reinterpret_cast<CUfunction>(handle_),
                                              grid_dim.x,
                                              grid_dim.y,
                                              grid_dim.z,
                                              block_dim.x,
                                              block_dim.y,
                                              block_dim.z,
                                              shared_mem_bytes,
                                              stream,
                                              kernel_params));
}

library_t::~library_t()
{
  if (handle_ != nullptr) { cu->LibraryUnload(handle_); }
}

library load_library(std::span<std::uint8_t const> binary)
{
  RTCX_FUNC_RANGE();

  CUlibrary handle;

  RTCX_CHECK_CUDA(
    cu->LibraryLoadData(&handle, binary.data(), nullptr, nullptr, 0, nullptr, nullptr, 0));

  RTCX_DEFER([&] {
    if (handle != nullptr) { RTCX_CHECK_CUDA(cu->LibraryUnload(handle)); }
  });

  auto library = std::make_shared<library_t>(handle);

  handle = nullptr;

  return library;
}

library load_library_from_file(char const* path)
{
  RTCX_FUNC_RANGE();

  RTCX_EXPECTS(path != nullptr, "Library path must not be null", std::logic_error);

  CUlibrary handle;

  RTCX_CHECK_CUDA(cu->LibraryLoadFromFile(&handle, path, nullptr, nullptr, 0, nullptr, nullptr, 0));

  RTCX_DEFER([&] {
    if (handle != nullptr) { RTCX_CHECK_CUDA(cu->LibraryUnload(handle)); }
  });

  auto library = std::make_shared<library_t>(handle);

  handle = nullptr;

  return library;
}

byte_buffer link_library(link_params const& params)
{
  RTCX_FUNC_RANGE();

  RTCX_EXPECTS(params.name != nullptr, "Link output name must not be null", std::logic_error);
  RTCX_EXPECTS(params.output_type == binary_type::CUBIN || params.output_type == binary_type::PTX,
               "Only CUBIN and PTX output types are supported for linking modules",
               std::logic_error);
  RTCX_EXPECTS(params.file_fragments.size() != 0 || params.memory_fragments.size() != 0,
               "At least one fragment must be provided for linking",
               std::logic_error);

  for (auto& frag : params.file_fragments) {
    RTCX_EXPECTS(frag.path != nullptr, "Fragment file path must not be empty", std::logic_error);
  }

  for (auto& frag : params.memory_fragments) {
    RTCX_EXPECTS(
      frag.data.size_bytes() > 0, "Fragment binary data must be non-empty", std::logic_error);
  }

  nvJitLinkHandle handle = nullptr;
  RTCX_CHECK_NVJITLINK(nvjitlink->Create(&handle,
                                         static_cast<std::uint32_t>(params.link_options.size()),
                                         const_cast<char const**>(params.link_options.data())));

  RTCX_DEFER([&] { nvjitlink->Destroy(&handle); });

  for (auto& frag : params.file_fragments) {
    RTCX_CHECK_NVJITLINK(nvjitlink->AddFile(handle, to_nvjitlink_input_type(frag.type), frag.path));
  }

  for (auto& frag : params.memory_fragments) {
    RTCX_CHECK_NVJITLINK(nvjitlink->AddData(handle,
                                            to_nvjitlink_input_type(frag.type),
                                            frag.data.data(),
                                            frag.data.size_bytes(),
                                            frag.name));
  }

  auto link_result = nvjitlink->Complete(handle);
  log_nvJitLink_result(params, handle, link_result);
  RTCX_CHECK_NVJITLINK(link_result);

  switch (params.output_type) {
    case binary_type::CUBIN: {
      std::size_t cubin_size;
      RTCX_CHECK_NVJITLINK(nvjitlink->GetLinkedCubinSize(handle, &cubin_size));
      auto cubin = byte_buffer::make(cubin_size);
      RTCX_CHECK_NVJITLINK(nvjitlink->GetLinkedCubin(handle, cubin.data()));
      return cubin;
    } break;
    case binary_type::PTX: {
      std::size_t ptx_size;
      RTCX_CHECK_NVJITLINK(nvjitlink->GetLinkedPtxSize(handle, &ptx_size));
      auto ptx = byte_buffer::make(ptx_size);
      RTCX_CHECK_NVJITLINK(nvjitlink->GetLinkedPtx(handle, reinterpret_cast<char*>(ptx.data())));
      return ptx;
    } break;
    default:
      RTCX_FAIL(std::format("Unsupported output binary type for linking CUDA libraries: ({})",
                            binary_type_string(params.output_type)),
                std::runtime_error);
  }
}

kernel_ref library_t::get_kernel(char const* name) const
{
  RTCX_FUNC_RANGE();

  CUkernel kernel;
  RTCX_CHECK_CUDA(cu->LibraryGetKernel(&kernel, handle_, name));
  return kernel_ref{kernel};
}

namespace {

[[noreturn]] void throw_posix(std::string_view message, std::string_view syscall_name)
{
  auto errc = errno;
  RTCX_FAIL(
    std::format("{}. `{}` failed with {} ({})", message, syscall_name, errc, std::strerror(errc)),
    std::runtime_error);
}

}  // namespace

cache_t::cache_t(std::string cache_dir,
                 std::string tmp_dir,
                 cache_limits const& limits,
                 bool preload,
                 bool disable)
  : enabled_{!disable},
    cache_dir_{std::move(cache_dir)},
    tmp_dir_{std::move(tmp_dir)},
    limits_{limits},
    lock_{},
    blobs_cache_{limits.num_mem_blobs},
    libraries_cache_{limits.num_mem_libraries},
    tick_{0}
{
  if (preload) { preload_from_disk(); }
}

std::string const& cache_t::get_cache_dir() { return cache_dir_; }

std::string const& cache_t::get_tmp_dir() { return tmp_dir_; }

std::optional<blob_t> blob_t::from_file(char const* path)
{
  std::int32_t fd = ::open(path, O_RDONLY);

  if (fd == -1) {
    if (errno == ENOENT) {
      return std::nullopt;
    } else {
      throw_posix("Failed to open RTCX cache file from disk", "open");
    }
  }

  RTCX_DEFER([&] {
    if (::close(fd) == -1) {
      throw_posix("Failed to close RTCX cache file after memory-mapping", "close");
    }
  });

  auto file_size = ::lseek(fd, 0, SEEK_END);
  if (file_size == -1) { throw_posix("Failed to determine size of RTCX cache file", "lseek"); }

  if (file_size == 0) {
    // mmap does not support mapping zero-length files, so we return an empty blob in this case
    return blob_t::from_static_data({});
  }

  void* map = ::mmap(nullptr, file_size, PROT_READ, MAP_SHARED, fd, 0);

  if (map == MAP_FAILED) { throw_posix("Failed to memory-map RTCX cache file", "mmap"); }

  auto deleter = +[](std::uint8_t const* buffer, std::size_t size) {
    if (::munmap(static_cast<void*>(const_cast<std::uint8_t*>(buffer)), size) == -1) {
      throw_posix("Failed to unmap RTCX cache file from memory", "munmap");
    }
  };

  return blob_t::from_parts(static_cast<std::uint8_t const*>(map), file_size, deleter);
}

namespace {

/// @brief retrieves a blob from disk based on the given hash and object type (e.g. "blob",
/// "cuLibrary"). Returns nullopt if the file doesn't exist on disk, and throws if any other error
/// occurs.
std::optional<blob> get_disk_blob(std::string const& cache_dir,
                                  object_type type,
                                  hash128 const& hash)
{
  auto hex  = hash.to_hex_string();
  auto path = std::format("{}/{}.{}.bin", cache_dir, hex.view(), object_tag(type));
  auto blob = blob_t::from_file(path.c_str());

  if (!blob.has_value()) { return std::nullopt; }
  return std::make_shared<blob_t>(std::move(*blob));
}

std::optional<library> get_disk_library(std::string const& cache_dir, hash128 const& hash)
{
  RTCX_FUNC_RANGE();

  auto hex  = hash.to_hex_string();
  auto path = std::format("{}/{}.{}.bin", cache_dir, hex.view(), object_tag(object_type::LIBRARY));

  // WAR: avoid a driver API call when the cache file is not present
  // compute-sanitizer doesn't properly handle exceptions thrown from driver API calls, so we need
  // to check for file existence first to avoid false positives in the sanitizer
  if (!std::filesystem::exists(path)) { return std::nullopt; }

  CUlibrary handle;
  auto errc =
    cu->LibraryLoadFromFile(&handle, path.c_str(), nullptr, nullptr, 0, nullptr, nullptr, 0);

  if (errc == CUDA_ERROR_FILE_NOT_FOUND) { return std::nullopt; }

  RTCX_EXPECTS(errc == CUDA_SUCCESS,
               std::format("Failed to load library `{}` from RTCX cache file", path),
               std::runtime_error);

  return std::make_shared<library_t>(handle);
}

std::vector<std::string> get_disk_entries(std::string const& cache_dir)
{
  std::vector<std::string> entries;
  for (auto& entry : std::filesystem::directory_iterator(cache_dir)) {
    if (!entry.is_regular_file()) { continue; }
    entries.push_back(entry.path().string());
  }

  return entries;
}

/// @brief atomically writes a blob to disk by first writing to a temporary file and then renaming
/// it to the final path.
void cache_blob_to_disk(std::string const& cache_dir,
                        std::string const& tmp_dir,
                        object_type type,
                        hash128 const& hash,
                        std::span<std::uint8_t const> binary)
{
  RTCX_FUNC_RANGE();

  auto tmp_path = std::format("{}/rtcx-bin-XXXXXX", tmp_dir);
  (void)tmp_path.c_str();  // to ensure null-termination for mkstemp

  {
    std::int32_t fd = ::mkstemp(tmp_path.data());
    if (fd == -1) { throw_posix("Failed to create temporary file for RTCX cache", "mkstemp"); }

    RTCX_DEFER([&] {
      if (::close(fd) == -1) { throw_posix("Failed to close temporary RTCX cache file", "close"); }
    });

    {
      auto ptr       = binary.data();
      auto remaining = binary.size();
      while (remaining > 0) {
        auto written = ::write(fd, ptr, remaining);
        if (written == -1) { throw_posix("Failed to write RTCX cache to temporary file", "write"); }
        ptr += static_cast<std::size_t>(written);
        remaining -= static_cast<std::size_t>(written);
      }
    }
  }

  auto hex        = hash.to_hex_string();
  auto final_path = std::format("{}/{}.{}.bin", cache_dir, hex.view(), object_tag(type));

  std::filesystem::create_directories(std::filesystem::path{final_path}.parent_path());

  // rename is atomic, even if another process is performing the same operation
  if (::rename(tmp_path.c_str(), final_path.c_str()) == -1) {
    if (errno == EEXIST) {
      // another process has already created the file, so just remove our temp file
      if (::remove(tmp_path.c_str()) == -1) {
        throw_posix("Failed to remove temporary RTCX cache file", "remove");
      }
      return;
    } else {
      throw_posix(
        std::format("Failed to move temporary RTCX cache file to final location ({})", final_path),
        "rename");
    }
  }
}

}  // namespace

std::shared_future<blob> cache_t::get_or_add_blob(hash128 const& hash, blob_compile_func compile)
{
  RTCX_FUNC_RANGE();

  std::atomic_ref tick{tick_};
  auto current_tick = tick.fetch_add(1, std::memory_order_relaxed);

  std::unique_lock lock{lock_};

  // check memory cache
  if (auto it = enabled_ ? blobs_cache_.entries_.find(hash) : blobs_cache_.entries_.end();
      it != blobs_cache_.entries_.end()) {
    counter_.blob_mem_hits.incr();

    // update LRU tick
    it->second.hit(current_tick);

    return it->second.value;

  } else {
    counter_.blob_mem_misses.incr();

    // check disk cache
    std::optional<blob> disk_blob = std::nullopt;
    if (enabled_) { disk_blob = get_disk_blob(cache_dir_, object_type::BLOB, hash); }

    std::promise<blob> promise;
    auto fut       = promise.get_future().share();
    auto cache_fut = fut;
    auto ret_fut   = fut;

    if (disk_blob.has_value()) {
      counter_.blob_disk_hits.incr();

      promise.set_value(std::move(*disk_blob));

      // insert into cache
      blobs_cache_.insert(hash, std::move(cache_fut), current_tick);

      return ret_fut;

    } else {
      counter_.blob_disk_misses.incr();

      blobs_cache_.insert(hash, std::move(cache_fut), current_tick);

      // we can release the lock while calling the maker function since it may be expensive and we
      // have already reserved a spot in the cache for this hash
      lock.unlock();

      auto result = compile();
      promise.set_value(result);

      cache_blob_to_disk(cache_dir_, tmp_dir_, object_type::BLOB, hash, result->view());

      return ret_fut;
    }
  }
}

std::shared_future<library> cache_t::get_or_add_library(hash128 const& hash,
                                                        library_compile_func compile)
{
  RTCX_FUNC_RANGE();

  std::atomic_ref tick{tick_};
  auto current_tick = tick.fetch_add(1, std::memory_order_relaxed);

  std::unique_lock lock{lock_};

  // check memory cache
  if (auto it = enabled_ ? libraries_cache_.entries_.find(hash) : libraries_cache_.entries_.end();
      it != libraries_cache_.entries_.end()) {
    counter_.library_mem_hits.incr();

    // update LRU tick
    it->second.hit(current_tick);

    return it->second.value;

  } else {
    counter_.library_mem_misses.incr();

    // check disk cache
    std::optional<library> disk_library = std::nullopt;
    if (enabled_) { disk_library = get_disk_library(cache_dir_, hash); }

    std::promise<library> promise;
    auto fut       = promise.get_future().share();
    auto cache_fut = fut;
    auto ret_fut   = fut;

    if (disk_library.has_value()) {
      counter_.library_disk_hits.incr();

      libraries_cache_.insert(hash, std::move(cache_fut), current_tick);

      // we can release the lock while calling the maker function since it may be expensive and we
      // have already reserved a spot in the cache for this hash
      lock.unlock();

      promise.set_value(std::move(*disk_library));

      return ret_fut;

    } else {
      counter_.library_disk_misses.incr();

      libraries_cache_.insert(hash, std::move(cache_fut), current_tick);

      // we can release the lock while calling the maker function since it may be expensive and we
      // have already reserved a spot in the cache for this hash
      lock.unlock();

      auto [library, blob] = compile();
      promise.set_value(library);

      // store result to disk
      cache_blob_to_disk(cache_dir_, tmp_dir_, object_type::LIBRARY, hash, blob->view());

      return ret_fut;
    }
  }
}

cache_stats cache_t::get_stats()
{
  return cache_stats{.blob_mem_hits       = counter_.blob_mem_hits.get(),
                     .blob_mem_misses     = counter_.blob_mem_misses.get(),
                     .blob_disk_hits      = counter_.blob_disk_hits.get(),
                     .blob_disk_misses    = counter_.blob_disk_misses.get(),
                     .library_mem_hits    = counter_.library_mem_hits.get(),
                     .library_mem_misses  = counter_.library_mem_misses.get(),
                     .library_disk_hits   = counter_.library_disk_hits.get(),
                     .library_disk_misses = counter_.library_disk_misses.get()};
}

void cache_t::clear_stats()
{
  counter_.blob_mem_hits.reset();
  counter_.blob_mem_misses.reset();
  counter_.blob_disk_hits.reset();
  counter_.blob_disk_misses.reset();
  counter_.library_mem_hits.reset();
  counter_.library_mem_misses.reset();
  counter_.library_disk_hits.reset();
  counter_.library_disk_misses.reset();
}

cache_limits cache_t::get_limits() { return limits_; }

std::size_t cache_t::get_blob_count()
{
  std::lock_guard guard{lock_};
  return blobs_cache_.entries_.size();
}

std::size_t cache_t::get_library_count()
{
  std::lock_guard guard{lock_};
  return libraries_cache_.entries_.size();
}

void cache_t::clear_memory_store()
{
  RTCX_FUNC_RANGE();

  std::lock_guard guard{lock_};

  blobs_cache_.entries_.clear();
  libraries_cache_.entries_.clear();
}

void cache_t::clear_disk_store()
{
  RTCX_FUNC_RANGE();

  auto entries = get_disk_entries(cache_dir_);

  for (auto const& path : entries) {
    try {
      std::filesystem::remove(path);
    } catch (...) {
      log_error(std::format("Unknown error occurred while removing RTCX cache file `{}`", path));
    }
  }
}

void cache_t::preload_from_disk()
{
  RTCX_FUNC_RANGE();

  auto entries = get_disk_entries(cache_dir_);

  auto load_count =
    std::min<std::size_t>(entries.size(), limits_.num_mem_blobs + limits_.num_mem_libraries);

  entries.resize(load_count);

  {
    std::lock_guard guard{lock_};
    tick_++;

    for (auto const& path : entries) {
      try {
        auto file_name = std::filesystem::path{path}.filename().string();
        auto hash_str  = file_name.substr(0, file_name.find('.'));
        auto hash      = hash128::parse(hash_str);

        if (path.ends_with(".blob.bin")) {
          auto data = blob_t::from_file(path.c_str());
          if (!data.has_value()) { continue; }
          auto blob = std::make_shared<blob_t>(std::move(*data));
          std::promise<rtcx::blob> promise;
          auto fut = promise.get_future().share();
          promise.set_value(std::move(blob));
          blobs_cache_.insert(hash, std::move(fut), tick_);
        } else if (path.ends_with(".cuLibrary.bin")) {
          auto lib = get_disk_library(cache_dir_, hash);
          if (!lib.has_value()) { continue; }
          std::promise<library> promise;
          auto fut = promise.get_future().share();
          promise.set_value(std::move(*lib));
          libraries_cache_.insert(hash, std::move(fut), tick_);
        }
      } catch (std::exception const& e) {
        // ignore any errors during preload
        log_error(e.what());
      } catch (...) {
        log_error("Unknown error during preload");
      }
    }
  }
}

void cache_t::enable(bool enable)
{
  std::lock_guard guard{lock_};
  enabled_ = enable;
}

bool cache_t::is_enabled()
{
  std::lock_guard guard{lock_};
  return enabled_;
}

std::string reflect_template(std::string_view template_name,
                             std::span<std::string_view const> template_args)
{
  return std::format("{}<{}>", template_name, join_strings(template_args, ", "));
}

std::string reflect_template(std::string_view template_name,
                             std::span<std::string const> template_args)
{
  return std::format("{}<{}>", template_name, join_strings(template_args, ", "));
}

rtcx::byte_buffer decompress_blob(std::span<std::uint8_t const> compressed_binary,
                                  std::size_t uncompressed_size,
                                  std::string_view compression)
{
  RTCX_FUNC_RANGE();

  RTCX_EXPECTS(compression == "none" || compression == "zstd",
               std::format("Unsupported compression type specified: {}", compression),
               std::runtime_error);
  auto decompressed = rtcx::byte_buffer::make(uncompressed_size);

  if (compression == "zstd") {
    std::size_t errc = ::ZSTD_decompress(
      decompressed.data(), uncompressed_size, compressed_binary.data(), compressed_binary.size());

    RTCX_EXPECTS(
      !::ZSTD_isError(errc) && errc == uncompressed_size,
      std::format("Failed to decompress embedded RTC source files with ZSTD, error code {} : {}",
                  errc,
                  ::ZSTD_getErrorName(errc)),
      std::runtime_error);
  } else {
    // compression is "none", so just copy the data
    std::copy(compressed_binary.data(),
              compressed_binary.data() + compressed_binary.size(),
              decompressed.data());
  }

  return decompressed;
}

}  // namespace rtcx