Add code for reporting progress to gbbs/helpers

Author: Laxman Dhulipala

gbbs/helpers/BUILD

@@ -1,5 +1,7 @@
 licenses(["notice"])
 
+load("//internal_tools:build_defs.bzl", "gbbs_cc_test")
+
 package(
     default_visibility = ["//visibility:public"],
 )
@@ -59,6 +61,41 @@ cc_library(
     hdrs = ["parse_command_line.h"],
 )
 
+cc_library(
+    name = "progress_reporting",
+    srcs = ["progress_reporting.cc"],
+    hdrs = ["progress_reporting.h"],
+    deps = [
+        "@abseil-cpp//absl/functional:any_invocable",
+        "@abseil-cpp//absl/log:absl_check",
+        "@abseil-cpp//absl/status",
+        "@abseil-cpp//absl/strings",
+    ],
+)
+
+gbbs_cc_test(
+    name = "progress_reporting_test",
+    srcs = ["progress_reporting_test.cc"],
+    deps = [
+        ":progress_reporting",
+        ":progress_reporting_mock",
+        ":status_macros",
+        "@abseil-cpp//absl/status",
+        "@googletest//:gtest_main",
+    ],
+)
+
+cc_library(
+    name = "progress_reporting_mock",
+    testonly = True,
+    hdrs = ["progress_reporting_mock.h"],
+    deps = [
+        ":progress_reporting",
+        "@abseil-cpp//absl/base:core_headers",
+    ],
+)
+
+
 cc_library(
     name = "resizable_table",
     hdrs = ["resizable_table.h"],
@@ -94,6 +131,18 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "status_macros",
+    srcs = ["status_macros.cc"],
+    hdrs = ["status_macros.h"],
+    deps = [
+        "@googletest//:gtest",
+        "@abseil-cpp//absl/log:absl_log",
+        "@abseil-cpp//absl/status",
+        "@abseil-cpp//absl/status:statusor",
+    ],
+)
+
 cc_library(
     name = "undirected_edge",
     srcs = ["undirected_edge.cc"],

gbbs/helpers/progress_reporting.cc

@@ -0,0 +1,81 @@
+#include "gbbs/helpers/progress_reporting.h"
+
+#include "absl/status/status.h"
+#include "absl/strings/str_cat.h"
+
+namespace gbbs {
+
+absl::Status IterationProgressReporter::PreprocessingComplete() {
+  if (!has_preprocessing_) {
+    return absl::FailedPreconditionError(
+        "'PreprocessingComplete()' called on an instance with "
+        "'has_preprocessing' of false.");
+  }
+  if (num_steps_completed_ != 0) {
+    return absl::FailedPreconditionError(
+        "'PreprocessingComplete()' called more than once.");
+  }
+  ++num_steps_completed_;
+  ReportProgress();
+  return absl::OkStatus();
+}
+
+absl::Status IterationProgressReporter::IterationComplete(int iteration) {
+  if (has_preprocessing_ && num_steps_completed_ == 0) {
+    return absl::FailedPreconditionError(
+        "'PreprocessingComplete()' must be called before any call of "
+        "'IterationComplete()'.");
+  }
+  if (num_iterations_ <= 0) {
+    return absl::InvalidArgumentError(
+        "'num_iterations' must be strictly positive.");
+  }
+  if (iteration < 0 || iteration >= num_iterations_) {
+    return absl::InvalidArgumentError(
+        "'iteration' must be in the half-open interval [0, num_iterations).");
+  }
+
+  const int expected_iteration =
+      num_steps_completed_ - (has_preprocessing_ ? 1 : 0);
+  if (iteration != expected_iteration) {
+    return absl::InvalidArgumentError(
+        absl::StrCat("'iteration' must be monotonically ascending; expected ",
+                     expected_iteration, " but got ", iteration, "."));
+  }
+
+  ++num_steps_completed_;
+  ReportProgress();
+  return absl::OkStatus();
+}
+
+absl::Status IterationProgressReporter::IterationsDoneEarly() {
+  if (has_preprocessing_ && num_steps_completed_ == 0) {
+    return absl::FailedPreconditionError(
+        "'PreprocessingComplete()' must be called before any call of "
+        "'IterationsDoneEarly()'.");
+  }
+  num_steps_completed_ = (num_iterations_ - 1) + (has_preprocessing_ ? 1 : 0);
+  return IterationComplete(num_iterations_ - 1);
+}
+
+absl::Status IterationProgressReporter::PostprocessingComplete() {
+  if (!has_postprocessing_) {
+    return absl::FailedPreconditionError(
+        "'PostprocessingComplete()' called on an instance with "
+        "'has_postprocessing' of false.");
+  }
+  if (num_steps_completed_ <= (has_preprocessing_ ? 1 : 0)) {
+    return absl::FailedPreconditionError(
+        "'PostprocessingComplete()' called before any call of "
+        "IterationComplete()' or 'IterationsDoneEarly()'.");
+  }
+  num_steps_completed_ = total_steps_;
+  ReportProgress();
+  return absl::OkStatus();
+}
+
+void IterationProgressReporter::ReportProgress() {
+  report_progress_(static_cast<float>(num_steps_completed_) / total_steps_);
+}
+
+}  // namespace gbbs

gbbs/helpers/progress_reporting.h

@@ -0,0 +1,107 @@
+#pragma once
+
+// This library contains utilities for reporting the progress of the execution
+// of an algorithm.
+
+#include <utility>
+
+#include "absl/functional/any_invocable.h"
+#include "absl/status/status.h"
+
+namespace gbbs {
+
+// Callable object to be used for reporting the progress of the execution of an
+// algorithm, as a number in the closed interval [0.0, 1.0]. Algorithms must
+// report non-decreasing values in this range; values closer to 1.0 indicate
+// that the algorithm is closer to completion.
+//
+// Note: beyond the non-decreasing requirement, there's no requirement on the
+// concrete meaning of the reported numbers (in particular, the progress numbers
+// reported need not be proportional to time elapsed since the start of the
+// algorithm). There's also no requirement on how many times, or how often, the
+// object is called.
+//
+// Typically, an algorithm will make at least two calls; the first one reporting
+// a value of 0.0 (at the very beginning of the execution of the algorithm), and
+// the final one reporting a value of 1.0 (at the very end of the execution of
+// the algorithm).
+using ReportProgressT = absl::AnyInvocable<void(float progress)>;
+
+// Wrapper for a `ReportProgress` instance that's useful for algorithms with the
+// following structure:
+//
+//   - Preprocessing (optional)
+//   - One or more iterations
+//   - Postprocessing (optional)
+//
+// This class provides a convenient way to report the progress of the algorithm
+// execution. It makes the simplifying assumption that the preprocessing step
+// (if any), postprocessing step (if any), and each iteration all represent
+// equal amounts of progress.
+class IterationProgressReporter {
+ public:
+  // Creates a new `IterationProgressReporter` instance.
+  //
+  // Arguments:
+  // * `report_progress`: the instance to be used for reporting the progress of
+  //   the algorithm execution.
+  // * `num_iterations`: the number of iterations (must be strictly positive).
+  // * `has_preprocessing`: indicates whether the algorithm has a preprocessing
+  //   step.
+  // * `has_postprocessing`: indicates whether the algorithm has a
+  //   postprocessing step.
+  IterationProgressReporter(ReportProgressT report_progress, int num_iterations,
+                            bool has_preprocessing = false,
+                            bool has_postprocessing = false)
+      : report_progress_(std::move(report_progress)),
+        num_iterations_(num_iterations),
+        has_preprocessing_(has_preprocessing),
+        has_postprocessing_(has_postprocessing),
+        total_steps_(num_iterations + (has_preprocessing ? 1 : 0) +
+                     (has_postprocessing ? 1 : 0)) {}
+
+  // Indicate that the preprocessing step is complete. Returns an error status
+  // if `has_preprocessing_` is false or if any call of `IterationComplete()`
+  // has been made.
+  absl::Status PreprocessingComplete();
+
+  // Indicates that the `iteration`-th iteration is complete. The `iteration`
+  // value must be in the half-open interval [0, `num_iterations_`) (i.e.,
+  // iteration indices are 0-based). At least one call of
+  // this method (with argument 0) must be made.
+  //
+  // Returns an error status if `num_iterations` is non-positive, if
+  // preprocessing was indicated but `PreprocessingComplete()` has not been
+  // called, or if successive calls of this method do not pass monotonically
+  // ascending `iteration` values of 1, 2, ..., `num_iterations`.
+  absl::Status IterationComplete(int iteration);
+
+  // Indicates that all iterations are complete. This is equivalent to calling
+  // `IterationComplete(num_iterations)`, but can be used in cases where the
+  // algorithm detects that it has converged early and not all expected
+  // iterations are required
+  //
+  // Returns an error status if `num_iterations` is non-positive or if
+  // preprocessing was indicated but `PreprocessingComplete()` has not been
+  // called.
+  absl::Status IterationsDoneEarly();
+
+  // Indicate that the postprocessing step is complete. Returns an error status
+  // if `has_postprocessing_` is false or if no call of `IterationComplete()`
+  // has been made.
+  absl::Status PostprocessingComplete();
+
+ private:
+  /*const*/ ReportProgressT report_progress_;
+  const int num_iterations_;
+  const bool has_preprocessing_;
+  const bool has_postprocessing_;
+  const int total_steps_;
+  int num_steps_completed_ = 0;
+
+  // Invokes the `report_progress_` callback so as to reflect
+  // `num_steps_completed_` worth of progress out of `total_steps_`.
+  void ReportProgress();
+};
+
+}  // namespace gbbs

gbbs/helpers/progress_reporting_mock.h

@@ -0,0 +1,48 @@
+#pragma once
+
+#include <vector>
+
+#include "absl/base/attributes.h"
+#include "gbbs/helpers/progress_reporting.h"
+
+namespace gbbs {
+
+// Test-only class for mocking the progress reporting of an algorithm. This
+// is intended to be a mix-in class to be combined into a test fixture, like
+// this:
+//
+// class MyAlgorithmTest : public testing::Test, public ReportProgressMock {
+//   // ...
+// };
+//
+// TEST_F(MyAlgorithmTest, DoesFoo) {
+//   // Invoke method under test.
+//   EXPECT_THAT(clusterer_.Cluster(..., MockReportProgress()),
+//               IsOkAndHolds(...));
+//   // Check that the progress reports were as expected.
+//   EXPECT_THAT(GetProgressReports(), ElementsAre(0.0, 1.0));
+// }
+//
+// Note that because `MockReportProgress()` clears any previous progress
+// reports, multiple `MockReportProgress()` ... `GetProgressReports()` call
+// pairs can be used in a single test.
+class ReportProgressMock {
+ public:
+  // Returns a new ReportProgress `AnyInvocable` that records its successive
+  // arguments in `progress_reports_`. Any previously recorded progress reports
+  // are cleared.
+  ReportProgressT MockReportProgress() ABSL_ATTRIBUTE_LIFETIME_BOUND {
+    progress_reports_.clear();
+    return [this](float progress) {
+      this->progress_reports_.push_back(progress);
+    };
+  }
+
+  // Returns the arguments to the sequence of progress report calls.
+  std::vector<float> GetProgressReports() const { return progress_reports_; }
+
+ private:
+  std::vector<float> progress_reports_;
+};
+
+}  // namespace gbbs