path: root/mozglue/baseprofiler/public/ProgressLogger.h

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef ProgressLogger_h
#define ProgressLogger_h

#include "mozilla/Assertions.h"
#include "mozilla/ProportionValue.h"
#include "mozilla/RefCounted.h"
#include "mozilla/RefPtr.h"

#include <atomic>

// Uncomment to printf ProcessLogger updates.
// #define DEBUG_PROCESSLOGGER

#ifdef DEBUG_PROCESSLOGGER
#  include "mozilla/BaseProfilerUtils.h"
#  include <cstdio>
#endif  // DEBUG_PROCESSLOGGER

namespace mozilla {

// A `ProgressLogger` is used to update a referenced atomic `ProportionValue`,
// and can recursively create a sub-logger corresponding to a subset of their
// own range, but that sub-logger's updates are done in its local 0%-100% range.
// The typical usage is for multi-level tasks, where each level can estimate its
// own work and the work delegated to a next-level function, without knowing how
// this local work relates to the higher-level total work. See
// `CreateSubLoggerFromTo` for details.
// Note that this implementation is single-threaded, it does not support logging
// progress from multiple threads at the same time.
class ProgressLogger {
 public:
  // An RefPtr'd object of this class is used as the target of all
  // ProgressLogger updates, and it may be shared to make these updates visible
  // from other code in any thread.
  class SharedProgress : public external::AtomicRefCounted<SharedProgress> {
   public:
    MOZ_DECLARE_REFCOUNTED_TYPENAME(SharedProgress)

    SharedProgress() = default;

    SharedProgress(const SharedProgress&) = delete;
    SharedProgress& operator=(const SharedProgress&) = delete;

    // This constant is used to indicate that an update may change the progress
    // value, but should not modify the previously-recorded location.
    static constexpr const char* NO_LOCATION_UPDATE = nullptr;

    // Set the current progress and location, but the previous location is not
    // overwritten if the new one is null or empty.
    // The location and then the progress are atomically "released", so that all
    // preceding writes on this thread will be visible to other threads reading
    // these values; most importantly when reaching 100% progress, the reader
    // can be confident that the location is final and the operation being
    // watched has completed.
    void SetProgress(
        ProportionValue aProgress,
        const char* aLocationOrNullEmptyToIgnore = NO_LOCATION_UPDATE) {
      if (aLocationOrNullEmptyToIgnore &&
          *aLocationOrNullEmptyToIgnore != '\0') {
        mLastLocation.store(aLocationOrNullEmptyToIgnore,
                            std::memory_order_release);
      }
      mProgress.store(aProgress, std::memory_order_release);
    }

    // Read the current progress value. Atomically "acquired", so that writes
    // from the thread that stored this value are all visible to the reader
    // here; most importantly when reaching 100%, we can be confident that the
    // location is final and the operation being watched has completed.
    [[nodiscard]] ProportionValue Progress() const {
      return mProgress.load(std::memory_order_acquire);
    }

    // Read the current progress value. Atomically "acquired".
    [[nodiscard]] const char* LastLocation() const {
      return mLastLocation.load(std::memory_order_acquire);
    }

   private:
    friend mozilla::detail::RefCounted<SharedProgress,
                                       mozilla::detail::AtomicRefCount>;
    ~SharedProgress() = default;

    // Progress and last-known location.
    // Beware that these two values are not strongly tied: Reading one then the
    // other may give mismatched information; but it should be fine for
    // informational usage.
    // They are stored using atomic acquire-release ordering, to guarantee that
    // when read, all writes preceding these values are visible.
    std::atomic<ProportionValue> mProgress = ProportionValue{0.0};
    std::atomic<const char*> mLastLocation = nullptr;
  };

  static constexpr const char* NO_LOCATION_UPDATE =
      SharedProgress::NO_LOCATION_UPDATE;

  ProgressLogger() = default;

  // Construct a top-level logger, starting at 0% and expected to end at 100%.
  explicit ProgressLogger(
      RefPtr<SharedProgress> aGlobalProgressOrNull,
      const char* aLocationOrNullEmptyToIgnoreAtStart = NO_LOCATION_UPDATE,
      const char* aLocationOrNullEmptyToIgnoreAtEnd = NO_LOCATION_UPDATE)
      : ProgressLogger{std::move(aGlobalProgressOrNull),
                       /* Start */ ProportionValue{0.0},
                       /* Multiplier */ ProportionValue{1.0},
                       aLocationOrNullEmptyToIgnoreAtStart,
                       aLocationOrNullEmptyToIgnoreAtEnd} {}

  // Don't make copies, it would be confusing!
  // TODO: Copies could one day be allowed to track multi-threaded work, but it
  // is outside the scope of this implementation; Please update if needed.
  ProgressLogger(const ProgressLogger&) = delete;
  ProgressLogger& operator&(const ProgressLogger&) = delete;

  // Move-construct is allowed, to return from CreateSubLoggerFromTo, and
  // forward straight into a function. Note that moved-from ProgressLoggers must
  // not be used anymore! Use `CreateSubLoggerFromTo` to pass a sub-logger to
  // functions.
  ProgressLogger(ProgressLogger&& aOther)
      : mGlobalProgressOrNull(std::move(aOther.mGlobalProgressOrNull)),
        mLocalStartInGlobalSpace(aOther.mLocalStartInGlobalSpace),
        mLocalToGlobalMultiplier(aOther.mLocalToGlobalMultiplier),
        mLocationAtDestruction(aOther.mLocationAtDestruction) {
    aOther.MarkMovedFrom();
#ifdef DEBUG_PROCESSLOGGER
    if (mGlobalProgressOrNull) {
      printf("[%d] Moved (staying globally at %.2f in [%.2f, %.2f])\n",
             int(baseprofiler::profiler_current_process_id().ToNumber()),
             GetGlobalProgress().ToDouble() * 100.0,
             mLocalStartInGlobalSpace.ToDouble() * 100.0,
             (mLocalStartInGlobalSpace + mLocalToGlobalMultiplier).ToDouble() *
                 100.0);
    }
#endif  // DEBUG_PROCESSLOGGER
  }

  // Move-assign. This may be useful when starting with a default (empty) logger
  // and later assigning it a progress value to start updating.
  ProgressLogger& operator=(ProgressLogger&& aOther) {
    mGlobalProgressOrNull = std::move(aOther.mGlobalProgressOrNull);
    mLocalStartInGlobalSpace = aOther.mLocalStartInGlobalSpace;
    mLocalToGlobalMultiplier = aOther.mLocalToGlobalMultiplier;
    mLocationAtDestruction = aOther.mLocationAtDestruction;
    aOther.MarkMovedFrom();
#ifdef DEBUG_PROCESSLOGGER
    if (mGlobalProgressOrNull) {
      printf("[%d] Re-assigned (globally at %.2f in [%.2f, %.2f])\n",
             int(baseprofiler::profiler_current_process_id().ToNumber()),
             GetGlobalProgress().ToDouble() * 100.0,
             mLocalStartInGlobalSpace.ToDouble() * 100.0,
             (mLocalStartInGlobalSpace + mLocalToGlobalMultiplier).ToDouble() *
                 100.0);
    }
#endif  // DEBUG_PROCESSLOGGER
    return *this;
  }

  // Destruction sets the local update value to 100% unless empty or moved-from.
  ~ProgressLogger() {
    if (!IsMovedFrom()) {
#ifdef DEBUG_PROCESSLOGGER
      if (mGlobalProgressOrNull) {
        printf("[%d] Destruction:\n",
               int(baseprofiler::profiler_current_process_id().ToNumber()));
      }
#endif  // DEBUG_PROCESSLOGGER
      SetLocalProgress(ProportionValue{1.0}, mLocationAtDestruction);
    }
  }

  // Retrieve the current progress in the global space. May be invalid.
  [[nodiscard]] ProportionValue GetGlobalProgress() const {
    return mGlobalProgressOrNull ? mGlobalProgressOrNull->Progress()
                                 : ProportionValue::MakeInvalid();
  }

  // Retrieve the last known global location. May be null.
  [[nodiscard]] const char* GetLastGlobalLocation() const {
    return mGlobalProgressOrNull ? mGlobalProgressOrNull->LastLocation()
                                 : nullptr;
  }

  // Set the current progress in the local space.
  void SetLocalProgress(ProportionValue aLocalProgress,
                        const char* aLocationOrNullEmptyToIgnore) {
    MOZ_ASSERT(!IsMovedFrom());
    if (mGlobalProgressOrNull && !mLocalToGlobalMultiplier.IsExactlyZero()) {
      mGlobalProgressOrNull->SetProgress(LocalToGlobal(aLocalProgress),
                                         aLocationOrNullEmptyToIgnore);
#ifdef DEBUG_PROCESSLOGGER
      printf("[%d] - local %.0f%% ~ global %.2f%% \"%s\"\n",
             int(baseprofiler::profiler_current_process_id().ToNumber()),
             aLocalProgress.ToDouble() * 100.0,
             LocalToGlobal(aLocalProgress).ToDouble() * 100.0,
             aLocationOrNullEmptyToIgnore ? aLocationOrNullEmptyToIgnore
                                          : "<null>");
#endif  // DEBUG_PROCESSLOGGER
    }
  }

  // Create a sub-logger that will record progress in the given local range.
  // E.g.: `f(pl.CreateSubLoggerFromTo(0.2, "f...", 0.4, "f done"));` expects
  // that `f` will produce work in the local range 0.2 (when starting) to 0.4
  // (when returning); `f` itself will update this provided logger from 0.0
  // to 1.0 (local to that `f` function), which will effectively be converted to
  // 0.2-0.4 (local to the calling function).
  // This can cascade multiple levels, each deeper level affecting a smaller and
  // smaller range in the global output.
  [[nodiscard]] ProgressLogger CreateSubLoggerFromTo(
      ProportionValue aSubStartInLocalSpace,
      const char* aLocationOrNullEmptyToIgnoreAtStart,
      ProportionValue aSubEndInLocalSpace,
      const char* aLocationOrNullEmptyToIgnoreAtEnd = NO_LOCATION_UPDATE) {
    MOZ_ASSERT(!IsMovedFrom());
    if (!mGlobalProgressOrNull) {
      return ProgressLogger{};
    }
    const ProportionValue subStartInGlobalSpace =
        LocalToGlobal(aSubStartInLocalSpace);
    const ProportionValue subEndInGlobalSpace =
        LocalToGlobal(aSubEndInLocalSpace);
    if (subStartInGlobalSpace.IsInvalid() || subEndInGlobalSpace.IsInvalid()) {
      return ProgressLogger{mGlobalProgressOrNull,
                            /* Start */ ProportionValue::MakeInvalid(),
                            /* Multiplier */ ProportionValue{0.0},
                            aLocationOrNullEmptyToIgnoreAtStart,
                            aLocationOrNullEmptyToIgnoreAtEnd};
    }
#ifdef DEBUG_PROCESSLOGGER
    if (mGlobalProgressOrNull) {
      printf("[%d] * Sub: local [%.0f%%, %.0f%%] ~ global [%.2f%%, %.2f%%]\n",
             int(baseprofiler::profiler_current_process_id().ToNumber()),
             aSubStartInLocalSpace.ToDouble() * 100.0,
             aSubEndInLocalSpace.ToDouble() * 100.0,
             subStartInGlobalSpace.ToDouble() * 100.0,
             subEndInGlobalSpace.ToDouble() * 100.0);
    }
#endif  // DEBUG_PROCESSLOGGER
    return ProgressLogger{
        mGlobalProgressOrNull,
        /* Start */ subStartInGlobalSpace,
        /* Multipler */ subEndInGlobalSpace - subStartInGlobalSpace,
        aLocationOrNullEmptyToIgnoreAtStart, aLocationOrNullEmptyToIgnoreAtEnd};
  }

  // Helper with no start location.
  [[nodiscard]] ProgressLogger CreateSubLoggerFromTo(
      ProportionValue aSubStartInLocalSpace,
      ProportionValue aSubEndInLocalSpace,
      const char* aLocationOrNullEmptyToIgnoreAtEnd = NO_LOCATION_UPDATE) {
    return CreateSubLoggerFromTo(aSubStartInLocalSpace, NO_LOCATION_UPDATE,
                                 aSubEndInLocalSpace,
                                 aLocationOrNullEmptyToIgnoreAtEnd);
  }

  // Helper using the current progress as start.
  [[nodiscard]] ProgressLogger CreateSubLoggerTo(
      const char* aLocationOrNullEmptyToIgnoreAtStart,
      ProportionValue aSubEndInLocalSpace,
      const char* aLocationOrNullEmptyToIgnoreAtEnd = NO_LOCATION_UPDATE) {
    MOZ_ASSERT(!IsMovedFrom());
    if (!mGlobalProgressOrNull) {
      return ProgressLogger{};
    }
    const ProportionValue subStartInGlobalSpace = GetGlobalProgress();
    const ProportionValue subEndInGlobalSpace =
        LocalToGlobal(aSubEndInLocalSpace);
    if (subStartInGlobalSpace.IsInvalid() || subEndInGlobalSpace.IsInvalid()) {
      return ProgressLogger{mGlobalProgressOrNull,
                            /* Start */ ProportionValue::MakeInvalid(),
                            /* Multiplier */ ProportionValue{0.0},
                            aLocationOrNullEmptyToIgnoreAtStart,
                            aLocationOrNullEmptyToIgnoreAtEnd};
    }
#ifdef DEBUG_PROCESSLOGGER
    if (mGlobalProgressOrNull) {
      printf("[%d] * Sub: local [(here), %.0f%%] ~ global [%.2f%%, %.2f%%]\n",
             int(baseprofiler::profiler_current_process_id().ToNumber()),
             aSubEndInLocalSpace.ToDouble() * 100.0,
             subStartInGlobalSpace.ToDouble() * 100.0,
             subEndInGlobalSpace.ToDouble() * 100.0);
    }
#endif  // DEBUG_PROCESSLOGGER
    return ProgressLogger{
        mGlobalProgressOrNull,
        /* Start */ subStartInGlobalSpace,
        /* Multiplier */ subEndInGlobalSpace - subStartInGlobalSpace,
        aLocationOrNullEmptyToIgnoreAtStart, aLocationOrNullEmptyToIgnoreAtEnd};
  }

  // Helper using the current progress as start, no start location.
  [[nodiscard]] ProgressLogger CreateSubLoggerTo(
      ProportionValue aSubEndInLocalSpace,
      const char* aLocationOrNullEmptyToIgnoreAtEnd = NO_LOCATION_UPDATE) {
    return CreateSubLoggerTo(NO_LOCATION_UPDATE, aSubEndInLocalSpace,
                             aLocationOrNullEmptyToIgnoreAtEnd);
  }

  class IndexAndProgressLoggerRange;

  [[nodiscard]] inline IndexAndProgressLoggerRange CreateLoopSubLoggersFromTo(
      ProportionValue aLoopStartInLocalSpace,
      ProportionValue aLoopEndInLocalSpace, uint32_t aLoopCount,
      const char* aLocationOrNullEmptyToIgnoreAtEdges =
          ProgressLogger::NO_LOCATION_UPDATE);
  [[nodiscard]] inline IndexAndProgressLoggerRange CreateLoopSubLoggersTo(
      ProportionValue aLoopEndInLocalSpace, uint32_t aLoopCount,
      const char* aLocationOrNullEmptyToIgnoreAtEdges =
          ProgressLogger::NO_LOCATION_UPDATE);

 private:
  // All constructions start at the local 0%.
  ProgressLogger(RefPtr<SharedProgress> aGlobalProgressOrNull,
                 ProportionValue aLocalStartInGlobalSpace,
                 ProportionValue aLocalToGlobalMultiplier,
                 const char* aLocationOrNullEmptyToIgnoreAtConstruction,
                 const char* aLocationOrNullEmptyToIgnoreAtDestruction)
      : mGlobalProgressOrNull(std::move(aGlobalProgressOrNull)),
        mLocalStartInGlobalSpace(aLocalStartInGlobalSpace),
        mLocalToGlobalMultiplier(aLocalToGlobalMultiplier),
        mLocationAtDestruction(aLocationOrNullEmptyToIgnoreAtDestruction) {
    MOZ_ASSERT(!IsMovedFrom(), "Don't construct a moved-from object!");
    SetLocalProgress(ProportionValue{0.0},
                     aLocationOrNullEmptyToIgnoreAtConstruction);
  }

  void MarkMovedFrom() {
    mLocalToGlobalMultiplier = ProportionValue::MakeInvalid();
  }
  [[nodiscard]] bool IsMovedFrom() const {
    return mLocalToGlobalMultiplier.IsInvalid();
  }

  [[nodiscard]] ProportionValue LocalToGlobal(
      ProportionValue aLocalProgress) const {
    return aLocalProgress * mLocalToGlobalMultiplier + mLocalStartInGlobalSpace;
  }

  // Global progress value to update from local changes.
  RefPtr<SharedProgress> mGlobalProgressOrNull;

  // How much to multiply and add to a local [0, 100%] value, to get the
  // corresponding value in the global space.
  // If mLocalToGlobalMultiplier is invalid, this ProgressLogger is moved-from,
  // functions should not be used, and destructor won't update progress.
  ProportionValue mLocalStartInGlobalSpace;
  ProportionValue mLocalToGlobalMultiplier;

  const char* mLocationAtDestruction = nullptr;
};

// Helper class for range-for loop, e.g., with `aProgressLogger`:
//   for (auto [index, loopProgressLogger] :
//        IndexAndProgressLoggerRange{aProgressLogger, 30_pc, 50_pc, 10,
//                                    "looping..."}) {
//     // This will loop 10 times.
//     // `index` is the loop index, from 0 to 9.
//     // The overall loop will start at 30% and end at 50% of aProgressLogger.
//     // `loopProgressLogger` is the progress logger for each iteration,
//     // covering 1/10th of the range, therefore: [30%,32%], then [32%,34%],
//     // etc. until [48%,50%].
//     // Progress is automatically updated before/after each loop.
//   }
// Note that this implementation is single-threaded, it does not support logging
// progress from parallel loops.
class ProgressLogger::IndexAndProgressLoggerRange {
 public:
  struct IndexAndProgressLogger {
    uint32_t index;
    ProgressLogger progressLogger;
  };

  class IndexAndProgressLoggerEndIterator {
   public:
    explicit IndexAndProgressLoggerEndIterator(uint32_t aIndex)
        : mIndex(aIndex) {}

    [[nodiscard]] uint32_t Index() const { return mIndex; }

   private:
    uint32_t mIndex;
  };

  class IndexAndProgressLoggerIterator {
   public:
    IndexAndProgressLoggerIterator(
        RefPtr<ProgressLogger::SharedProgress> aGlobalProgressOrNull,
        ProportionValue aLoopStartInGlobalSpace,
        ProportionValue aLoopIncrementInGlobalSpace,
        const char* aLocationOrNullEmptyToIgnoreAtEdges)
        : mGlobalProgressOrNull(aGlobalProgressOrNull),
          mLoopStartInGlobalSpace(aLoopStartInGlobalSpace),
          mLoopIncrementInGlobalSpace(aLoopIncrementInGlobalSpace),
          mIndex(0u),
          mLocationOrNullEmptyToIgnoreAtEdges(
              aLocationOrNullEmptyToIgnoreAtEdges) {
      if (mGlobalProgressOrNull) {
        mGlobalProgressOrNull->SetProgress(mLoopStartInGlobalSpace,
                                           mLocationOrNullEmptyToIgnoreAtEdges);
      }
    }

    [[nodiscard]] IndexAndProgressLogger operator*() {
      return IndexAndProgressLogger{
          mIndex,
          mGlobalProgressOrNull
              ? ProgressLogger{mGlobalProgressOrNull, mLoopStartInGlobalSpace,
                               mLoopIncrementInGlobalSpace,
                               ProgressLogger::NO_LOCATION_UPDATE,
                               ProgressLogger::NO_LOCATION_UPDATE}
              : ProgressLogger{}};
    }

    [[nodiscard]] bool operator!=(
        const IndexAndProgressLoggerEndIterator& aEnd) const {
      return mIndex != aEnd.Index();
    }

    IndexAndProgressLoggerIterator& operator++() {
      ++mIndex;
      mLoopStartInGlobalSpace =
          mLoopStartInGlobalSpace + mLoopIncrementInGlobalSpace;
      if (mGlobalProgressOrNull) {
        mGlobalProgressOrNull->SetProgress(mLoopStartInGlobalSpace,
                                           mLocationOrNullEmptyToIgnoreAtEdges);
      }
      return *this;
    }

   private:
    RefPtr<ProgressLogger::SharedProgress> mGlobalProgressOrNull;
    ProportionValue mLoopStartInGlobalSpace;
    ProportionValue mLoopIncrementInGlobalSpace;
    uint32_t mIndex;
    const char* mLocationOrNullEmptyToIgnoreAtEdges;
  };

  [[nodiscard]] IndexAndProgressLoggerIterator begin() {
    return IndexAndProgressLoggerIterator{
        mGlobalProgressOrNull, mLoopStartInGlobalSpace,
        mLoopIncrementInGlobalSpace, mLocationOrNullEmptyToIgnoreAtEdges};
  }

  [[nodiscard]] IndexAndProgressLoggerEndIterator end() {
    return IndexAndProgressLoggerEndIterator{mLoopCount};
  }

 private:
  friend class ProgressLogger;
  IndexAndProgressLoggerRange(ProgressLogger& aProgressLogger,
                              ProportionValue aLoopStartInGlobalSpace,
                              ProportionValue aLoopEndInGlobalSpace,
                              uint32_t aLoopCount,
                              const char* aLocationOrNullEmptyToIgnoreAtEdges =
                                  ProgressLogger::NO_LOCATION_UPDATE)
      : mGlobalProgressOrNull(aProgressLogger.mGlobalProgressOrNull),
        mLoopStartInGlobalSpace(aLoopStartInGlobalSpace),
        mLoopIncrementInGlobalSpace(
            (aLoopEndInGlobalSpace - aLoopStartInGlobalSpace) / aLoopCount),
        mLoopCount(aLoopCount),
        mLocationOrNullEmptyToIgnoreAtEdges(
            aLocationOrNullEmptyToIgnoreAtEdges) {}

  RefPtr<ProgressLogger::SharedProgress> mGlobalProgressOrNull;
  ProportionValue mLoopStartInGlobalSpace;
  ProportionValue mLoopIncrementInGlobalSpace;
  uint32_t mLoopCount;
  const char* mLocationOrNullEmptyToIgnoreAtEdges;
};

[[nodiscard]] ProgressLogger::IndexAndProgressLoggerRange
ProgressLogger::CreateLoopSubLoggersFromTo(
    ProportionValue aLoopStartInLocalSpace,
    ProportionValue aLoopEndInLocalSpace, uint32_t aLoopCount,
    const char* aLocationOrNullEmptyToIgnoreAtEdges) {
  return IndexAndProgressLoggerRange{
      *this, LocalToGlobal(aLoopStartInLocalSpace),
      LocalToGlobal(aLoopEndInLocalSpace), aLoopCount,
      aLocationOrNullEmptyToIgnoreAtEdges};
}

[[nodiscard]] ProgressLogger::IndexAndProgressLoggerRange
ProgressLogger::CreateLoopSubLoggersTo(
    ProportionValue aLoopEndInLocalSpace, uint32_t aLoopCount,
    const char* aLocationOrNullEmptyToIgnoreAtEdges) {
  return IndexAndProgressLoggerRange{
      *this, GetGlobalProgress(), LocalToGlobal(aLoopEndInLocalSpace),
      aLoopCount, aLocationOrNullEmptyToIgnoreAtEdges};
}

}  // namespace mozilla

#endif  // ProgressLogger_h