]>
Commit | Line | Data |
---|---|---|
bbc27441 | 1 | /* |
b8ae064d | 2 | * Copyright (C) 1996-2023 The Squid Software Foundation and contributors |
bbc27441 AJ |
3 | * |
4 | * Squid software is distributed under GPLv2+ license and includes | |
5 | * contributions from numerous individuals and organizations. | |
6 | * Please see the COPYING and CONTRIBUTORS files for details. | |
7 | */ | |
8 | ||
ff9d9458 FC |
9 | #ifndef SQUID_SRC_BASE_RUNNERSREGISTRY_H |
10 | #define SQUID_SRC_BASE_RUNNERSREGISTRY_H | |
61f3a07b AR |
11 | |
12 | /** | |
21b7990f AR |
13 | * This API allows virtually any module to register its interest in receiving |
14 | * notification about initial configuration availability, configuration changes | |
15 | * and other critical events in Squid lifetime without exposing the notifier | |
16 | * to the details of the module. | |
61f3a07b AR |
17 | * |
18 | * For example, main.cc may activate registered I/O modules after parsing | |
21b7990f AR |
19 | * squid.conf and deactivate them before exiting, all without knowing what |
20 | * those I/O modules really are. | |
61f3a07b AR |
21 | * |
22 | * A module in this context is code providing a functionality or service to the | |
21b7990f AR |
23 | * rest of Squid, such as src/DiskIO/Blocking, src/fs/ufs, or Cache Manager. To |
24 | * receive notifications, a module must declare a RegisteredRunner child class | |
25 | * and implement the methods corresponding to the events the module is | |
26 | * interested in. | |
61f3a07b | 27 | * |
21b7990f AR |
28 | * The order of events is documented in this header (where applicable), but |
29 | * the order in which runners are notified about a given event is undefined. | |
30 | * If a specific notification order is required, split the event into two or | |
31 | * more related event(s), documenting their relative order here. | |
61f3a07b AR |
32 | * |
33 | */ | |
34 | ||
21b7990f AR |
35 | /// a runnable registrant API |
36 | /// kids must override [only] the methods they are interested in | |
37 | class RegisteredRunner | |
38 | { | |
39 | public: | |
40 | /* Related methods below are declared in their calling order */ | |
41 | ||
42 | /* Configuration events */ | |
43 | ||
d2dca19c AJ |
44 | /// Called right before parsing squid.conf. |
45 | /// Meant for initializing/preparing configuration parsing facilities. | |
46 | virtual void bootstrapConfig() {} | |
47 | ||
21b7990f | 48 | /// Called after parsing squid.conf. |
45e8762c AR |
49 | /// Meant for setting configuration options that depend on other |
50 | /// configuration options and were not explicitly configured. | |
21b7990f | 51 | virtual void finalizeConfig() {} |
45e8762c | 52 | |
21b7990f AR |
53 | /// Called after finalizeConfig(). |
54 | /// Meant for announcing memory reservations before memory is allocated. | |
55 | virtual void claimMemoryNeeds() {} | |
ea2cdeb6 | 56 | |
21b7990f AR |
57 | /// Called after claimMemoryNeeds(). |
58 | /// Meant for activating modules and features using a finalized | |
59 | /// configuration with known memory requirements. | |
60 | virtual void useConfig() {} | |
61f3a07b | 61 | |
21b7990f | 62 | /* Reconfiguration events */ |
61f3a07b | 63 | |
ee58de20 AJ |
64 | /// Called after receiving a reconfigure request and before parsing squid.conf. |
65 | /// Meant for modules that need to prepare for their configuration being changed | |
66 | /// [outside their control]. The changes end with the syncConfig() event. | |
67 | virtual void startReconfigure() {} | |
68 | ||
21b7990f AR |
69 | /// Called after parsing squid.conf during reconfiguration. |
70 | /// Meant for adjusting the module state based on configuration changes. | |
71 | virtual void syncConfig() {} | |
72 | ||
73 | /* Shutdown events */ | |
74 | ||
75 | /// Called after receiving a shutdown request and before stopping the main | |
76 | /// loop. At least one main loop iteration is guaranteed after this call. | |
77 | /// Meant for cleanup and state saving that may require other modules. | |
78 | virtual void startShutdown() {} | |
79 | ||
d442618d AJ |
80 | /// Called after shutdown_lifetime grace period ends and before stopping |
81 | /// the main loop. At least one main loop iteration is guaranteed after | |
82 | /// this call. | |
83 | /// Meant for cleanup and state saving that may require other modules. | |
84 | virtual void endingShutdown() {} | |
85 | ||
553d498c | 86 | /// Called after stopping the main loop and before releasing memory. |
21b7990f | 87 | /// Meant for quick/basic cleanup that does not require any other modules. |
61f3a07b | 88 | virtual ~RegisteredRunner() {} |
a27fcaed CT |
89 | |
90 | /// Meant for cleanup of services needed by the already destroyed objects. | |
91 | virtual void finishShutdown() {} | |
21b7990f AR |
92 | |
93 | /// a pointer to one of the above notification methods | |
94 | typedef void (RegisteredRunner::*Method)(); | |
61f3a07b | 95 | |
61f3a07b AR |
96 | }; |
97 | ||
a27fcaed CT |
98 | /// registers a given runner with the given registry and returns true on success |
99 | bool RegisterRunner(RegisteredRunner *rr); | |
d442618d | 100 | |
21b7990f AR |
101 | /// Calls a given method of all runners. |
102 | /// All runners are destroyed after the finishShutdown() call. | |
103 | void RunRegistered(const RegisteredRunner::Method &m); | |
61f3a07b | 104 | |
a27fcaed CT |
105 | /// A RegisteredRunner with lifetime determined by forces outside the Registry. |
106 | class IndependentRunner: public RegisteredRunner | |
107 | { | |
108 | public: | |
337b9aa4 | 109 | ~IndependentRunner() override { unregisterRunner(); } |
a27fcaed CT |
110 | |
111 | protected: | |
b856803f | 112 | void registerRunner(); |
a27fcaed CT |
113 | void unregisterRunner(); ///< unregisters self; safe to call multiple times |
114 | }; | |
115 | ||
21b7990f AR |
116 | /// convenience macro to describe/debug the caller and the method being called |
117 | #define RunRegisteredHere(m) \ | |
118 | debugs(1, 2, "running " # m); \ | |
119 | RunRegistered(&m) | |
61f3a07b | 120 | |
230d4410 AR |
121 | /// helps DefineRunnerRegistrator() and CallRunnerRegistrator() (and their |
122 | /// namespace-sensitive variants) to use the same registration function name | |
123 | #define NameRunnerRegistrator_(Namespace, ClassName) \ | |
124 | Register ## ClassName ## In ## Namespace() | |
125 | ||
126 | /// helper macro that implements DefineRunnerRegistrator() and | |
127 | /// DefineRunnerRegistratorIn() using supplied constructor expression | |
128 | #define DefineRunnerRegistrator_(Namespace, ClassName, Constructor) \ | |
129 | void NameRunnerRegistrator_(Namespace, ClassName); \ | |
130 | void NameRunnerRegistrator_(Namespace, ClassName) { \ | |
131 | const auto registered = RegisterRunner(new Constructor); \ | |
132 | assert(registered); \ | |
133 | } | |
134 | ||
135 | /// Define registration code for the given RegisteredRunner-derived class known | |
136 | /// as ClassName in Namespace. A matching CallRunnerRegistratorIn() call should | |
137 | /// run this code before any possible use of the being-registered module. | |
138 | /// \sa DefineRunnerRegistrator() for classes declared in the global namespace. | |
139 | #define DefineRunnerRegistratorIn(Namespace, ClassName) \ | |
140 | DefineRunnerRegistrator_(Namespace, ClassName, Namespace::ClassName) | |
141 | ||
142 | /// Define registration code for the given RegisteredRunner-derived class known | |
143 | /// as ClassName (in global namespace). A matching CallRunnerRegistrator() call | |
144 | /// should run this code before any possible use of the being-registered module. | |
145 | /// \sa DefineRunnerRegistratorIn() for classes declared in named namespaces. | |
146 | #define DefineRunnerRegistrator(ClassName) \ | |
147 | DefineRunnerRegistrator_(Global, ClassName, ClassName) | |
148 | ||
149 | /// Register one RegisteredRunner kid, known as ClassName in Namespace. | |
150 | /// \sa CallRunnerRegistrator() for classes declared in the global namespace. | |
151 | #define CallRunnerRegistratorIn(Namespace, ClassName) \ | |
152 | do { \ | |
153 | void NameRunnerRegistrator_(Namespace, ClassName); \ | |
154 | NameRunnerRegistrator_(Namespace, ClassName); \ | |
155 | } while (false) | |
156 | ||
157 | /// Register one RegisteredRunner kid, known as ClassName (in the global namespace). | |
158 | /// \sa CallRunnerRegistratorIn() for classes declared in named namespaces. | |
159 | #define CallRunnerRegistrator(ClassName) \ | |
160 | CallRunnerRegistratorIn(Global, ClassName) | |
61f3a07b | 161 | |
ff9d9458 | 162 | #endif /* SQUID_SRC_BASE_RUNNERSREGISTRY_H */ |
f53969cc | 163 |