runner.hpp

//
// libsemigroups - C++ library for semigroups and monoids
// Copyright (C) 2019-2025 James D. Mitchell
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <http://www.gnu.org/licenses/>.
//
 
// This file contains two classes Runner and Race for competitively running
// different functions/member functions in different threads, and obtaining the
// winner.
 
#ifndef LIBSEMIGROUPS_RUNNER_HPP_
#define LIBSEMIGROUPS_RUNNER_HPP_
 
#include <algorithm>    // for max
#include <array>        // for array
#include <atomic>       // for atomic
#include <chrono>       // for time_point, nanoseconds
#include <cstddef>      // for size_t
#include <functional>   // for function
#include <memory>       // for unique_ptr
#include <mutex>        // for mutex
#include <string>       // for basic_string, string
#include <string_view>  // for basic_string_view
#include <thread>       // for sleep_for, thread
#include <tuple>        // for apply
#include <utility>      // for move, forward
#include <vector>       // for vector
 
#include "debug.hpp"  // for LIBSEMIGROUPS_ASSERT
 
#include "detail/function-ref.hpp"  // for FunctionRef
#include "detail/report.hpp"        // for report_default
#include "detail/string.hpp"        // for unicode_string_length
 
namespace libsemigroups {


  // Not noexcept because std::chrono::duration_cast isn't
  [[nodiscard]] static inline std::chrono::nanoseconds
  delta(std::chrono::high_resolution_clock::time_point const& t) {
    using std::chrono::duration_cast;
    using std::chrono::high_resolution_clock;
    return duration_cast<std::chrono::nanoseconds>(high_resolution_clock::now()
                                                   - t);
  }

  constexpr std::chrono::nanoseconds FOREVER = std::chrono::nanoseconds::max();

  class Reporter {
   public:
    using time_point = std::chrono::high_resolution_clock::time_point;
    using nanoseconds = std::chrono::nanoseconds;
 
   private:
    std::string _divider;
    std::string _prefix;
    nanoseconds _report_time_interval;
 
    mutable std::atomic<time_point> _last_report;
    mutable time_point              _start_time;
 
   public:
    // not noexcept because std::string constructor isn't
    Reporter();

    Reporter& init();

    Reporter(Reporter const& that);

    Reporter(Reporter&& that);

    Reporter& operator=(Reporter const& that);

    Reporter& operator=(Reporter&& that);
 
    ~Reporter() = default;

    // not noexcept because operator- for time_points can throw.
    // TODO(later) remove? Used by Action
    [[nodiscard]] bool report() const;

    [[deprecated]] Reporter& report_every(nanoseconds val) noexcept {
      _last_report          = std::chrono::high_resolution_clock::now();
      _report_time_interval = val;
      return *this;
    }

    template <typename Time>
    [[deprecated]] Reporter& report_every(Time t) noexcept {
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
      return report_every(nanoseconds(t));
#pragma GCC diagnostic pop
    }

    [[deprecated]] [[nodiscard]] nanoseconds report_every() const noexcept {
      return _report_time_interval;
    }

    [[nodiscard]] time_point start_time() const noexcept {
      return _start_time;
    }

    // Not sure if this is noexcept or not,
    // std::chrono::high_resolution_clock::now is noexcept, but JDM couldn't
    // find the noexcept spec of the copy assignment operator of a time_point.
    Reporter const& reset_start_time() const {
      _last_report = std::chrono::high_resolution_clock::now();
      _start_time  = _last_report;
      return *this;
    }

    [[nodiscard]] time_point last_report() const noexcept {
      return _last_report;
    }

    // Not sure if this is noexcept or not,
    // std::chrono::high_resolution_clock::now is noexcept, but JDM couldn't
    // find the noexcept spec of the copy assignment operator of a time_point.
    Reporter const& reset_last_report() const {
      _last_report = std::chrono::high_resolution_clock::now();
      return *this;
    }

    // Not noexcept because std::string::operator= isn't
    Reporter& report_prefix(std::string const& val) {
      _prefix = val;
      return *this;
    }

    [[nodiscard]] std::string const& report_prefix() const noexcept {
      return _prefix;
    }

    // Not noexcept because std::string::operator= isn't
    // TODO(1) deprecate
    Reporter& report_divider(std::string const& val) {
      _divider = val;
      return *this;
    }

    // TODO(1) deprecate
    [[nodiscard]] std::string const& report_divider() const noexcept {
      return _divider;
    }

    void emit_divider() {
      if (!_divider.empty()) {
        report_no_prefix(_divider, "");
      }
    }
  };

  class Runner : public Reporter {
   public:
    enum class state {
      never_run = 0,
      running_to_finish = 1,
      running_for = 2,
      running_until = 3,
      timed_out = 4,
      stopped_by_predicate = 6,
      not_running = 7,
      dead = 8
    };
 
   private:
    // Runner - data - private
 
    std::chrono::nanoseconds        _run_for;
    mutable std::atomic<state>      _state;
    detail::FunctionRef<bool(void)> _stopper;
 
   public:
    // Runner - constructors + destructor - public

    // not noexcept because Reporter() isn't
    Runner();

    Runner& init();

    Runner(Runner const& other);

    Runner(Runner&& other);

    Runner& operator=(Runner const& other);

    Runner& operator=(Runner&& other);
 
    virtual ~Runner();

    // Runner - non-virtual member functions - public
 
    // The following mem fns don't return a reference to Runner to avoid the
    // unexpected behaviour of e.g. Sims1.run_for() returning a reference to not
    // a Sims1.

    // At the end of this either finished, or dead.
    void run();

    // At the end of this either finished, dead, or timed_out.
    void run_for(std::chrono::nanoseconds t);

    template <typename Time>
    void run_for(Time t) {
      run_for(std::chrono::nanoseconds(t));
    }

    // not noexcept because operator-(time_point, time_point) isn't
    [[nodiscard]] inline bool timed_out() const {
      return (running_for() ? delta(start_time()) >= _run_for
                            : current_state() == state::timed_out);
    }

    // At the end of this either finished, dead, or stopped_by_predicate.
    template <typename Func>
    void run_until(Func&& func);

    void run_until(bool (*func)()) {
      run_until(detail::FunctionRef<bool(void)>(func));
    }

    // not noexcept because it calls timed_out which is not noexcept
    void report_why_we_stopped() const;
 
    // TODO(doc)
    std::string string_why_we_stopped() const;

    // Not noexcept because finished_impl isn't
    [[nodiscard]] bool finished() const;

    [[nodiscard]] virtual bool success() const {
      return finished();
    }

    [[nodiscard]] bool started() const noexcept {
      return current_state() != state::never_run;
    }

    [[nodiscard]] bool running() const noexcept {
      return current_state() == state::running_to_finish
             || current_state() == state::running_for
             || current_state() == state::running_until;
    }

    void kill() noexcept {
      set_state(state::dead);
    }

    [[nodiscard]] bool dead() const noexcept {
      return current_state() == state::dead;
    }

    // not noexcept because timed_out isn't
    [[nodiscard]] bool stopped() const {
      return (running() ? (timed_out() || stopped_by_predicate())
                        : current_state() > state::running_until);
    }

    // noexcept should depend on whether _stopper can throw or not
    [[nodiscard]] inline bool stopped_by_predicate() const {
      if (running_until()) {
        LIBSEMIGROUPS_ASSERT(_stopper.valid());
        return _stopper();
      } else {
        return current_state() == state::stopped_by_predicate;
      }
    }

    [[nodiscard]] bool running_for() const noexcept {
      return _state == state::running_for;
    }

    [[nodiscard]] std::chrono::nanoseconds
    running_for_how_long() const noexcept {
      return _run_for;
    }

    [[nodiscard]] bool running_until() const noexcept {
      return _state == state::running_until;
    }

    [[nodiscard]] state current_state() const noexcept {
      return _state;
    }
 
   private:
    virtual void               run_impl()            = 0;
    [[nodiscard]] virtual bool finished_impl() const = 0;
 
    void set_state(state stt) const noexcept {
      // We can set the state back to never_run if run_impl throws, and we are
      // restoring the old state.
      if (!dead()) {
        // It can be that *this* becomes dead after this function has been
        // called.
        _state = stt;
      }
    }
  };  // class Runner
}  // namespace libsemigroups
 
#include "runner.tpp"
#endif  // LIBSEMIGROUPS_RUNNER_HPP_