Access

AccessMut

MEComparison

MonitorElement

MonitorElement

MutableMonitorElementData

fits_in_int64_t

Macros

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543
#ifndef DQMSERVICES_CORE_MONITOR_ELEMENT_H
#define DQMSERVICES_CORE_MONITOR_ELEMENT_H

#if __GNUC__ && !defined DQM_DEPRECATED
//#define DQM_DEPRECATED __attribute__((deprecated))
#define DQM_DEPRECATED
#endif

#include "DQMServices/Core/interface/DQMNet.h"

#include "DataFormats/Histograms/interface/MonitorElementCollection.h"

#include "FWCore/Utilities/interface/Exception.h"

#include "TF1.h"
#include "TH1F.h"
#include "TH1S.h"
#include "TH1D.h"
#include "TH1I.h"
#include "TH2F.h"
#include "TH2S.h"
#include "TH2I.h"
#include "TH2D.h"
#include "TH2Poly.h"
#include "TH3F.h"
#include "TProfile.h"
#include "TProfile2D.h"
#include "TObjString.h"
#include "TAxis.h"
#include "TGraph.h"

#include <mutex>
#include <memory>
#include <string>
#include <atomic>
#include <sstream>
#include <iomanip>
#include <cassert>
#include <cstdint>
#include <sys/time.h>
#include <oneapi/tbb/spin_mutex.h>

// TODO: cleaup the usages and remove.
using QReport = MonitorElementData::QReport;
using DQMChannel = MonitorElementData::QReport::DQMChannel;

// TODO: move to a better location (changing all usages)
namespace dqm {
  /** Numeric constants for quality test results.  The smaller the
      number, the less severe the message.  */
  namespace qstatus {
    static const int OTHER = 30;        //< Anything but 'ok','warning' or 'error'.
    static const int DISABLED = 50;     //< Test has been disabled.
    static const int INVALID = 60;      //< Problem preventing test from running.
    static const int INSUF_STAT = 70;   //< Insufficient statistics.
    static const int DID_NOT_RUN = 90;  //< Algorithm did not run.
    static const int STATUS_OK = 100;   //< Test was succesful.
    static const int WARNING = 200;     //< Test had some problems.
    static const int ERROR = 300;       //< Test has failed.
  }  // namespace qstatus

  namespace me_util {
    using Channel = DQMChannel;
  }
}  // namespace dqm

// forward declarations for all our friends
namespace dqm::implementation {
  class DQMStore;
  class IBooker;
}  // namespace dqm::implementation
struct DQMTTreeIO;
namespace dqm {
  class DQMFileSaverPB;
}
class DQMService;
class QualityTester;

namespace dqm::impl {

  using dqmmutex = tbb::spin_mutex;

  struct Access {
    std::unique_lock<dqmmutex> guard_;
    MonitorElementData::Key const &key;
    MonitorElementData::Value const &value;
  };
  // TODO: can this be the same type, just const?
  struct AccessMut {
    std::unique_lock<dqmmutex> guard_;
    MonitorElementData::Key const &key;
    MonitorElementData::Value &value;
  };

  struct MutableMonitorElementData {
    MonitorElementData data_;
    dqmmutex lock_;
    Access access() { return Access{std::unique_lock<dqmmutex>(lock_), data_.key_, data_.value_}; }
    AccessMut accessMut() { return AccessMut{std::unique_lock<dqmmutex>(lock_), data_.key_, data_.value_}; }
  };

  /** The base class for all MonitorElements (ME) */
  class MonitorElement {
    // these need to create and destroy MEs.
    friend dqm::implementation::DQMStore;
    friend dqm::implementation::IBooker;
    // these need to access some of the IO related methods.
    friend ::DQMTTreeIO;  // declared in DQMRootSource
    friend ::dqm::DQMFileSaverPB;
    friend ::DQMService;
    // this one only needs syncCoreObject.
    friend ::QualityTester;

  public:
    using Scalar = MonitorElementData::Scalar;
    using Kind = MonitorElementData::Kind;

    // Comparison helper used in DQMStore to insert into sets. This needs deep
    // private access to the MEData, that is why it lives here.
    struct MEComparison {
      using is_transparent = int;  // magic marker to allow C++14 heterogeneous set lookup.

      auto make_tuple(MonitorElement *me) const {
        return std::make_tuple(std::reference_wrapper(me->getPathname()), std::reference_wrapper(me->getName()));
      }
      auto make_tuple(MonitorElementData::Path const &path) const {
        return std::make_tuple(std::reference_wrapper(path.getDirname()), std::reference_wrapper(path.getObjectname()));
      }
      bool operator()(MonitorElement *left, MonitorElement *right) const {
        return make_tuple(left) < make_tuple(right);
      }
      bool operator()(MonitorElement *left, MonitorElementData::Path const &right) const {
        return make_tuple(left) < make_tuple(right);
      }
      bool operator()(MonitorElementData::Path const &left, MonitorElement *right) const {
        return make_tuple(left) < make_tuple(right);
      }
      bool operator()(MonitorElementData::Path const &left, MonitorElementData::Path const &right) const {
        return make_tuple(left) < make_tuple(right);
      }
    };

  private:
    std::shared_ptr<MutableMonitorElementData> mutable_;  // only set if this is a mutable copy of this ME
    // there are no immutable MEs at this time, but we might need them in the future.
    /** 
     * To do anything to the MEs data, one needs to obtain an access object.
     * This object will contain the lock guard if one is needed. We differentiate
     * access for reading and access for mutation (denoted by `Access` or
     * `AccessMut`, however, also read-only access may need to take a lock
     * if it is to a mutable object. 
     * We want all of this inlined and redundant operations any copies/refs
     * optimized away.
     */
    const Access access() const {
      // First, check if there is a mutable object
      if (mutable_) {
        // if there is a mutable object, that is the truth, and we take a lock.
        return mutable_->access();
      }  // else
      throw cms::Exception("LogicError") << "MonitorElement " << getName() << " not backed by any data!";
    }

    AccessMut accessMut() {
      // For completeness, set the legacy `updated` marker.
      this->update();

      // First, check if there is a mutable object
      if (mutable_) {
        // if there is a mutable object, that is the truth, and we take a lock.
        return mutable_->accessMut();
      }  // else
      throw cms::Exception("LogicError") << "MonitorElement " << getName() << " not backed by any data!";
    }

  private:
    // but internal -- only for DQMStore etc.

    // Create ME using this data. A ROOT object pointer may be moved into the
    // new ME. The new ME will own this data.
    MonitorElement(MonitorElementData &&data);
    // Create new ME and take ownership of this data.
    MonitorElement(std::shared_ptr<MutableMonitorElementData> data);
    // Create a new ME sharing data with this existing ME.
    MonitorElement(MonitorElement *me);

    // return a new clone of the data of this ME. Calls ->Clone(), new object
    // is owned by the returned value.
    MonitorElementData cloneMEData();

    // Remove access to the data.
    std::shared_ptr<MutableMonitorElementData> release();

    // re-initialize this ME as a shared copy of the other.
    void switchData(MonitorElement *other);
    // re-initialize taking ownership of this data.
    void switchData(std::shared_ptr<MutableMonitorElementData> data);

    // Replace the ROOT object in this ME's data with the new object, taking
    // ownership. The old object is deleted.
    void switchObject(std::unique_ptr<TH1> &&newobject);

    // copy applicable fileds into the DQMNet core object for compatibility.
    // In a few places these flags are also still used by the ME.
    void syncCoreObject();
    void syncCoreObject(AccessMut &access);

    // check if the ME is currently backed by MEData; if false (almost) any
    // access will throw.
    bool isValid() const { return mutable_ != nullptr; }

    // used to implement getQErrors et. al.
    template <typename FILTER>
    std::vector<MonitorElementData::QReport *> filterQReports(FILTER filter) const;

    // legacy interfaces, there are no alternatives but they should not be used

    /// Compare monitor elements, for ordering in sets.
    bool operator<(const MonitorElement &x) const { return DQMNet::setOrder(data_, x.data_); }
    /// Check the consistency of the axis labels
    static bool CheckBinLabels(const TAxis *a1, const TAxis *a2);
    /// Get the object flags.
    uint32_t flags() const { return data_.flags; }
    /// Mark the object updated.
    void update() { data_.flags |= DQMNet::DQM_PROP_NEW; }

    // mostly used for IO, should be private.
    std::string valueString() const;
    std::string tagString() const;
    std::string tagLabelString() const;
    std::string effLabelString() const;
    std::string qualityTagString(const DQMNet::QValue &qv) const;

    // kept for DQMService. data_ is also used for MEComparison, without it
    // we'd need to keep a copy od the name somewhere else.
    /// true if ME was updated in last monitoring cycle
    bool wasUpdated() const { return data_.flags & DQMNet::DQM_PROP_NEW; }
    void packScalarData(std::string &into, const char *prefix) const;
    void packQualityData(std::string &into) const;
    DQMNet::CoreObject data_;  //< Core object information.

  public:
    MonitorElement &operator=(const MonitorElement &) = delete;
    MonitorElement &operator=(MonitorElement &&) = delete;
    virtual ~MonitorElement();

  public:
    // good to be used in subsystem code

    /// Get the type of the monitor element.
    Kind kind() const { return Kind(data_.flags & DQMNet::DQM_PROP_TYPE_MASK); }

    /// get name of ME
    const std::string &getName() const { return this->data_.objname; }

    /// get pathname of parent folder
    const std::string &getPathname() const { return this->data_.dirname; }

    /// get full name of ME including Pathname
    std::string getFullname() const { return access().key.path_.getFullname(); }

    edm::LuminosityBlockID getRunLumi() { return access().key.id_; }

    MonitorElementData::Scope getScope() { return access().key.scope_; }

    /// true if ME is meant to be stored for each luminosity section
    bool getLumiFlag() const { return access().key.scope_ == MonitorElementData::Scope::LUMI; }

    /// this ME is meant to be an efficiency plot that must not be
    /// normalized when drawn in the DQM GUI.
    void setEfficiencyFlag() {
      auto access = this->accessMut();
      if (access.value.object_)
        access.value.object_->SetBit(TH1::kIsAverage);
    }
    bool getEfficiencyFlag() {
      auto access = this->access();
      return access.value.object_ && access.value.object_->TestBit(TH1::kIsAverage);
    }

  private:
    // A static assert to check that T actually fits in
    // int64_t.
    template <typename T>
    struct fits_in_int64_t {
      int checkArray[sizeof(int64_t) - sizeof(T) + 1];
    };

    void doFill(int64_t x);

  public:
    // filling API.

    void Fill(long long x) {
      fits_in_int64_t<long long>();
      doFill(static_cast<int64_t>(x));
    }
    void Fill(unsigned long long x) {
      fits_in_int64_t<unsigned long long>();
      doFill(static_cast<int64_t>(x));
    }
    void Fill(unsigned long x) {
      fits_in_int64_t<unsigned long>();
      doFill(static_cast<int64_t>(x));
    }
    void Fill(long x) {
      fits_in_int64_t<long>();
      doFill(static_cast<int64_t>(x));
    }
    void Fill(unsigned int x) {
      fits_in_int64_t<unsigned int>();
      doFill(static_cast<int64_t>(x));
    }
    void Fill(int x) {
      fits_in_int64_t<int>();
      doFill(static_cast<int64_t>(x));
    }
    void Fill(short x) {
      fits_in_int64_t<short>();
      doFill(static_cast<int64_t>(x));
    }
    void Fill(unsigned short x) {
      fits_in_int64_t<unsigned short>();
      doFill(static_cast<int64_t>(x));
    }
    void Fill(char x) {
      fits_in_int64_t<char>();
      doFill(static_cast<int64_t>(x));
    }
    void Fill(unsigned char x) {
      fits_in_int64_t<unsigned char>();
      doFill(static_cast<int64_t>(x));
    }

    void Fill(float x) { Fill(static_cast<double>(x)); }
    void Fill(double x);
    void Fill(std::string &value);

    void Fill(double x, double yw);
    void Fill(double x, double y, double zw);
    void Fill(double x, double y, double z, double w);
    DQM_DEPRECATED
    void ShiftFillLast(double y, double ye = 0., int32_t xscale = 1);

  public:
    // additional APIs, mainly for harvesting.

    /// Remove all data from the ME, keept the empty histogram with all its settings.
    virtual void Reset();

    /// true if at least of one of the quality tests returned an error
    bool hasError() const { return data_.flags & DQMNet::DQM_PROP_REPORT_ERROR; }

    /// true if at least of one of the quality tests returned a warning
    bool hasWarning() const { return data_.flags & DQMNet::DQM_PROP_REPORT_WARN; }

    /// true if at least of one of the tests returned some other (non-ok) status
    bool hasOtherReport() const { return data_.flags & DQMNet::DQM_PROP_REPORT_OTHER; }

    /// get QReport corresponding to <qtname> (null pointer if QReport does not exist)
    const MonitorElementData::QReport *getQReport(const std::string &qtname) const;
    /// get map of QReports
    std::vector<MonitorElementData::QReport *> getQReports() const;
    /// access QReport, potentially adding it.
    void getQReport(bool create, const std::string &qtname, MonitorElementData::QReport *&qr, DQMNet::QValue *&qv);

    /// get warnings from last set of quality tests
    std::vector<MonitorElementData::QReport *> getQWarnings() const;
    /// get errors from last set of quality tests
    std::vector<MonitorElementData::QReport *> getQErrors() const;
    /// from last set of quality tests
    std::vector<MonitorElementData::QReport *> getQOthers() const;

    // const and data-independent -- safe
    virtual int getNbinsX() const;
    virtual int getNbinsY() const;
    virtual int getNbinsZ() const;
    virtual int getBin(int binx, int biny) const;
    virtual int getNcells() const;
    virtual std::string getAxisTitle(int axis = 1) const;
    virtual std::string getTitle() const;

    // const but data-dependent -- semantically unsafe in RECO
    virtual double getMean(int axis = 1) const;
    virtual double getMeanError(int axis = 1) const;
    virtual double getRMS(int axis = 1) const;
    virtual double getRMSError(int axis = 1) const;
    virtual double getBinContent(int binx) const;
    virtual double getBinContent(int binx, int biny) const;
    virtual double getBinContent(int binx, int biny, int binz) const;
    virtual double getBinError(int binx) const;
    virtual double getBinError(int binx, int biny) const;
    virtual double getBinError(int binx, int biny, int binz) const;
    virtual double getEntries() const;
    virtual double getBinEntries(int bin) const;
    virtual double getBinEntries(int binx, int biny) const;
    virtual double integral() const;

    virtual int64_t getIntValue() const;
    virtual double getFloatValue() const;
    virtual const std::string &getStringValue() const;

    // non-const -- thread safety and semantical issues
    virtual void addBin(TGraph *graph);
    virtual void addBin(int n, const double *x, const double *y);
    virtual void addBin(double x1, double y1, double x2, double y2);
    virtual void setBinContent(int binx, double content);
    virtual void setBinContent(int binx, int biny, double content);
    virtual void setBinContent(int binx, int biny, int binz, double content);
    virtual void setBinError(int binx, double error);
    virtual void setBinError(int binx, int biny, double error);
    virtual void setBinError(int binx, int biny, int binz, double error);
    virtual void setBinEntries(int bin, double nentries);
    virtual void setEntries(double nentries);
    virtual void divide(const MonitorElement *, const MonitorElement *, double, double, const char *);
    virtual void setBinLabel(int bin, const std::string &label, int axis = 1);
    virtual void setAxisRange(double xmin, double xmax, int axis = 1);
    virtual void setAxisTitle(const std::string &title, int axis = 1);
    virtual void setAxisTimeDisplay(int value, int axis = 1);
    virtual void setAxisTimeFormat(const char *format = "", int axis = 1);
    virtual void setTitle(const std::string &title);

    // additional operations mainly for booking
    virtual void setXTitle(std::string const &title);
    virtual void setYTitle(std::string const &title);
    virtual void enableSumw2();
    virtual void disableAlphanumeric();
    virtual void setOption(const char *option);
    virtual double getAxisMin(int axis = 1) const;
    virtual double getAxisMax(int axis = 1) const;
    // We should avoid extending histograms in general, and if the behaviour
    // is actually needed, provide a more specific interface rather than
    // relying on the ROOT behaviour.
    DQM_DEPRECATED
    virtual void setCanExtend(unsigned int value);
    // We should decide if we support this (or make it default)
    DQM_DEPRECATED
    virtual void setStatOverflows(bool value);
    virtual bool getStatOverflows();

    // these should be non-const, since they are potentially not thread-safe
    virtual TObject const *getRootObject() const;
    virtual TH1 *getTH1();
    virtual TH1F *getTH1F();
    virtual TH1S *getTH1S();
    virtual TH1D *getTH1D();
    virtual TH1I *getTH1I();
    virtual TH2F *getTH2F();
    virtual TH2S *getTH2S();
    virtual TH2I *getTH2I();
    virtual TH2D *getTH2D();
    virtual TH2Poly *getTH2Poly();
    virtual TH3F *getTH3F();
    virtual TProfile *getTProfile();
    virtual TProfile2D *getTProfile2D();

  private:
    void incompatible(const char *func) const;
    TH1 const *accessRootObject(Access const &access, const char *func, int reqdim) const;
    TH1 *accessRootObject(AccessMut const &, const char *func, int reqdim) const;

    TAxis const *getAxis(Access const &access, const char *func, int axis) const;
    TAxis *getAxis(AccessMut const &access, const char *func, int axis) const;
  };

}  // namespace dqm::impl

// These may become distinct classes in the future.
namespace dqm::reco {
  using MonitorElement = dqm::impl::MonitorElement;
}
namespace dqm::legacy {
  class MonitorElement : public dqm::reco::MonitorElement {
  public:
    // import constructors
    using dqm::reco::MonitorElement::MonitorElement;

    // Add ROOT object accessors without cost here so that harvesting code can
    // still freely use getTH1() and friends.
    using dqm::reco::MonitorElement::getRootObject;
    TObject *getRootObject() const override {
      return const_cast<TObject *>(
          const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getRootObject());
    };
    using dqm::reco::MonitorElement::getTH1;
    virtual TH1 *getTH1() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH1();
    };
    using dqm::reco::MonitorElement::getTH1F;
    virtual TH1F *getTH1F() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH1F();
    };
    using dqm::reco::MonitorElement::getTH1S;
    virtual TH1S *getTH1S() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH1S();
    };
    using dqm::reco::MonitorElement::getTH1D;
    virtual TH1D *getTH1D() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH1D();
    };
    using dqm::reco::MonitorElement::getTH1I;
    virtual TH1I *getTH1I() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH1I();
    };
    using dqm::reco::MonitorElement::getTH2F;
    virtual TH2F *getTH2F() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH2F();
    };
    using dqm::reco::MonitorElement::getTH2S;
    virtual TH2S *getTH2S() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH2S();
    };
    using dqm::reco::MonitorElement::getTH2I;
    virtual TH2I *getTH2I() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH2I();
    };
    using dqm::reco::MonitorElement::getTH2D;
    virtual TH2D *getTH2D() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH2D();
    };
    using dqm::reco::MonitorElement::getTH2Poly;
    virtual TH2Poly *getTH2Poly() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH2Poly();
    };
    using dqm::reco::MonitorElement::getTH3F;
    virtual TH3F *getTH3F() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTH3F();
    };
    using dqm::reco::MonitorElement::getTProfile;
    virtual TProfile *getTProfile() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTProfile();
    };
    using dqm::reco::MonitorElement::getTProfile2D;
    virtual TProfile2D *getTProfile2D() const {
      return const_cast<dqm::legacy::MonitorElement *>(this)->dqm::reco::MonitorElement::getTProfile2D();
    };
  };
}  // namespace dqm::legacy
namespace dqm::harvesting {
  using MonitorElement = dqm::legacy::MonitorElement;
}

#endif  // DQMSERVICES_CORE_MONITOR_ELEMENT_H