src/base/RunnersRegistry.h

   1 #ifndef SQUID_BASE_RUNNERSREGISTRY_H
   2 #define SQUID_BASE_RUNNERSREGISTRY_H
   3
   4 /**
   5  * This API allows virtually any module to register its interest in receiving
   6  * notification about initial configuration availability, configuration changes
   7  * and other critical events in Squid lifetime without exposing the notifier
   8  * to the details of the module.
   9  *
  10  * For example, main.cc may activate registered I/O modules after parsing
  11  * squid.conf and deactivate them before exiting, all without knowing what
  12  * those I/O modules really are.
  13  *
  14  * A module in this context is code providing a functionality or service to the
  15  * rest of Squid, such as src/DiskIO/Blocking, src/fs/ufs, or Cache Manager. To
  16  * receive notifications, a module must declare a RegisteredRunner child class
  17  * and implement the methods corresponding to the events the module is
  18  * interested in.
  19  *
  20  * The order of events is documented in this header (where applicable), but
  21  * the order in which runners are notified about a given event is undefined.
  22  * If a specific notification order is required, split the event into two or
  23  * more related event(s), documenting their relative order here.
  24  *
  25  */
  26
  27 /// a runnable registrant API
  28 /// kids must override [only] the methods they are interested in
  29 class RegisteredRunner
  30 {
  31 public:
  32     /* Related methods below are declared in their calling order */
  33
  34     /* Configuration events */
  35
  36     /// Called after parsing squid.conf.
  37     /// Meant for setting configuration options that depend on other
  38     /// configuration options and were not explicitly configured.
  39     virtual void finalizeConfig() {}
  40
  41     /// Called after finalizeConfig().
  42     /// Meant for announcing memory reservations before memory is allocated.
  43     virtual void claimMemoryNeeds() {}
  44
  45     /// Called after claimMemoryNeeds().
  46     /// Meant for activating modules and features using a finalized
  47     /// configuration with known memory requirements.
  48     virtual void useConfig() {}
  49
  50     /* Reconfiguration events */
  51
  52     /// Called after parsing squid.conf during reconfiguration.
  53     /// Meant for adjusting the module state based on configuration changes.
  54     virtual void syncConfig() {}
  55
  56     /* Shutdown events */
  57
  58     /// Called after receiving a shutdown request and before stopping the main
  59     /// loop. At least one main loop iteration is guaranteed after this call.
  60     /// Meant for cleanup and state saving that may require other modules.
  61     virtual void startShutdown() {}
  62
  63     /// Called after stopping the main loop.
  64     /// Meant for quick/basic cleanup that does not require any other modules.
  65     virtual ~RegisteredRunner() {}
  66     /// exists to simplify caller interface; override the destructor instead
  67     void finishShutdown() { delete this; }
  68
  69     /// a pointer to one of the above notification methods
  70     typedef void (RegisteredRunner::*Method)();
  71
  72 };
  73
  74 /// registers a given runner with the given registry and returns registry count
  75 int RegisterRunner(RegisteredRunner *rr);
  76
  77 /// Calls a given method of all runners.
  78 /// All runners are destroyed after the finishShutdown() call.
  79 void RunRegistered(const RegisteredRunner::Method &m);
  80
  81 /// convenience macro to describe/debug the caller and the method being called
  82 #define RunRegisteredHere(m) \
  83     debugs(1, 2, "running " # m); \
  84     RunRegistered(&m)
  85
  86 /// convenience function to "use" an otherwise unreferenced static variable
  87 bool UseThisStatic(const void *);
  88
  89 /// convenience macro: register one RegisteredRunner kid as early as possible
  90 #define RunnerRegistrationEntry(Who) \
  91     static const bool Who ## _Registered_ = \
  92         RegisterRunner(new Who) > 0 && \
  93         UseThisStatic(& Who ## _Registered_);
  94
  95 #endif /* SQUID_BASE_RUNNERSREGISTRY_H */