From d3283fdf2c0057f80c59f25ef4d53f6ec64975a1 Mon Sep 17 00:00:00 2001
From: Ronen Friedman <rfriedma@redhat.com>
Date: Thu, 30 Dec 2021 13:04:58 +0000
Subject: [PATCH] osd/scrub: scrub components embedded documentation

Signed-off-by: Ronen Friedman <rfriedma@redhat.com>
---
 src/osd/scrubber/osd_scrub_sched.h | 104 +++++++++++++++++++++++++++++
 src/osd/scrubber/pg_scrubber.h     |   4 +-
 src/osd/scrubber/scrub_backend.h   |   9 ---
 3 files changed, 106 insertions(+), 11 deletions(-)

diff --git a/src/osd/scrubber/osd_scrub_sched.h b/src/osd/scrubber/osd_scrub_sched.h
index fc34be7a201..98309eb47fb 100644
--- a/src/osd/scrubber/osd_scrub_sched.h
+++ b/src/osd/scrubber/osd_scrub_sched.h
@@ -2,6 +2,110 @@
 // vim: ts=8 sw=2 smarttab
 
 #pragma once
+// clang-format off
+/*
+┌───────────────────────┐
+│ OSD                   │
+│ OSDService           ─┼───┐
+│                       │   │
+│                       │   │
+└───────────────────────┘   │   Ownes & uses the following
+                            │   ScrubQueue interfaces:
+                            │
+                            │
+                            │   - resource management (*1)
+                            │
+                            │   - environment conditions (*2)
+                            │
+                            │   - scrub scheduling (*3)
+                            │
+                            │
+                            │
+                            │
+                            │
+                            │
+ ScrubQueue                 │
+┌───────────────────────────▼────────────┐
+│                                        │
+│                                        │
+│  ScrubQContainer    to_scrub <>────────┼────────┐
+│  ScrubQContainer    penalized          │        │
+│                                        │        │
+│                                        │        │
+│  OSD_wide resource counters            │        │
+│                                        │        │
+│                                        │        │
+│  "env scrub conditions" monitoring     │        │
+│                                        │        │
+│                                        │        │
+│                                        │        │
+│                                        │        │
+└─▲──────────────────────────────────────┘        │
+  │                                               │
+  │                                               │
+  │uses interface <4>                             │
+  │                                               │
+  │                                               │
+  │            ┌──────────────────────────────────┘
+  │            │                 shared ownership of jobs
+  │            │
+  │      ┌─────▼──────┐
+  │      │ScrubJob    │
+  │      │            ├┐
+  │      │            ││
+  │      │            │┼┐
+  │      │            │┼│
+  └──────┤            │┼┤◄──────┐
+         │            │┼│       │
+         │            │┼│       │
+         │            │┼│       │
+         └┬───────────┼┼│       │shared ownership
+          └─┼┼┼┼┼┼┼┼┼┼┼┼│       │
+            └───────────┘       │
+                                │
+                                │
+                                │
+                                │
+┌───────────────────────────────┼─┐
+│                               <>│
+│PgScrubber                       │
+│                                 │
+│                                 │
+│                                 │
+│                                 │
+│                                 │
+└─────────────────────────────────┘
+
+
+SqrubQueue interfaces (main functions):
+
+<1> - OSD/PG resources management:
+
+  - can_inc_scrubs()
+  - {inc/dec}_scrubs_{local/remote}()
+  - dump_scrub_reservations()
+  - {set/clear/is}_reserving_now()
+
+<2> - environment conditions:
+
+  - update_loadavg()
+
+  - scrub_load_below_threshold()
+  - scrub_time_permit()
+
+<3> - scheduling scrubs:
+
+  - select_pg_and_scrub()
+  - dump_scrubs()
+
+<4> - manipulating a job's state:
+
+  - register_with_osd()
+  - remove_from_osd_queue()
+  - update_job()
+
+ */
+// clang-format on
 
 #include <atomic>
 #include <chrono>
diff --git a/src/osd/scrubber/pg_scrubber.h b/src/osd/scrubber/pg_scrubber.h
index 6fffed57bd3..313ab7be5cb 100644
--- a/src/osd/scrubber/pg_scrubber.h
+++ b/src/osd/scrubber/pg_scrubber.h
@@ -25,7 +25,7 @@ Main Scrubber interfaces:
                                  │
                                  │
 ┌────────────────────────────────▼──────────────────┐
-│               ScrubPgIf                           │
+│               <<ScrubPgIF>>                       │
 └───────────────────────────▲───────────────────────┘
                             │
                             │
@@ -45,7 +45,7 @@ Main Scrubber interfaces:
       │                   │                         implements
       │    ownes & uses   │                                 │
       │                   │       ┌─────────────────────────▼──────┐
-      │                   │       │    ScrubMachineListener        │
+      │                   │       │    <<ScrubMachineListener>>    │
       │                   │       └─────────▲──────────────────────┘
       │                   │                 │
       │                   │                 │
diff --git a/src/osd/scrubber/scrub_backend.h b/src/osd/scrubber/scrub_backend.h
index 573465d5c50..c866153fb55 100644
--- a/src/osd/scrubber/scrub_backend.h
+++ b/src/osd/scrubber/scrub_backend.h
@@ -271,15 +271,6 @@ class ScrubBackend {
   ConfigProxy& m_conf;
   LogChannelRef clog;
 
-  int num_digest_updates_pending{0};
-
- public:  
-  // as used by PgScrubber::final_cstat_update(). consider relocating.
-  // actually - only filled in by the PG backend, and used by the scrubber.
-  // We are not handling it. So consider getting it from the Scrubber, or
-  // creating it by the PG-BE
-  omap_stat_t m_omap_stats = (const struct omap_stat_t){0};
-
  private:
   using auth_and_obj_errs_t =
     std::tuple<std::list<pg_shard_t>,  ///< the auth-list
-- 
2.39.5