src/pconn.h

   1 /*
   2  * Copyright (C) 1996-2025 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_PCONN_H
  10 #define SQUID_SRC_PCONN_H
  11
  12 #include "base/CbcPointer.h"
  13 #include "base/RunnersRegistry.h"
  14 #include "mgr/forward.h"
  15
  16 #include <set>
  17 #include <iosfwd>
  18
  19 /**
  20  \defgroup PConnAPI Persistent Connection API
  21  \ingroup Component
  22  */
  23
  24 class PconnPool;
  25 class PeerPoolMgr;
  26
  27 #include "cbdata.h"
  28 #include "hash.h"
  29 /* for IOCB */
  30 #include "comm.h"
  31
  32 /// \ingroup PConnAPI
  33 #define PCONN_HIST_SZ (1<<16)
  34
  35 /** \ingroup PConnAPI
  36  * A list of connections currently open to a particular destination end-point.
  37  */
  38 class IdleConnList: public hash_link, private IndependentRunner
  39 {
  40     CBDATA_CLASS(IdleConnList);
  41
  42 public:
  43     IdleConnList(const char *key, PconnPool *parent);
  44     ~IdleConnList() override;
  45
  46     /// Pass control of the connection to the idle list.
  47     void push(const Comm::ConnectionPointer &conn);
  48
  49     /// get first conn which is not pending read fd.
  50     Comm::ConnectionPointer pop();
  51
  52     /** Search the list for a connection which matches the 'key' details
  53      * and pop it off the list.
  54      * The list is created based on remote IP:port hash. This further filters
  55      * the choices based on specific local-end details requested.
  56      * If nothing usable is found the a nil pointer is returned.
  57      */
  58     Comm::ConnectionPointer findUseable(const Comm::ConnectionPointer &key);
  59
  60     void clearHandlers(const Comm::ConnectionPointer &conn);
  61
  62     // TODO: Upgrade to return size_t
  63     int count() const { return size_; }
  64
  65     void closeN(size_t count);
  66
  67     // IndependentRunner API
  68     void endingShutdown() override;
  69 private:
  70     bool isAvailable(int i) const;
  71     bool removeAt(size_t index);
  72     int findIndexOf(const Comm::ConnectionPointer &conn) const;
  73     void findAndClose(const Comm::ConnectionPointer &conn);
  74     static IOCB Read;
  75     static CTCB Timeout;
  76
  77 private:
  78     /** List of connections we are holding.
  79      * Sorted as FIFO list for most efficient speeds on pop() and findUsable()
  80      * The worst-case pop() and scans occur on timeout and link closure events
  81      * where timing is less critical. Occasional slow additions are okay.
  82      */
  83     Comm::ConnectionPointer *theList_;
  84
  85     /// Number of entries theList can currently hold without re-allocating (capacity).
  86     size_t capacity_;
  87     ///< Number of in-use entries in theList
  88     size_t size_;
  89
  90     /** The pool containing this sub-list.
  91      * The parent performs all stats accounting, and
  92      * will delete us when it dies. It persists for the
  93      * full duration of our existence.
  94      */
  95     PconnPool *parent_;
  96
  97     char fakeReadBuf_[4096]; // TODO: kill magic number.
  98 };
  99
 100 #include "ip/forward.h"
 101
 102 class StoreEntry;
 103 class IdleConnLimit;
 104
 105 /* for hash_table */
 106 #include "hash.h"
 107
 108 /** \ingroup PConnAPI
 109  * Manages idle persistent connections to a caller-defined set of
 110  * servers (e.g., all HTTP servers). Uses a collection of IdleConnLists
 111  * internally to list the individual open connections to each server.
 112  * Controls lists existence and limits the total number of
 113  * idle connections across the collection.
 114  */
 115 class PconnPool
 116 {
 117
 118 public:
 119     PconnPool(const char *aDescription, const CbcPointer<PeerPoolMgr> &aMgr);
 120     ~PconnPool();
 121
 122     void moduleInit();
 123     void push(const Comm::ConnectionPointer &serverConn, const char *domain);
 124
 125     /**
 126      * Returns either a pointer to a popped connection to dest or nil.
 127      * Closes the connection before returning its pointer unless keepOpen.
 128      * For connection going to a cache_peer, supports standby connection pools.
 129      *
 130      * A caller with a non-retriable transaction should set keepOpen to false
 131      * and call pop() anyway, even though the caller does not want a pconn.
 132      * This forces us to close an available persistent connection, avoiding
 133      * creating a growing number of open connections when many transactions
 134      * create (and push) persistent connections but are not retriable and,
 135      * hence, do not need to pop a connection.
 136      */
 137     Comm::ConnectionPointer pop(const Comm::ConnectionPointer &dest, const char *domain, bool keepOpen);
 138     void count(int uses);
 139     void dump(std::ostream &) const;
 140     void unlinkList(IdleConnList *list);
 141     void noteUses(int uses);
 142     /// closes any n connections, regardless of their destination
 143     void closeN(int n);
 144     int count() const { return theCount; }
 145     void noteConnectionAdded() { ++theCount; }
 146     void noteConnectionRemoved() { assert(theCount > 0); --theCount; }
 147
 148     // sends an async message to the pool manager, if any
 149     void notifyManager(const char *reason);
 150
 151 private:
 152
 153     static const char *key(const Comm::ConnectionPointer &destLink, const char *domain);
 154
 155     Comm::ConnectionPointer popStored(const Comm::ConnectionPointer &dest, const char *domain, const bool keepOpen);
 156     void dumpHist(std::ostream &) const;
 157     void dumpHash(std::ostream &) const;
 158
 159     int hist[PCONN_HIST_SZ];
 160     hash_table *table;
 161     const char *descr;
 162     CbcPointer<PeerPoolMgr> mgr; ///< optional pool manager (for notifications)
 163     int theCount; ///< the number of pooled connections
 164 };
 165
 166 class StoreEntry;
 167 class PconnPool;
 168
 169 /** \ingroup PConnAPI
 170  * The global registry of persistent connection pools.
 171  */
 172 class PconnModule
 173 {
 174
 175 public:
 176     /** the module is a singleton until we have instance based cachemanager
 177      * management
 178      */
 179     static PconnModule * GetInstance();
 180     /** A thunk to the still C like CacheManager callback api. */
 181     static void DumpWrapper(StoreEntry *e);
 182
 183     PconnModule();
 184     void registerWithCacheManager(void);
 185
 186     void add(PconnPool *);
 187     void remove(PconnPool *); ///< unregister and forget about this pool object
 188
 189     void dump(std::ostream &yaml);
 190
 191 private:
 192     typedef std::set<PconnPool*> Pools; ///< unordered PconnPool collection
 193     Pools pools; ///< all live pools
 194
 195     static PconnModule * instance;
 196 };
 197
 198 #endif /* SQUID_SRC_PCONN_H */
 199