| Line | Branch | Exec | Source |
|---|---|---|---|
| 1 | /* This file is a part of NA64SW software. | ||
| 2 | * Copyright (C) 2015-2022 NA64 Collaboration, CERN | ||
| 3 | * | ||
| 4 | * NA64SW is free software: you can redistribute it and/or modify | ||
| 5 | * it under the terms of the GNU General Public License as published by | ||
| 6 | * the Free Software Foundation, either version 3 of the License, or | ||
| 7 | * (at your option) any later version. | ||
| 8 | * | ||
| 9 | * This program is distributed in the hope that it will be useful, | ||
| 10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 12 | * GNU General Public License for more details. | ||
| 13 | * | ||
| 14 | * You should have received a copy of the GNU General Public License | ||
| 15 | * along with this program. If not, see <https://www.gnu.org/licenses/>. */ | ||
| 16 | |||
| 17 | #pragma once | ||
| 18 | |||
| 19 | #include "na64util/YAMLAssertions.hh" | ||
| 20 | #include "na64util/str-fmt.hh" | ||
| 21 | #include "na64util/vctr.hh" | ||
| 22 | #include "na64util/mem/fwd.hh" | ||
| 23 | #include "na64event/reset-values.hh" | ||
| 24 | #include "na64dp/fallback.hh" | ||
| 25 | |||
| 26 | #include "log4cpp/Category.hh" | ||
| 27 | |||
| 28 | #include <map> | ||
| 29 | #include <yaml-cpp/yaml.h> | ||
| 30 | |||
| 31 | namespace na64dp { | ||
| 32 | |||
| 33 | namespace calib { class Manager; } // fwd | ||
| 34 | namespace event { struct Event; } // fwd | ||
| 35 | |||
| 36 | ///\defgroup handlers Data processing handlers | ||
| 37 | ///\defgroup generic-handlers Handlers parameterised with type or attribute | ||
| 38 | |||
| 39 | /**\brief An abstract handler class | ||
| 40 | * | ||
| 41 | * Defines an interface for all the handlers implemented in the pipeline. | ||
| 42 | * | ||
| 43 | * \todo document local memory behaviour (invokation code must guarantee (re-)set). | ||
| 44 | */ | ||
| 45 | class AbstractHandler : public aux::FallbackableMixin { | ||
| 46 | public: | ||
| 47 | ///\brief Type of the numerical code returned by handler adter processing done. | ||
| 48 | enum ProcRes : uint8_t { | ||
| 49 | /// This is the default return code meaning that event should be | ||
| 50 | /// propagated further by the pipeline. | ||
| 51 | kOk = 0x0, | ||
| 52 | /// This flag in returning result stops the caller code to | ||
| 53 | /// propagate the event to next handlers in pipeline. After that the | ||
| 54 | /// caller code may continue with next event from source. | ||
| 55 | kDiscriminateEvent = 0x2, | ||
| 56 | /// This flag must be considered by the caller code as a terminative | ||
| 57 | /// signal -- no more event must be processed by the caller code. | ||
| 58 | /// Together with `kDiscriminateEvent' flag it stops the further | ||
| 59 | /// propagation of current event as well | ||
| 60 | kStopProcessing = 0x4, | ||
| 61 | /// A shortcut for instant stop of processing. | ||
| 62 | kAbortProcessing = kDiscriminateEvent | kStopProcessing, | ||
| 63 | }; | ||
| 64 | private: | ||
| 65 | /// Local memory pointer; used by handlers that may allocate new event data | ||
| 66 | /// properties. | ||
| 67 | LocalMemory * _lmemPtr; | ||
| 68 | protected: | ||
| 69 | /// Handlers logger category | ||
| 70 | log4cpp::Category & _log; | ||
| 71 | |||
| 72 | /// Returns local memory reference during the event processing | ||
| 73 | LocalMemory & lmem() { assert(_lmemPtr); return *_lmemPtr; } | ||
| 74 | public: | ||
| 75 | /// Default ctr, only initializes logger for "handlers" category. | ||
| 76 | AbstractHandler(); | ||
| 77 | /// Default ctr, only initializes logger. | ||
| 78 | AbstractHandler(log4cpp::Category &); | ||
| 79 | /// Abstract method processing the event. Doing most of the handler's work. | ||
| 80 | /// Returning value of type `ProcRes` signaling the pipeline how to | ||
| 81 | /// proceed with the event. | ||
| 82 | virtual ProcRes process_event(event::Event & event) = 0; | ||
| 83 | /// Method performing some operations after all the | ||
| 84 | /// events were processed and before the resources will be freed (e.g. | ||
| 85 | /// before output ROOT file is closed). | ||
| 86 | virtual void finalize(); | ||
| 87 | /// Dtr made virtual to provide generic deletion of handler subclass | ||
| 88 | /// instances, does nothing. | ||
| 89 | 4 | virtual ~AbstractHandler() {} | |
| 90 | /// Returns current logger instance affiliated to handlers objects. | ||
| 91 | log4cpp::Category & log() { return _log; } | ||
| 92 | |||
| 93 | /// Sets the local memory reference prior to the invokation to the | ||
| 94 | /// processing. | ||
| 95 | /// Must be called by invokation code explicitly, typically prior to `try`. | ||
| 96 | void set_local_memory( LocalMemory & ); | ||
| 97 | /// Reets the local memory reference after invokation to the processing. | ||
| 98 | /// Must be called by invokation code explicitly, typically within the | ||
| 99 | /// `catch` block. | ||
| 100 | void reset_local_memory(); | ||
| 101 | }; | ||
| 102 | |||
| 103 | ///\brief Virtual constructor traits for `AbstractHandler` class | ||
| 104 | /// | ||
| 105 | /// Provides constructor callback type that requires calibration data | ||
| 106 | /// dispatcher and configuration node to be used to construct the handler. | ||
| 107 | template<> struct CtrTraits<AbstractHandler> { | ||
| 108 | typedef AbstractHandler * (*Constructor) | ||
| 109 | ( calib::Manager &, const YAML::Node & ); | ||
| 110 | }; | ||
| 111 | |||
| 112 | namespace util { | ||
| 113 | |||
| 114 | /// Returns getter instance by name | ||
| 115 | template<typename T> typename event::Traits<T>::Getter | ||
| 116 | value_getter( const std::string & nm ) { | ||
| 117 | auto it = event::Traits<T>::getters.find(nm); | ||
| 118 | if( event::Traits<T>::getters.end() == it ) { | ||
| 119 | NA64DP_RUNTIME_ERROR( "No getter named \"%s\".", nm.c_str() ); | ||
| 120 | } | ||
| 121 | return it->second.second; | ||
| 122 | } | ||
| 123 | |||
| 124 | } // namespace na64dp::util | ||
| 125 | |||
| 126 | namespace aux { | ||
| 127 | |||
| 128 | ///\brief Gets logging category from handler-config | ||
| 129 | /// | ||
| 130 | /// Standard way to obtain logging category from handler configuration. First, | ||
| 131 | /// looks for parameter `_log` in given config node and returns its value if | ||
| 132 | /// given. Otherwise, looks for `_label` and retrieves `handlers.` + label | ||
| 133 | /// category. If failed, a "handlers" category will be returned. | ||
| 134 | log4cpp::Category & get_logging_cat(const YAML::Node &); | ||
| 135 | |||
| 136 | } // namespace aux | ||
| 137 | } // namespace na64dp | ||
| 138 | |||
| 139 | /**\brief Registers new event handler type for pipeline data processing | ||
| 140 | * \ingroup vctr-defs | ||
| 141 | * | ||
| 142 | * Registers subclasses of `AbstractHandler` base to be created with `VCtr`. | ||
| 143 | * | ||
| 144 | * \param clsName The name of the handler type | ||
| 145 | * \param calibDsp The name of calibations manager instance to be used in ctr | ||
| 146 | * \param ni The name of the config (YAML) node to be used in the ctr | ||
| 147 | * \param desc An event handler type description string | ||
| 148 | */ | ||
| 149 | # define REGISTER_HANDLER( clsName, calibDsp, ni, desc ) \ | ||
| 150 | static na64dp::AbstractHandler * _new_ ## clsName ## _instance( na64dp::calib::Manager & \ | ||
| 151 | , const YAML::Node & ); \ | ||
| 152 | static bool _regResult_ ## clsName = \ | ||
| 153 | ::na64dp::VCtr::self().register_class<na64dp::AbstractHandler>( # clsName, _new_ ## clsName ## _instance, desc ); \ | ||
| 154 | static na64dp::AbstractHandler * _new_ ## clsName ## _instance( __attribute__((unused)) na64dp::calib::Manager & calibDsp \ | ||
| 155 | , __attribute__((unused)) const YAML::Node & ni ) | ||
| 156 | |||
| 157 |