Module.hpp 7.17 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
/** @file
 *  @brief Base class for Corryvreckan modules
 *  @copyright Copyright (c) 2017 CERN and the Corryvreckan authors.
 * This software is distributed under the terms of the MIT License, copied verbatim in the file "LICENSE.md".
 * In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an
 * Intergovernmental Organization or submit itself to any jurisdiction.
 */

#ifndef CORRYVRECKAN_MODULE_H
#define CORRYVRECKAN_MODULE_H
11
12

#include <string>
13

Simon Spannagel's avatar
Simon Spannagel committed
14
#include "ModuleIdentifier.hpp"
15
#include "core/clipboard/Clipboard.hpp"
16
#include "core/config/Configuration.hpp"
17
#include "core/detector/Detector.hpp"
18
#include "exceptions.h"
19

20
namespace corryvreckan {
21
22
23
24
25
26
27
28
29
30
31
32
    /**
     * @brief Flags to signal the status of a module processing a given event
     *
     * These flags are to be used as return values for the Module::run() function to signal the framework the outcome of the
     * event processing. Here, three different states are supported:
     * - Success: the event processing finished successfully and the framework should continue processing this event with the
     * next module.
     * - NoData: there was no data found to process by this module. The framework should skip all following modules and
     * proceed with the next event.
     * - Failure: the module failed to process the event correctly or requests an end of the event processing for other
     * reasons. The framework should stop processing events and call Module::finalise for all modules.
     */
Simon Spannagel's avatar
Simon Spannagel committed
33
34
35
36
37
38
    enum StatusCode {
        Success,
        NoData,
        Failure,
    };

39
40
    /** Base class for all modules
     *  @defgroup Modules Modules
Simon Spannagel's avatar
Simon Spannagel committed
41
     */
42
43
44
45
46
47
48
49
50
51

    /**
     * @brief Base class for all modules
     *
     * The module base is the core of the modular framework. All modules should be descendants of this class. The base class
     * defines the methods the children can implement:
     * - Module::initialise(): for initializing the module at the start
     * - Module::run(Clipoard* Clipboard): for doing the job of every module for every event
     * - Module::finalise(): for finalising the module at the end
     */
52
    class Module {
53
        friend class ModuleManager;
Simon Spannagel's avatar
Simon Spannagel committed
54
55

    public:
56
57
58
59
60
61
        /**
         * @brief Delete default constructor (configuration required)
         */
        Module() = delete;

        /**
62
63
64
65
         * @brief Base constructor for detector modules
         * @param config Configuration for this module
         * @param detector Pointer to the detector this module is bound to
         */
66
        Module(Configuration config, std::shared_ptr<Detector> detector);
67
68
69

        /**
         * @brief Base constructor for unique modules
70
71
72
         * @param config Configuration for this module
         * @param detectors List of detectors this module should be aware of
         */
73
        Module(Configuration config, std::vector<std::shared_ptr<Detector>> detectors);
74
75
76
77
78
79
80
81
82
83
84
85

        /**
         * @brief Essential virtual destructor.
         */
        virtual ~Module();

        /**
         * @brief Copying a module is not allowed
         */
        Module(const Module&) = delete;
        Module& operator=(const Module&) = delete;

Simon Spannagel's avatar
Simon Spannagel committed
86
        /**
Simon Spannagel's avatar
Simon Spannagel committed
87
88
89
         * @brief Get the unique name of this module
         * @return Unique name
         * @note Can be used to interact with ROOT objects that require an unique name
Simon Spannagel's avatar
Simon Spannagel committed
90
         */
Simon Spannagel's avatar
Simon Spannagel committed
91
        std::string getUniqueName() const;
Simon Spannagel's avatar
Simon Spannagel committed
92
93
94
95
96
97
98

        /**
         * @brief Get the configuration for this module
         * @return Reference to the configuration of this module
         */
        Configuration& getConfig() { return m_config; }

99
100
101
102
103
104
105
106
107
108
109
110
111
112
        /**
         * @brief Initialise the module before the event sequence
         *
         * Does nothing if not overloaded.
         */
        virtual void initialise() {}

        /**
         * @brief Execute the function of the module for every event
         * @param clipboard Pointer to the central clipboard to store and fetch information
         * @return Status code of the event processing
         *
         * Does nothing if not overloaded.
         */
113
        virtual StatusCode run(std::shared_ptr<Clipboard>) { return Success; }
114
115
116
117
118
119
120
121

        /**
         * @brief Finalise the module after the event sequence
         * @note Useful to have before destruction to allow for raising exceptions
         *
         * Does nothing if not overloaded.
         */
        virtual void finalise(){};
Simon Spannagel's avatar
Simon Spannagel committed
122

123
124
125
126
127
128
        /**
         * @brief Get ROOT directory which should be used to output histograms et cetera
         * @return ROOT directory for storage
         */
        TDirectory* getROOTDirectory() const;

Simon Spannagel's avatar
Simon Spannagel committed
129
    protected:
Simon Spannagel's avatar
Simon Spannagel committed
130
        // Configuration of this module
Simon Spannagel's avatar
Simon Spannagel committed
131
        Configuration m_config;
132

Simon Spannagel's avatar
Simon Spannagel committed
133
134
135
136
        /**
         * @brief Get list of all detectors this module acts on
         * @return List of all detectors for this module
         */
137
        std::vector<std::shared_ptr<Detector>> get_detectors() { return m_detectors; };
Simon Spannagel's avatar
Simon Spannagel committed
138
139
140
141
142

        /**
         * @brief Get the number of detectors this module takes care of
         * @return Number of detectors to act on
         */
143
        std::size_t num_detectors() { return m_detectors.size(); };
Simon Spannagel's avatar
Simon Spannagel committed
144
145
146
147
148
149
150

        /**
         * @brief Get a specific detector, identified by its name
         * @param  name Name of the detector to retrieve
         * @return Pointer to the requested detector
         * @throws ModuleError if detector with given name is not found for this module
         */
151
        std::shared_ptr<Detector> get_detector(std::string name);
Simon Spannagel's avatar
Simon Spannagel committed
152

153
154
155
156
        /**
         * @brief Get the reference detector for this setup
         * @return Pointer to the reference detector
         */
157
        std::shared_ptr<Detector> get_reference();
158

159
160
        /**
         * @brief Get the device under test
161
         * @return Pointer to the DUT detector.  A nullptr is returned if no DUT is found.
162
163
         * FIXME This should allow retrieval of a vector of DUTs
         */
164
        std::shared_ptr<Detector> get_dut();
165

Simon Spannagel's avatar
Simon Spannagel committed
166
167
168
169
170
        /**
         * @brief Check if this module should act on a given detector
         * @param  name Name of the detector to check
         * @return True if detector is known to this module, false if detector is unknown.
         */
171
        bool has_detector(std::string name);
172

173
    private:
Simon Spannagel's avatar
Simon Spannagel committed
174
175
176
177
178
179
180
181
182
183
184
185
        /**
         * @brief Set the module identifier for internal use
         * @param identifier Identifier of the instantiation
         */
        void set_identifier(ModuleIdentifier identifier);
        /**
         * @brief Get the module identifier for internal use
         * @return Identifier of the instantiation
         */
        ModuleIdentifier get_identifier() const;
        ModuleIdentifier identifier_;

186
187
188
189
190
191
192
        /**
         * @brief Set the output ROOT directory for this module
         * @param directory ROOT directory for storage
         */
        void set_ROOT_directory(TDirectory* directory);
        TDirectory* directory_{nullptr};

193
194
195
196
        // Configure the reference detector:
        void setReference(std::shared_ptr<Detector> reference) { m_reference = reference; };
        std::shared_ptr<Detector> m_reference;

Simon Spannagel's avatar
Simon Spannagel committed
197
        // List of detectors to act on
198
        std::vector<std::shared_ptr<Detector>> m_detectors;
Simon Spannagel's avatar
Simon Spannagel committed
199
    };
Simon Spannagel's avatar
Simon Spannagel committed
200

201
} // namespace corryvreckan
202
203

#endif // CORRYVRECKAN_MODULE_H