playhead.h

// SPDX-FileCopyrightText: © 2025-2026 Alexandros Theodotou <alex@zrythm.org>
// SPDX-License-Identifier: LicenseRef-ZrythmLicense
 
#pragma once
 
#include <atomic>
#include <mutex>
 
#include "dsp/tempo_map.h"
 
namespace zrythm::dsp
{
using namespace std::string_view_literals;

class Playhead
{
  friend class PlayheadProcessingGuard;
 
public:
  Playhead (const TempoMap &tempo_map) : tempo_map_ (tempo_map) { }
 
  // Audio threads ONLY ----------------------------------------------------
 
private:
  void prepare_for_processing () noexcept
  {
    // Copy current position before processing
    const auto samples =
      position_samples_.load (std::memory_order_acquire).in (units::samples);
    position_samples_at_start_of_processing_ = samples;
    position_samples_processing_.store (samples, std::memory_order_release);
  }
 
public:
  void advance_processing (units::sample_t nframes) noexcept
  {
    if (nframes >= units::samples (0)) [[likely]]
      {
        position_samples_processing_.fetch_add (
          nframes.in<double> (units::samples));
      }
    else
      {
        position_samples_processing_.fetch_sub (
          -nframes.in<double> (units::samples));
      }
  }

  auto position_during_processing_precise () const noexcept
  {
    return position_samples_processing_.load (std::memory_order_acquire);
  }
  units::sample_t position_during_processing_rounded () const noexcept
  {
    return units::samples (
      static_cast<int64_t> (std::round (
        position_samples_processing_.load (std::memory_order_acquire))));
  }
 
private:
  void finalize_processing () noexcept
  {
    // Commit position only at end of block
    const auto processing_samples =
      position_samples_processing_.load (std::memory_order_acquire);
 
    // Atomically compare and exchange - only update if current value matches
    // start value (otherwise the position was changed by the user meanwhile and
    // we should honor that change)
    auto expected = units::samples (position_samples_at_start_of_processing_);
    position_samples_.compare_exchange_strong (
      expected, units::samples (processing_samples), std::memory_order_acq_rel,
      std::memory_order_acquire);
  }
 
  // GUI thread ONLY ------------------------------------------------------
 
public:
  void set_position_ticks (units::precise_tick_t ticks) [[clang::blocking]]
  {
    std::lock_guard lock (position_mutex_);
    position_ticks_ = ticks;
    position_samples_.store (
      tempo_map_.tick_to_samples (TimelineTick{ ticks }),
      std::memory_order_release);
  }

  auto position_ticks () const [[clang::blocking]]
  {
    std::lock_guard lock (position_mutex_);
    return position_ticks_;
  }
 
  // Any thread (non-RT) --------------------------------------------------

  void update_ticks_from_samples () [[clang::blocking]]
  {
    std::lock_guard lock (position_mutex_);
    position_ticks_ =
      tempo_map_
        .samples_to_tick (position_samples_.load (std::memory_order_acquire))
        .asQuantity ();
  }
 
  const auto &get_tempo_map () const { return tempo_map_; }

  auto position_samples_FOR_TESTING () const noexcept
  {
    return position_samples_.load (std::memory_order_acquire);
  }
 
private:
  // Serialization keys — Playhead stores its own mode + value rather than
  // reusing a generic position type in the project schema.
  static constexpr auto kMode = "mode"sv;
  static constexpr auto kValue = "value"sv;
  friend void           to_json (nlohmann::json &j, const Playhead &pos);
  friend void           from_json (const nlohmann::json &j, Playhead &pos);
 
private:
  const TempoMap &tempo_map_;
 
  // Audio thread state
  std::atomic<double> position_samples_processing_ = 0.0;
  double              position_samples_at_start_of_processing_{};
 
  // Shared state (protected)
  std::atomic<units::precise_sample_t> position_samples_;
  units::precise_tick_t                position_ticks_;
  mutable std::mutex                   position_mutex_;
 
  static_assert (decltype (position_samples_)::is_always_lock_free);
};

class PlayheadProcessingGuard
{
public:
  explicit PlayheadProcessingGuard (Playhead &playhead) noexcept
      : playhead_ (playhead)
  {
    playhead_.prepare_for_processing ();
  }

  ~PlayheadProcessingGuard () noexcept { playhead_.finalize_processing (); }
 
  // Prevent copying
  PlayheadProcessingGuard (const PlayheadProcessingGuard &) = delete;
  PlayheadProcessingGuard &operator= (const PlayheadProcessingGuard &) = delete;
 
private:
  Playhead &playhead_;
};
 
} // namespace zrythm::dsp