src/base/RunnersRegistry.h

   1 /*
   2  * Copyright (C) 1996-2015 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_BASE_RUNNERSREGISTRY_H
  10 #define SQUID_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 after parsing squid.conf.
  45     /// Meant for setting configuration options that depend on other
  46     /// configuration options and were not explicitly configured.
  47     virtual void finalizeConfig() {}
  48
  49     /// Called after finalizeConfig().
  50     /// Meant for announcing memory reservations before memory is allocated.
  51     virtual void claimMemoryNeeds() {}
  52
  53     /// Called after claimMemoryNeeds().
  54     /// Meant for activating modules and features using a finalized
  55     /// configuration with known memory requirements.
  56     virtual void useConfig() {}
  57
  58     /* Reconfiguration events */
  59
  60     /// Called after parsing squid.conf during reconfiguration.
  61     /// Meant for adjusting the module state based on configuration changes.
  62     virtual void syncConfig() {}
  63
  64     /* Shutdown events */
  65
  66     /// Called after receiving a shutdown request and before stopping the main
  67     /// loop. At least one main loop iteration is guaranteed after this call.
  68     /// Meant for cleanup and state saving that may require other modules.
  69     virtual void startShutdown() {}
  70
  71     /// Called after stopping the main loop and before releasing memory.
  72     /// Meant for quick/basic cleanup that does not require any other modules.
  73     virtual ~RegisteredRunner() {}
  74     /// exists to simplify caller interface; override the destructor instead
  75     void finishShutdown() { delete this; }
  76
  77     /// a pointer to one of the above notification methods
  78     typedef void (RegisteredRunner::*Method)();
  79
  80 };
  81
  82 /// registers a given runner with the given registry and returns registry count
  83 int RegisterRunner(RegisteredRunner *rr);
  84
  85 /// Calls a given method of all runners.
  86 /// All runners are destroyed after the finishShutdown() call.
  87 void RunRegistered(const RegisteredRunner::Method &m);
  88
  89 /// convenience macro to describe/debug the caller and the method being called
  90 #define RunRegisteredHere(m) \
  91     debugs(1, 2, "running " # m); \
  92     RunRegistered(&m)
  93
  94 /// convenience function to "use" an otherwise unreferenced static variable
  95 bool UseThisStatic(const void *);
  96
  97 /// convenience macro: register one RegisteredRunner kid as early as possible
  98 #define RunnerRegistrationEntry(Who) \
  99     static const bool Who ## _Registered_ = \
 100         RegisterRunner(new Who) > 0 && \
 101         UseThisStatic(& Who ## _Registered_);
 102
 103 #endif /* SQUID_BASE_RUNNERSREGISTRY_H */
 104