src/adaptation/icap/ServiceRep.h

   1
   2 /*
   3  *
   4  * SQUID Web Proxy Cache          http://www.squid-cache.org/
   5  * ----------------------------------------------------------
   6  *
   7  *  Squid is the result of efforts by numerous individuals from
   8  *  the Internet community; see the CONTRIBUTORS file for full
   9  *  details.   Many organizations have provided support for Squid's
  10  *  development; see the SPONSORS file for full details.  Squid is
  11  *  Copyrighted (C) 2001 by the Regents of the University of
  12  *  California; see the COPYRIGHT file for full details.  Squid
  13  *  incorporates software developed and/or copyrighted by other
  14  *  sources; see the CREDITS file for full details.
  15  *
  16  *  This program is free software; you can redistribute it and/or modify
  17  *  it under the terms of the GNU General Public License as published by
  18  *  the Free Software Foundation; either version 2 of the License, or
  19  *  (at your option) any later version.
  20  *
  21  *  This program is distributed in the hope that it will be useful,
  22  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  23  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  24  *  GNU General Public License for more details.
  25  *
  26  *  You should have received a copy of the GNU General Public License
  27  *  along with this program; if not, write to the Free Software
  28  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  29  *
  30  */
  31
  32 #ifndef SQUID_ICAPSERVICEREP_H
  33 #define SQUID_ICAPSERVICEREP_H
  34
  35 #include "adaptation/forward.h"
  36 #include "adaptation/icap/Elements.h"
  37 #include "adaptation/Initiator.h"
  38 #include "adaptation/Service.h"
  39 #include "base/AsyncJobCalls.h"
  40 #include "cbdata.h"
  41 #include "comm.h"
  42 #include "FadingCounter.h"
  43 #include "pconn.h"
  44 #include <deque>
  45
  46 namespace Adaptation
  47 {
  48 namespace Icap
  49 {
  50
  51 class Options;
  52 class OptXact;
  53
  54 /* The ICAP service representative maintains information about a single ICAP
  55    service that Squid communicates with. The representative initiates OPTIONS
  56    requests to the service to keep cached options fresh. One ICAP server may
  57    host many ICAP services. */
  58
  59 /*
  60  * A service with a fresh cached OPTIONS response and without many failures
  61  * is an "up" service. All other services are "down". A service is "probed"
  62  * if we tried to get an OPTIONS response from it and succeeded or failed.
  63  * A probed down service is called "broken".
  64  *
  65  * The number of failures required to bring an up service down is determined
  66  * by icap_service_failure_limit in squid.conf.
  67  *
  68  * As a bootstrapping mechanism, ICAP transactions wait for an unprobed
  69  * service to get a fresh OPTIONS response (see the callWhenReady method).
  70  * The waiting callback is called when the OPTIONS transaction completes,
  71  * even if the service is now broken.
  72  *
  73  * We do not initiate ICAP transactions with a broken service, but will
  74  * eventually retry to fetch its options in hope to bring the service up.
  75  *
  76  * A service that should no longer be used after Squid reconfiguration is
  77  * treated as if it does not have a fresh cached OPTIONS response. We do
  78  * not try to fetch fresh options for such a service. It should be
  79  * auto-destroyed by refcounting when no longer used.
  80  */
  81
  82 class ServiceRep : public RefCountable, public Adaptation::Service,
  83         public Adaptation::Initiator
  84 {
  85
  86 public:
  87     typedef RefCount<ServiceRep> Pointer;
  88
  89 public:
  90     explicit ServiceRep(const ServiceConfigPointer &aConfig);
  91     virtual ~ServiceRep();
  92
  93     virtual void finalize();
  94
  95     virtual bool probed() const; // see comments above
  96     virtual bool up() const; // see comments above
  97     bool availableForNew() const; ///< a new transaction may start communicating with the service
  98     bool availableForOld() const; ///< a transaction notified about connection slot availability may start communicating with the service
  99
 100     virtual Initiate *makeXactLauncher(HttpMsg *virginHeader, HttpRequest *virginCause, AccessLogEntry::Pointer &alp);
 101
 102     void callWhenAvailable(AsyncCall::Pointer &cb, bool priority = false);
 103     void callWhenReady(AsyncCall::Pointer &cb);
 104
 105     // the methods below can only be called on an up() service
 106     bool wantsUrl(const String &urlPath) const;
 107     bool wantsPreview(const String &urlPath, size_t &wantedSize) const;
 108     bool allows204() const;
 109     bool allows206() const;
 110     Comm::ConnectionPointer getConnection(bool isRetriable, bool &isReused);
 111     void putConnection(const Comm::ConnectionPointer &conn, bool isReusable, bool sendReset, const char *comment);
 112     void noteConnectionUse(const Comm::ConnectionPointer &conn);
 113     void noteConnectionFailed(const char *comment);
 114
 115     void noteFailure(); // called by transactions to report service failure
 116
 117     void noteNewWaiter() {theAllWaiters++;} ///< New xaction waiting for service to be up or available
 118     void noteGoneWaiter(); ///< An xaction is not waiting any more for service to be available
 119     bool existWaiters() const {return (theAllWaiters > 0);} ///< if there are xactions waiting for the service to be available
 120
 121     //AsyncJob virtual methods
 122     virtual bool doneAll() const { return Adaptation::Initiator::doneAll() && false;}
 123     virtual void callException(const std::exception &e);
 124
 125     virtual void detach();
 126     virtual bool detached() const;
 127
 128 public: // treat these as private, they are for callbacks only
 129     void noteTimeToUpdate();
 130     void noteTimeToNotify();
 131
 132     // receive either an ICAP OPTIONS response header or an abort message
 133     virtual void noteAdaptationAnswer(const Answer &answer);
 134
 135 private:
 136     // stores Prepare() callback info
 137
 138     struct Client {
 139         Pointer service; // one for each client to preserve service
 140         AsyncCall::Pointer callback;
 141     };
 142
 143     typedef Vector<Client> Clients;
 144     // TODO: rename to theUpWaiters
 145     Clients theClients; // all clients waiting for a call back
 146
 147     Options *theOptions;
 148     CbcPointer<Adaptation::Initiate> theOptionsFetcher; // pending ICAP OPTIONS transaction
 149     time_t theLastUpdate; // time the options were last updated
 150
 151     /// FIFO queue of xactions waiting for a connection slot and not yet notified
 152     /// about it; xaction is removed when notification is scheduled
 153     std::deque<Client> theNotificationWaiters;
 154     int theBusyConns;   ///< number of connections given to active transactions
 155     /// number of xactions waiting for a connection slot (notified and not)
 156     /// the number is decreased after the xaction receives notification
 157     int theAllWaiters;
 158     int theMaxConnections; ///< the maximum allowed connections to the service
 159     // TODO: use a better type like the FadingCounter for connOverloadReported
 160     mutable bool connOverloadReported; ///< whether we reported exceeding theMaxConnections
 161     IdleConnList *theIdleConns; ///< idle persistent connection pool
 162
 163     FadingCounter theSessionFailures;
 164     const char *isSuspended; // also stores suspension reason for debugging
 165
 166     bool notifying; // may be true in any state except for the initial
 167     bool updateScheduled; // time-based options update has been scheduled
 168
 169 private:
 170     ICAP::Method parseMethod(const char *) const;
 171     ICAP::VectPoint parseVectPoint(const char *) const;
 172
 173     void suspend(const char *reason);
 174
 175     bool hasOptions() const;
 176     bool needNewOptions() const;
 177     time_t optionsFetchTime() const;
 178
 179     void scheduleUpdate(time_t when);
 180     void scheduleNotification();
 181
 182     void startGettingOptions();
 183     void handleNewOptions(Options *newOptions);
 184     void changeOptions(Options *newOptions);
 185     void checkOptions();
 186
 187     void announceStatusChange(const char *downPhrase, bool important) const;
 188
 189     /// Set the maximum allowed connections for the service
 190     void setMaxConnections();
 191     /// The number of connections which excess the Max-Connections limit
 192     int excessConnections() const;
 193     /**
 194      * The available connections slots to the ICAP server
 195      \return the available slots, or -1 if there is no limit on allowed connections
 196      */
 197     int availableConnections() const;
 198     /**
 199      * If there are xactions waiting for the service to be available, notify
 200      * as many xactions as the available connections slots.
 201      */
 202     void busyCheckpoint();
 203
 204     const char *status() const;
 205
 206     mutable bool wasAnnouncedUp; // prevent sequential same-state announcements
 207     bool isDetached;
 208     CBDATA_CLASS2(ServiceRep);
 209 };
 210
 211 class ModXact;
 212 /// Custom dialer to call Service::noteNewWaiter and noteGoneWaiter
 213 /// to maintain Service idea of waiting and being-notified transactions.
 214 class ConnWaiterDialer: public NullaryMemFunT<ModXact>
 215 {
 216 public:
 217     typedef NullaryMemFunT<ModXact> Parent;
 218     ServiceRep::Pointer theService;
 219     ConnWaiterDialer(const CbcPointer<ModXact> &xact, Parent::Method aHandler);
 220     ConnWaiterDialer(const Adaptation::Icap::ConnWaiterDialer &aConnWaiter);
 221     ~ConnWaiterDialer();
 222 };
 223
 224 } // namespace Icap
 225 } // namespace Adaptation
 226
 227 #endif /* SQUID_ICAPSERVICEREP_H */