time_limit.h

Go to the documentation of this file.

// Copyright 2010-2025 Google LLC
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
 
#ifndef OR_TOOLS_UTIL_TIME_LIMIT_H_
#define OR_TOOLS_UTIL_TIME_LIMIT_H_
 
#include <algorithm>
#include <atomic>
#include <cstdint>
#include <limits>
#include <memory>
#include <string>
#include <vector>
 
#include "absl/base/thread_annotations.h"
#include "absl/container/flat_hash_map.h"
#include "absl/flags/declare.h"
#include "absl/flags/flag.h"
#include "absl/log/check.h"
#include "absl/synchronization/mutex.h"
#include "absl/time/clock.h"
#include "absl/time/time.h"
#include "ortools/base/base_export.h"
#include "ortools/base/timer.h"
#include "ortools/base/types.h"
#include "ortools/util/running_stat.h"

OR_DLL ABSL_DECLARE_FLAG(bool, time_limit_use_usertime);
 
namespace operations_research {

// TODO(user): The expression "deterministic time" should be replaced with
//                 "number of operations" to avoid confusion with "real" time.
class OR_DLL TimeLimit {
 public:
  static const double kSafetyBufferSeconds;  // See the .cc for the value.
  static const int kHistorySize;

  explicit TimeLimit(
      double limit_in_seconds,
      double deterministic_limit = std::numeric_limits<double>::infinity());
 
  TimeLimit() : TimeLimit(std::numeric_limits<double>::infinity()) {}
  TimeLimit(const TimeLimit&) = delete;
  TimeLimit& operator=(const TimeLimit&) = delete;

  static std::unique_ptr<TimeLimit> Infinite() {
    return std::make_unique<TimeLimit>(std::numeric_limits<double>::infinity(),
                                       std::numeric_limits<double>::infinity());
  }

  static std::unique_ptr<TimeLimit> FromDeterministicTime(
      double deterministic_limit) {
    return std::make_unique<TimeLimit>(std::numeric_limits<double>::infinity(),
                                       deterministic_limit);
  }

  template <typename Parameters>
  static std::unique_ptr<TimeLimit> FromParameters(
      const Parameters& parameters) {
    return std::make_unique<TimeLimit>(parameters.max_time_in_seconds(),
                                       parameters.max_deterministic_time());
  }

  bool LimitReached();

  double GetTimeLeft() const;

  double GetDeterministicTimeLeft() const {
    return std::max(0.0, deterministic_limit_ - elapsed_deterministic_time_);
  }

  inline void AdvanceDeterministicTime(double deterministic_duration) {
    DCHECK_LE(0.0, deterministic_duration);
    elapsed_deterministic_time_ += deterministic_duration;
  }

  inline void AdvanceDeterministicTime(double deterministic_duration,
                                       const char* counter_name) {
    AdvanceDeterministicTime(deterministic_duration);
#ifndef NDEBUG
    deterministic_counters_[counter_name] += deterministic_duration;
#endif
  }

  double GetElapsedTime() const {
    return 1e-9 * (absl::GetCurrentTimeNanos() - start_ns_);
  }

  double GetElapsedDeterministicTime() const {
    return elapsed_deterministic_time_;
  }

  void RegisterExternalBooleanAsLimit(
      std::atomic<bool>* external_boolean_as_limit) {
    external_boolean_as_limit_ = external_boolean_as_limit;
  }

  void RegisterSecondaryExternalBooleanAsLimit(
      std::atomic<bool>* external_boolean_as_limit) {
    secondary_external_boolean_as_limit_ = external_boolean_as_limit;
  }

  std::atomic<bool>* ExternalBooleanAsLimit() const {
    return external_boolean_as_limit_;
  }

  template <typename Parameters>
  void ResetLimitFromParameters(const Parameters& parameters);

  void MergeWithGlobalTimeLimit(const TimeLimit* other);

  void ChangeDeterministicLimit(double new_limit) {
    deterministic_limit_ = new_limit;
  }

  double GetDeterministicLimit() const { return deterministic_limit_; }

  void ResetHistory() { running_max_.Reset(); }

  std::string DebugString() const;
 
 private:
  void ResetTimers(double limit_in_seconds, double deterministic_limit);
 
  mutable int64_t start_ns_;  // Not const! this is initialized after
                              // instruction counter initialization.
  int64_t last_ns_;
  int64_t limit_ns_;  // Not const! See the code of LimitReached().
  const int64_t safety_buffer_ns_;
  RunningMax<int64_t> running_max_;
 
  // Only used when FLAGS_time_limit_use_usertime is true.
  UserTimer user_timer_;
  double limit_in_seconds_;
 
  double deterministic_limit_;
  double elapsed_deterministic_time_;
 
  std::atomic<bool>* external_boolean_as_limit_ = nullptr;
  std::atomic<bool>* secondary_external_boolean_as_limit_ = nullptr;
 
#ifndef NDEBUG
  // Contains the values of the deterministic time counters.
  absl::flat_hash_map<std::string, double> deterministic_counters_;
#endif
 
  friend class NestedTimeLimit;
  friend class ParallelTimeLimit;
};
 
// Wrapper around TimeLimit to make it thread safe and add Stop() support.
class SharedTimeLimit {
 public:
  explicit SharedTimeLimit(TimeLimit* time_limit)
      : time_limit_(time_limit), stopped_boolean_(false) {
    // We use the one already registered if present or ours otherwise.
    stopped_ = time_limit->ExternalBooleanAsLimit();
    if (stopped_ == nullptr) {
      stopped_ = &stopped_boolean_;
      time_limit->RegisterExternalBooleanAsLimit(stopped_);
    }
  }
 
  ~SharedTimeLimit() {
    if (stopped_ == &stopped_boolean_) {
      time_limit_->RegisterExternalBooleanAsLimit(nullptr);
    }
  }
 
  bool LimitReached() const {
    // Note, time_limit_->LimitReached() is not const, and changes internal
    // state of time_limit_, hence we need a writer's lock.
    absl::MutexLock lock(&mutex_);
    return time_limit_->LimitReached();
  }
 
  void Stop() {
    absl::MutexLock lock(&mutex_);
    *stopped_ = true;
  }
 
  void UpdateLocalLimit(TimeLimit* local_limit) {
    absl::MutexLock lock(&mutex_);
    local_limit->MergeWithGlobalTimeLimit(time_limit_);
  }
 
  void AdvanceDeterministicTime(double deterministic_duration) {
    absl::MutexLock lock(&mutex_);
    time_limit_->AdvanceDeterministicTime(deterministic_duration);
  }
 
  double GetTimeLeft() const {
    absl::ReaderMutexLock lock(&mutex_);
    return time_limit_->GetTimeLeft();
  }
 
  double GetElapsedDeterministicTime() const {
    absl::ReaderMutexLock lock(&mutex_);
    return time_limit_->GetElapsedDeterministicTime();
  }
 
  std::atomic<bool>* ExternalBooleanAsLimit() const {
    absl::ReaderMutexLock lock(&mutex_);
    // We can simply return the "external bool" and remain thread-safe because
    // it's wrapped in std::atomic.
    return time_limit_->ExternalBooleanAsLimit();
  }
 
 private:
  mutable absl::Mutex mutex_;
  TimeLimit* time_limit_ ABSL_GUARDED_BY(mutex_);
  std::atomic<bool> stopped_boolean_ ABSL_GUARDED_BY(mutex_);
  std::atomic<bool>* stopped_ ABSL_GUARDED_BY(mutex_);
};

class NestedTimeLimit {
 public:
  NestedTimeLimit(TimeLimit* base_time_limit, double limit_in_seconds,
                  double deterministic_limit);
 
  // This type is neither copyable nor movable.
  NestedTimeLimit(const NestedTimeLimit&) = delete;
  NestedTimeLimit& operator=(const NestedTimeLimit&) = delete;

  ~NestedTimeLimit();

  template <typename Parameters>
  static std::unique_ptr<NestedTimeLimit> FromBaseTimeLimitAndParameters(
      TimeLimit* time_limit, const Parameters& parameters) {
    return std::make_unique<NestedTimeLimit>(
        time_limit, parameters.max_time_in_seconds(),
        parameters.max_deterministic_time());
  }

  TimeLimit* GetTimeLimit() { return &time_limit_; }
 
 private:
  TimeLimit* const base_time_limit_;
  TimeLimit time_limit_;
};
 
class TimeLimitCheckEveryNCalls {
 public:
  TimeLimitCheckEveryNCalls(int N, TimeLimit* time_limit)
      : time_limit_(time_limit), frequency_(N) {}
 
  bool LimitReached() {
    if (count_++ == frequency_) {
      if (time_limit_->LimitReached()) {
        stopped_ = true;
        return true;
      }
      count_ = 0;
    }
    return stopped_;
  }
 
 private:
  TimeLimit* time_limit_;
  bool stopped_ = false;
  int count_ = 0;
  const int frequency_;
};
 
// ################## Implementations below #####################
 
inline void TimeLimit::ResetTimers(double limit_in_seconds,
                                   double deterministic_limit) {
  elapsed_deterministic_time_ = 0.0;
  deterministic_limit_ = deterministic_limit;
 
  if (absl::GetFlag(FLAGS_time_limit_use_usertime)) {
    user_timer_.Start();
    limit_in_seconds_ = limit_in_seconds;
  }
  start_ns_ = absl::GetCurrentTimeNanos();
  last_ns_ = start_ns_;
  // Note that duration arithmetic is properly saturated.
  limit_ns_ = (absl::Seconds(limit_in_seconds) + absl::Nanoseconds(start_ns_)) /
              absl::Nanoseconds(1);
}
 
template <typename Parameters>
inline void TimeLimit::ResetLimitFromParameters(const Parameters& parameters) {
  ResetTimers(parameters.max_time_in_seconds(),
              parameters.max_deterministic_time());
}
 
inline void TimeLimit::MergeWithGlobalTimeLimit(const TimeLimit* other) {
  if (other == nullptr) return;
  ResetTimers(
      std::min(GetTimeLeft(), other->GetTimeLeft()),
      std::min(GetDeterministicTimeLeft(), other->GetDeterministicTimeLeft()));
  if (other->ExternalBooleanAsLimit() != nullptr) {
    RegisterExternalBooleanAsLimit(other->ExternalBooleanAsLimit());
  }
}
 
inline bool TimeLimit::LimitReached() {
  if (external_boolean_as_limit_ != nullptr &&
      external_boolean_as_limit_->load()) {
    return true;
  }
  if (secondary_external_boolean_as_limit_ != nullptr &&
      secondary_external_boolean_as_limit_->load()) {
    return true;
  }
 
  if (GetDeterministicTimeLeft() <= 0.0) {
    return true;
  }
 
  const int64_t current_ns = absl::GetCurrentTimeNanos();
  running_max_.Add(std::max(safety_buffer_ns_, current_ns - last_ns_));
  last_ns_ = current_ns;
  if (current_ns + running_max_.GetCurrentMax() >= limit_ns_) {
    if (absl::GetFlag(FLAGS_time_limit_use_usertime)) {
      // To avoid making many system calls, we only check the user time when
      // the "absolute" time limit has been reached. Note that the user time
      // should advance more slowly, so this is correct.
      const double time_left_s = limit_in_seconds_ - user_timer_.Get();
      if (time_left_s > kSafetyBufferSeconds) {
        limit_ns_ = static_cast<int64_t>(time_left_s * 1e9) + last_ns_;
        return false;
      }
    }
 
    // To ensure that future calls to LimitReached() will return true.
    limit_ns_ = 0;
    return true;
  }
  return false;
}
 
inline double TimeLimit::GetTimeLeft() const {
  if (limit_ns_ == kint64max) return std::numeric_limits<double>::infinity();
  const int64_t delta_ns = limit_ns_ - absl::GetCurrentTimeNanos();
  if (delta_ns < 0) return 0.0;
  if (absl::GetFlag(FLAGS_time_limit_use_usertime)) {
    return std::max(limit_in_seconds_ - user_timer_.Get(), 0.0);
  } else {
    return delta_ns * 1e-9;
  }
}
 
}  // namespace operations_research
 
#endif  // OR_TOOLS_UTIL_TIME_LIMIT_H_