src/base/RunnersRegistry.h

   1 /*
   2  * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
   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
   9 #ifndef SQUID_SRC_BASE_RUNNERSREGISTRY_H
  10 #define SQUID_SRC_BASE_RUNNERSREGISTRY_H
  11
  12 /**
  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.
  17  *
  18  * For example, main.cc may activate registered I/O modules after parsing
  19  * squid.conf and deactivate them before exiting, all without knowing what
  20  * those I/O modules really are.
  21  *
  22  * A module in this context is code providing a functionality or service to the
  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.
  27  *
  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.
  32  *
  33  */
  34
  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
  44     /// Called right before parsing squid.conf.
  45     /// Meant for initializing/preparing configuration parsing facilities.
  46     virtual void bootstrapConfig() {}
  47
  48     /// Called after parsing squid.conf.
  49     /// Meant for setting configuration options that depend on other
  50     /// configuration options and were not explicitly configured.
  51     virtual void finalizeConfig() {}
  52
  53     /// Called after finalizeConfig().
  54     /// Meant for announcing memory reservations before memory is allocated.
  55     virtual void claimMemoryNeeds() {}
  56
  57     /// Called after claimMemoryNeeds().
  58     /// Meant for activating modules and features using a finalized
  59     /// configuration with known memory requirements.
  60     virtual void useConfig() {}
  61
  62     /* Reconfiguration events */
  63
  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
  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
  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
  86     /// Called after stopping the main loop and before releasing memory.
  87     /// Meant for quick/basic cleanup that does not require any other modules.
  88     virtual ~RegisteredRunner() {}
  89
  90     /// Meant for cleanup of services needed by the already destroyed objects.
  91     virtual void finishShutdown() {}
  92
  93     /// a pointer to one of the above notification methods
  94     typedef void (RegisteredRunner::*Method)();
  95
  96 };
  97
  98 /// registers a given runner with the given registry and returns true on success
  99 bool RegisterRunner(RegisteredRunner *rr);
 100
 101 /// Calls a given method of all runners.
 102 /// All runners are destroyed after the finishShutdown() call.
 103 void RunRegistered(const RegisteredRunner::Method &m);
 104
 105 /// A RegisteredRunner with lifetime determined by forces outside the Registry.
 106 class IndependentRunner: public RegisteredRunner
 107 {
 108 public:
 109     ~IndependentRunner() override { unregisterRunner(); }
 110
 111 protected:
 112     void registerRunner();
 113     void unregisterRunner(); ///< unregisters self; safe to call multiple times
 114 };
 115
 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)
 120
 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)
 161
 162 #endif /* SQUID_SRC_BASE_RUNNERSREGISTRY_H */
 163