update documentation

shahor02 · shahor02 · commit a0910bf420cf · 2022-04-24T01:28:43.000+02:00
diff --git a/Detectors/Base/README.md b/Detectors/Base/README.md
@@ -25,21 +25,24 @@ and the method `GRPGeomRequest::instance()->checkUpdates(pc)` is called in the b
 ```cpp
 class MyTask {
  public:
-  MyTask(std::shared_ptr<GRPGeomRequest> req, ...)
-  {
-    GRPGeomRequest::instance()->setRequest(req);
+  MyTask(std::shared_ptr<GRPGeomRequest> req, ...) : mCCDBReq(req) {
+  }
+  void init(o2::framework::InitContext& ic) {
+    GRPGeomHelper::instance()->setRequest(req);
     ...
   }
   void finaliseCCDB(ConcreteDataMatcher& matcher, void* obj)
   {
-    GRPGeomRequest::instance()->finaliseCCDB(matcher, obj);
+    GRPGeomHelper::instance()->finaliseCCDB(matcher, obj);
     ...
   }
   void run(ProcessingContext& pc)
   {
-    GRPGeomRequest::instance()->checkUpdates(pc);
+    GRPGeomHelper::instance()->checkUpdates(pc);
     ...
   }
+  protected:
+   std::shared_ptr<GRPGeomRequest> mCCDBReq;
 };
 ```
 
diff --git a/Detectors/Calibration/README.md b/Detectors/Calibration/README.md
@@ -9,15 +9,17 @@ The calibration flow of O2 foresees that every calibration device (expected to a
 ## TimeSlotCalibration<Input, Container>
 Each calibration device (to be run in a workflow) has to derive from `o2::calibration::TimeSlotCalibration`, which is a templated class that takes as types the Input type (i.e. the object to be processed, coming from the upstream device) and the Container type (i.e. the object that will contain the calibration data per TimeSlot). Each calibration device has to be configured with the following parameters:
 
-```cpp
-tf-per-slot               : default length of a TiemSlot in TFs (will be widened in case of too little statistics). If this is set to `std::numeric_limits<long>::max()`, then there will be
-                            only 1 slot at a time, valid till infinity.
-updateInterval            : to be used together with `tf-per-slot = std::numeric_limits<long>::max()`: it allows to try to finalize the slot (and produce calibration) when the `updateInterval`
-                            has passed. Note that this is an approximation (as explained in the code) due to the fact that TFs will come asynchronously (not ordered in time).
-max-delay                 : maximum arrival delay of a TF with respect to the most recent one processed; units in number of TimeSlots; if beyond this, the TF will be considered too old, and discarded.
-                            If `tf-per-slot == std::numeric_limits<long>::max()`, or `updateAtTheEndOfRunOnly == true`, its value is irrelevant.
-updateAtTheEndOfRunOnly   : to tell the TimeCalibration to finalize the slots and prepare the CCDB entries only at the end of the run.
-```
+`tf-per-slot` : default length of a TiemSlot in TFs (will be widened in case of too little statistics). If this is set to `o2::calibration::INFINITE_TF`, then there will be only 1 slot at a time, valid till infinity. Value 0 is reserved for a special mode: a single slot w/o explicit boundaries is
+filled until the requested statistics is reached. Once `hasEnoughData` return true, the slot will be closed with really seen min/max TFs and new one will be created with lower boundary equal the end of the previous slot.
+The slot duration can be also set via methods `setSlotLengthInSeconds(int s)` or `setSlotLengthInOrbits(int n)`, which will be internally converted (and rounded) to the number of TFs at the 1st TF processing (when the NHBF per orbit will be available from the GRPECS).
+
+`updateInterval` : to be used together with `tf-per-slot = o2::calibration::INFINITE_TF`: it allows to try to finalize the slot (and produce calibration) when the `updateInterval` has passed. Note that this is an approximation (as explained in the code) due to the fact that TFs will come asynchronously (not ordered in time).
+
+`max-delay` : maximum arrival delay of a TF with respect to the most recent one processed; units in number of TimeSlots; if beyond this, the TF will be considered too old, and discarded.
+If `tf-per-slot == o2::calibration::INFINITE_TF`, or `updateAtTheEndOfRunOnly == true`, its value is irrelevant.
+
+`updateAtTheEndOfRunOnly` : to tell the TimeCalibration to finalize the slots and prepare the CCDB entries only at the end of the run.
+
 Example for the options above:
 `tf-per-slot = 20`
 `max-delay = 3`
@@ -31,7 +33,7 @@ Each calibration device has to implement the following methods:
 
 `void finalizeSlot(o2::calibration::TimeSlot<Container>& slot)` : method to process the calibration data accumulated in each TimeSlot;
 
-`o2::calibration::TimeSlot<Container>& slot emplaceNewSlot(bool front, uint64_t tstart, uint64_t tend` : method to creata a new TimeSlot; this is specific to the calibration procedure as it instantiates the detector-calibration-specific object.
+`o2::calibration::TimeSlot<Container>& slot emplaceNewSlot(bool front, TFType tstart, TFType tend)` : method to creata a new TimeSlot; this is specific to the calibration procedure as it instantiates the detector-calibration-specific object.
 
 See e.g. LHCClockCalibrator.h/cxx in AliceO2/Detectors/TOF/calibration/include/TOFCalibration/LHCClockCalibrator.h and  AliceO2/Detectors/TOF/calibration/srcLHCClockCalibrator.cxx
 
@@ -51,6 +53,8 @@ If provided, this latter method will be used.
 
 See e.g. LHCClockCalibrator.h/cxx in AliceO2/Detectors/TOF/calibration/include/TOFCalibration/LHCClockCalibrator.h and  AliceO2/Detectors/TOF/calibration/srcLHCClockCalibrator.cxx
 
+The Slot provides a generic methods to access its boundaries: `getTFStart()` and `getTFEnd()` in terms of TF counter (as assigned by the DataDistribution) and `getStartTimeMS()`, `getEndTimeMS()` for the absolute time stamp in milleseconds.
+
 ## detector-specific-calibrator-workflow
 
 Each calibration will need to be implemented in the form of a workflow, whose options should include those for the calibration device itself (`tf-per-slot` and `max-delay`, see above).
@@ -68,6 +72,8 @@ output.snapshot(Output{o2::calibration::Utils::gDataOriginCDBPayload, "TOF_LHCph
 output.snapshot(Output{o2::calibration::Utils::gDataOriginCDBWrapper, "TOF_LHCphase", i}, w);            // root-serialized
 ```
 
+Note that in order to access the absolute time of the slot boundaries, one should subscribe to CTP orbit reset time object (at least) via GRPGeomHelper class.
+
 See e.g. AliceO2/Detectors/TOF/calibration/testWorkflow/LHCClockCalibratorSpec.h,  AliceO2/Detectors/TOF/calibration/testWorkflow/lhc-clockphase-workflow.cxx
 
 ## ccdb-populator-workflow

Original file line number	Diff line number	Diff line change
@@ -25,21 +25,24 @@ and the method `GRPGeomRequest::instance()->checkUpdates(pc)` is called in the b
`25`	`25`	```cpp
`26`	`26`	`class MyTask {`
`27`	`27`	`public:`
`28`		`- MyTask(std::shared_ptr<GRPGeomRequest> req, ...)`
`29`		`- {`
`30`		`- GRPGeomRequest::instance()->setRequest(req);`
	`28`	`+ MyTask(std::shared_ptr<GRPGeomRequest> req, ...) : mCCDBReq(req) {`
	`29`	`+ }`
	`30`	`+ void init(o2::framework::InitContext& ic) {`
	`31`	`+ GRPGeomHelper::instance()->setRequest(req);`
`31`	`32`	`...`
`32`	`33`	`}`
`33`	`34`	`void finaliseCCDB(ConcreteDataMatcher& matcher, void* obj)`
`34`	`35`	`{`
`35`		`- GRPGeomRequest::instance()->finaliseCCDB(matcher, obj);`
	`36`	`+ GRPGeomHelper::instance()->finaliseCCDB(matcher, obj);`
`36`	`37`	`...`
`37`	`38`	`}`
`38`	`39`	`void run(ProcessingContext& pc)`
`39`	`40`	`{`
`40`		`- GRPGeomRequest::instance()->checkUpdates(pc);`
	`41`	`+ GRPGeomHelper::instance()->checkUpdates(pc);`
`41`	`42`	`...`
`42`	`43`	`}`
	`44`	`+ protected:`
	`45`	`+ std::shared_ptr<GRPGeomRequest> mCCDBReq;`
`43`	`46`	`};`
`44`	`47`	```
`45`	`48`