observation.hpp

/*
 * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 */
 
#pragma once
 
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <string_view>
#include <type_traits>
 
#include <kvikio/shim/utils.hpp>
 
namespace KVIKIO_EXPORT kvikio {
 
using Clock = std::chrono::steady_clock;
 
using TimePoint = Clock::time_point;
 
using Duration = std::chrono::nanoseconds;
 
struct ClockAnchor {
  TimePoint steady{};
  std::chrono::system_clock::time_point wall{};
 
  [[nodiscard]] static ClockAnchor now() noexcept;
 
  [[nodiscard]] std::chrono::system_clock::time_point to_wall_clock(TimePoint time) const noexcept
  {
    // Chrono is not noexcept because a duration's representation may have throwing arithmetic, and
    // duration_cast is specified in terms of the same operations. Ours are integers, so nothing
    // here can throw.
    static_assert(std::is_integral_v<TimePoint::rep>);
    static_assert(std::is_integral_v<std::chrono::system_clock::rep>);
    return wall + std::chrono::duration_cast<std::chrono::system_clock::duration>(time - steady);
  }
};
 
enum class IoBackend : std::uint8_t {
  POSIX = 0,    
  GDS,          
  MMAP,         
  REMOTE_HTTP,  
  REMOTE_HDFS   
};
 
constexpr std::size_t num_io_backends = static_cast<std::size_t>(IoBackend::REMOTE_HDFS) + 1;
 
enum class TransferDirection : std::uint8_t {
  READ = 0,  
  WRITE      
};
 
enum class MemoryKind : std::uint8_t {
  HOST = 0,  
  DEVICE     
};
 
enum class ObservationKind : std::uint8_t {
  LOGICAL = 0  
};
 
[[nodiscard]] std::string_view to_string(IoBackend backend) noexcept;
 
[[nodiscard]] std::string_view to_string(TransferDirection direction) noexcept;
 
[[nodiscard]] std::string_view to_string(MemoryKind memory_kind) noexcept;
 
[[nodiscard]] std::string_view to_string(ObservationKind kind) noexcept;
 
struct Observation {
  TimePoint start{};
  TimePoint end{};
  std::size_t offset{};
  std::size_t size{};
  std::size_t bytes_transferred{};
  std::uint64_t id{};
 
  char const* http_method{nullptr};
 
  std::string_view source{};
 
  ObservationKind kind{ObservationKind::LOGICAL};
  IoBackend backend{IoBackend::POSIX};
  TransferDirection direction{TransferDirection::READ};
  MemoryKind memory_kind{MemoryKind::HOST};
  bool ok{true};
 
  [[nodiscard]] Duration duration() const noexcept
  {
    return end > start ? end - start : Duration::zero();
  }
 
  [[nodiscard]] double bytes_per_sec() const noexcept
  {
    auto const seconds = std::chrono::duration<double>{duration()}.count();
    return seconds > 0.0 ? static_cast<double>(bytes_transferred) / seconds : 0.0;
  }
};
 
class Monitor {
 public:
  Monitor()                          = default;
  virtual ~Monitor()                 = default;
  Monitor(Monitor const&)            = delete;
  Monitor& operator=(Monitor const&) = delete;
 
  virtual void on_start(Observation const& observation) noexcept = 0;
 
  virtual void on_finish(Observation const& observation) noexcept = 0;
};
 
[[nodiscard]] std::uint64_t register_monitor(Monitor* monitor,
                                             ObservationKind kind = ObservationKind::LOGICAL);
 
void unregister_monitor(std::uint64_t id);
 
}  // namespace KVIKIO_EXPORT kvikio