/*********************************************************************
 * Software License Agreement (BSD License)
 *
 *  Copyright (c) 2024
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met:
 *
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *   * Redistributions in binary form must reproduce the above
 *     copyright notice, this list of conditions and the following
 *     disclaimer in the documentation and/or other materials provided
 *     with the distribution.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 *********************************************************************/

#ifndef ROBOT_WALL_TIMER_H
#define ROBOT_WALL_TIMER_H

#include <robot/walltime.h>
#include "robot_time_decl.h"
#include <functional>
#include <thread>
#include <mutex>
#include <atomic>
#include <condition_variable>
#include <memory>

namespace robot
{

/**
 * @brief Structure containing information about a wall timer event
 * 
 * Similar to ros::WallTimerEvent, this structure is passed to wall timer callbacks
 * and contains timing information about the current and previous timer events.
 * Uses wall-clock time (not affected by simulated time).
 */
struct ROBOT_TIME_DECL WallTimerEvent
{
  /**
   * @brief The time when the current callback was actually called (wall-clock time)
   */
  WallTime current_real;

  /**
   * @brief The time when the current callback was expected to be called (wall-clock time)
   */
  WallTime current_expected;

  /**
   * @brief The time when the previous callback was actually called (wall-clock time)
   */
  WallTime last_real;

  /**
   * @brief The time when the previous callback was expected to be called (wall-clock time)
   */
  WallTime last_expected;

  /**
   * @brief The time between the last two callbacks (wall-clock duration)
   */
  WallDuration last_duration;

  /**
   * @brief Default constructor
   */
  WallTimerEvent()
    : current_real(WallTime::now())
    , current_expected(WallTime::now())
    , last_real(WallTime())
    , last_expected(WallTime())
    , last_duration(WallDuration())
  {}
};

/**
 * @class WallTimer
 * @brief A class to call a callback function at a specified rate using wall-clock time
 * 
 * This class is similar to ros::WallTimer. It creates a separate thread that
 * calls a callback function at a specified period. The callback receives
 * a WallTimerEvent structure containing timing information.
 * 
 * Unlike Timer, WallTimer always uses wall-clock time and is not affected
 * by simulated time. This makes it ideal for:
 * - Performance monitoring
 * - Real-time deadlines
 * - Hardware interfaces
 * - Profiling and benchmarking
 * 
 * Example usage:
 * @code
 * void myCallback(const robot::WallTimerEvent& event) {
 *   // Do something periodically
 * }
 * 
 * robot::WallTimer timer(robot::WallDuration(1.0), myCallback);
 * timer.start();
 * // ... later ...
 * timer.stop();
 * @endcode
 */
class ROBOT_TIME_DECL WallTimer
{
public:
  /**
   * @brief Callback function type for wall timer events
   */
  using Callback = std::function<void(const WallTimerEvent&)>;

  /**
   * @brief Default constructor - creates an uninitialized timer
   * Timer must be assigned or constructed with parameters before use
   */
  WallTimer();

  /**
   * @brief Constructor
   * @param period The period between timer callbacks (wall-clock duration)
   * @param callback The callback function to call
   * @param oneshot If true, the timer will only fire once. If false, it will fire repeatedly.
   * @param autostart If true, the timer will start automatically. If false, you must call start().
   */
  WallTimer(const WallDuration& period, 
            const Callback& callback,
            bool oneshot = false,
            bool autostart = true);

  /**
   * @brief Constructor with member function pointer
   * @param period The period between timer callbacks (wall-clock duration)
   * @param callback Member function pointer to call
   * @param obj Object instance to call the member function on
   * @param oneshot If true, the timer will only fire once. If false, it will fire repeatedly.
   * @param autostart If true, the timer will start automatically. If false, you must call start().
   * 
   * Example:
   * @code
   * class MyClass {
   *   void callback(const robot::WallTimerEvent& event) { }
   * };
   * MyClass obj;
   * robot::WallTimer timer(robot::WallDuration(1.0), &MyClass::callback, &obj);
   * @endcode
   */
  template<typename T>
  WallTimer(const WallDuration& period,
            void (T::*callback)(const WallTimerEvent&),
            T* obj,
            bool oneshot = false,
            bool autostart = true)
    : WallTimer(period, 
                [obj, callback](const WallTimerEvent& event) { (obj->*callback)(event); },
                oneshot,
                autostart)
  {}

  /**
   * @brief Copy constructor
   */
  WallTimer(const WallTimer& rhs);

  /**
   * @brief Destructor - stops the timer and joins the thread
   */
  ~WallTimer();

  /**
   * @brief Start the timer. Does nothing if the timer is already started.
   */
  void start();

  /**
   * @brief Stop the timer. Once this call returns, no more callbacks will be called.
   * Does nothing if the timer is already stopped.
   */
  void stop();

  /**
   * @brief Set the period of this timer
   * @param period The new period between timer callbacks
   * @param reset Whether to reset the timer. If true, timer ignores elapsed time and next callback occurs at now()+period
   */
  void setPeriod(const WallDuration& period, bool reset = true);

  /**
   * @brief Check if the timer has been started
   * @return True if the timer is running, false otherwise
   */
  bool hasStarted() const;

  /**
   * @brief Check if the timer is valid (has a callback)
   * @return True if the timer is valid, false otherwise
   */
  bool isValid() const;

  /**
   * @brief Check if the timer has any pending events to call
   * @return True if there are pending events, false otherwise
   */
  bool hasPending() const;

  /**
   * @brief Check if the timer is one-shot
   * @return True if the timer is one-shot, false if it repeats
   */
  bool isOneShot() const;

  /**
   * @brief Set whether the timer is one-shot
   * @param oneshot If true, the timer will only fire once
   */
  void setOneShot(bool oneshot);

  /**
   * @brief Get the timer period
   * @return The period between timer callbacks
   */
  WallDuration getPeriod() const;

  /**
   * @brief Conversion to bool (for checking validity)
   */
  operator void*() const;

  /**
   * @brief Equality operator
   */
  bool operator==(const WallTimer& rhs) const;

  /**
   * @brief Inequality operator
   */
  bool operator!=(const WallTimer& rhs) const;

  /**
   * @brief Less-than operator (for ordering in containers)
   */
  bool operator<(const WallTimer& rhs) const;

  // Non-copyable assignment
  WallTimer& operator=(const WallTimer&) = delete;

  // Movable
  WallTimer(WallTimer&& other) noexcept;
  WallTimer& operator=(WallTimer&& other) noexcept;

private:
  /**
   * @brief The timer thread function
   */
  void timerThread();

  WallDuration period_;              ///< Period between callbacks
  Callback callback_;                 ///< Callback function
  bool oneshot_;                      ///< Whether timer is one-shot
  std::atomic<bool> running_;         ///< Whether timer is running
  std::atomic<bool> should_stop_;     ///< Flag to stop the timer thread
  
  std::thread thread_;                ///< Timer thread
  mutable std::mutex mutex_;          ///< Mutex for thread safety
  std::condition_variable cv_;        ///< Condition variable for timing

  WallTime last_real_;                ///< Last actual callback time
  WallTime last_expected_;            ///< Last expected callback time
};

} // namespace robot

#endif // ROBOT_WALL_TIMER_H