helper.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2021 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 /* DEBUG: section 84 Helper process maintenance */
10 
11 #ifndef SQUID_HELPER_H
12 #define SQUID_HELPER_H
13 
14 #include "base/AsyncCall.h"
15 #include "base/InstanceId.h"
16 #include "cbdata.h"
17 #include "comm/forward.h"
18 #include "dlink.h"
19 #include "helper/ChildConfig.h"
20 #include "helper/forward.h"
21 #include "helper/Reply.h"
22 #include "helper/Request.h"
23 #include "helper/ReservationId.h"
24 #include "ip/Address.h"
25 #include "sbuf/SBuf.h"
26 
27 #include <list>
28 #include <map>
29 #include <queue>
30 #include <unordered_map>
31 
32 class Packable;
33 class wordlist;
34 
35 namespace Helper
36 {
38 class Xaction {
40 public:
41  Xaction(HLPCB *c, void *d, const char *b): request(c, d, b) {}
44 };
45 }
46 
47 class HelperServerBase;
63 class helper
64 {
66 
67 public:
69  inline helper(const char *name) :
70  cmdline(NULL),
71  id_name(name),
72  ipc_type(0),
73  droppedRequests(0),
74  overloadStart(0),
75  last_queue_warn(0),
76  last_restart(0),
77  timeout(0),
80  eom('\n') {
81  memset(&stats, 0, sizeof(stats));
82  }
83  ~helper();
84 
87 
89  bool trySubmit(const char *buf, HLPCB * callback, void *data);
90 
94 
96  void packStatsInto(Packable *p, const char *label = NULL) const;
99  bool willOverload() const;
100 
104  void handleKilledServer(HelperServerBase *srv, bool &needsNewServers);
105 
106 public:
109  std::queue<Helper::Xaction *> queue;
110  const char *id_name;
112  int ipc_type;
114  unsigned int droppedRequests;
115  time_t overloadStart;
117  time_t last_restart;
118  time_t timeout;
122  char eom;
123 
124  struct _stats {
125  int requests;
126  int replies;
127  int timedout;
130  } stats;
131 
132 protected:
133  friend void helperSubmit(helper * hlp, const char *buf, HLPCB * callback, void *data);
134  bool queueFull() const;
135  bool overloaded() const;
136  void syncQueueStats();
137  bool prepSubmit();
138  void submit(const char *buf, HLPCB * callback, void *data);
139 };
140 
141 class statefulhelper : public helper
142 {
144 
145 public:
146  typedef std::unordered_map<Helper::ReservationId, helper_stateful_server *> Reservations;
147 
148  inline statefulhelper(const char *name) : helper(name) {}
149  inline ~statefulhelper() {}
150 
151 public:
154 
156  void cancelReservation(const Helper::ReservationId reservation);
157 
158 private:
159  friend void helperStatefulSubmit(statefulhelper * hlp, const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
160 
163 
164  void submit(const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
165  bool trySubmit(const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
166 
169 };
170 
173 {
174 public:
175  virtual ~HelperServerBase();
181  void closePipesSafely(const char *name);
182 
189  void closeWritePipeSafely(const char *name);
190 
191  // TODO: Teach each child to report its child-specific state instead.
193  virtual bool reserved() = 0;
194 
196  virtual void dropQueued();
197 
199  virtual helper *getParent() const = 0;
200 
201 public:
205  int pid;
209  void *hIpc;
210 
211  char *rbuf;
212  size_t rbuf_sz;
213  size_t roffset;
214 
215  struct timeval dispatch_time;
216  struct timeval answer_time;
217 
219 
220  struct _helper_flags {
221  bool writing;
222  bool closing;
223  bool shutdown;
224  } flags;
225 
226  typedef std::list<Helper::Xaction *> Requests;
228 
229  struct {
230  uint64_t uses; //< requests sent to this helper
231  uint64_t replies; //< replies received from this helper
232  uint64_t pending; //< queued lookups waiting to be sent to this helper
233  uint64_t releases; //< times release() has been called on this helper (if stateful)
234  uint64_t timedout; //< requests which timed-out
235  } stats;
236  void initStats();
237 };
238 
239 class MemBuf;
240 class CommTimeoutCbParams;
241 
242 // TODO: Rename to StatelessHelperServer and rename HelperServerBase to HelperServer.
245 {
247 
248 public:
249  uint64_t nextRequestId;
250 
253 
255 
261 
264 
265  // STL says storing std::list iterators is safe when changing the list
266  typedef std::map<uint64_t, Requests::iterator> RequestIndex;
268 
269  virtual ~helper_server();
274  Helper::Xaction *popRequest(int requestId);
275 
278  void checkForTimedOutRequests(bool const retry);
279 
280  /*HelperServerBase API*/
281  virtual bool reserved() override {return false;}
282  virtual void dropQueued() override;
283  virtual helper *getParent() const override {return parent;}
284 
286  static void requestTimeout(const CommTimeoutCbParams &io);
287 
289  static void HelperServerClosed(helper_server *srv);
290 };
291 
292 // TODO: Rename to StatefulHelperServer and rename HelperServerBase to HelperServer.
295 {
297 
298 public:
299  virtual ~helper_stateful_server();
300  void reserve();
301  void clearReservation();
302 
303  /* HelperServerBase API */
304  virtual bool reserved() override {return reservationId.reserved();}
305  virtual helper *getParent() const override {return parent;}
306 
308  static void HelperServerClosed(helper_stateful_server *srv);
309 
311 
312  // Reservations temporary lock the server for an exclusive "client" use. The
313  // client keeps the reservation ID as a proof of her reservation. If a
314  // reservation expires, and the server is reserved for another client, then
315  // the reservation ID presented by the late client will not match ours.
318 };
319 
320 /* helper.c */
321 void helperOpenServers(helper * hlp);
323 void helperSubmit(helper * hlp, const char *buf, HLPCB * callback, void *data);
324 void helperStatefulSubmit(statefulhelper * hlp, const char *buf, HLPCB * callback, void *data, uint64_t reservation);
325 void helperShutdown(helper * hlp);
327 
328 #endif /* SQUID_HELPER_H */
329 
virtual helper * getParent() const override
the helper object that created this server
Definition: helper.h:283
std::list< Helper::Xaction * > Requests
Definition: helper.h:226
void closePipesSafely(const char *name)
Definition: helper.cc:74
dlink_node link
Definition: helper.h:218
time_t reservationStart
when the last reservation was made
Definition: helper.h:317
void submitRequest(Helper::Xaction *r)
Definition: helper.cc:446
Helper::ChildConfig childs
Configuration settings for number running.
Definition: helper.h:111
void syncQueueStats()
synchronizes queue-dependent measurements with the current queue state
Definition: helper.cc:492
represents a single "stateless helper" process
Definition: helper.h:245
wordlist * cmdline
Definition: helper.h:107
dlink_list servers
Definition: helper.h:108
statefulhelper(const char *name)
Definition: helper.h:148
bool reserved() const
Definition: ReservationId.h:22
void helperStatefulOpenServers(statefulhelper *hlp)
Definition: helper.cc:332
helper_stateful_server * findServer(const Helper::ReservationId &reservation)
Definition: helper.cc:614
struct helper::_stats stats
statefulhelper * parent
Definition: helper.h:310
virtual ~helper_stateful_server()
Definition: helper.cc:182
virtual ~helper_server()
Definition: helper.cc:152
virtual void dropQueued()
dequeues and sends a Helper::Unknown answer to all queued requests
Definition: helper.cc:128
struct HelperServerBase::_helper_flags flags
friend void helperStatefulSubmit(statefulhelper *hlp, const char *buf, HLPCB *callback, void *data, const Helper::ReservationId &reservation)
Definition: helper.cc:567
uint64_t timedout
Definition: helper.h:234
const InstanceId< HelperServerBase > index
Definition: helper.h:204
int avg_svc_time
Definition: helper.h:129
#define CBDATA_CLASS(type)
Definition: cbdata.h:302
int ipc_type
Definition: helper.h:112
Definition: SBuf.h:87
void submit(const char *buf, HLPCB *callback, void *data)
dispatches or enqueues a helper requests; does not enforce queue limits
Definition: helper.cc:557
static void requestTimeout(const CommTimeoutCbParams &io)
Read timeout handler.
Definition: helper.cc:1556
time_t last_queue_warn
Definition: helper.h:116
static void HelperServerClosed(helper_stateful_server *srv)
close handler to handle exited server processes
Definition: helper.cc:876
std::queue< Helper::Xaction * > queue
Definition: helper.h:109
virtual bool reserved() override
whether the server is locked for exclusive use by a client
Definition: helper.h:281
virtual bool reserved() override
whether the server is locked for exclusive use by a client
Definition: helper.h:304
helper(const char *name)
Definition: helper.h:69
Helper::Reply reply
Definition: helper.h:43
struct timeval dispatch_time
Definition: helper.h:215
virtual void dropQueued() override
dequeues and sends a Helper::Unknown answer to all queued requests
Definition: helper.cc:176
CBDATA_CHILD(helper_stateful_server)
Xaction(HLPCB *c, void *d, const char *b)
Definition: helper.h:41
std::unordered_map< Helper::ReservationId, helper_stateful_server * > Reservations
Definition: helper.h:143
static void HelperServerClosed(helper_server *srv)
close handler to handle exited server processes
Definition: helper.cc:857
uint64_t uses
Definition: helper.h:230
void submit(const char *buf, HLPCB *callback, void *data, const Helper::ReservationId &reservation)
Definition: helper.cc:645
Requests requests
requests in order of submission/expiration
Definition: helper.h:227
void cancelReservation(const Helper::ReservationId reservation)
undo reserveServer(), clear the reservation and kick the queue
Definition: helper.cc:598
time_t last_restart
Definition: helper.h:117
uint64_t releases
Definition: helper.h:233
void helperStatefulSubmit(statefulhelper *hlp, const char *buf, HLPCB *callback, void *data, uint64_t reservation)
void reserveServer(helper_stateful_server *srv)
reserve the given server
Definition: helper.cc:585
void * hIpc
Definition: helper.h:209
int timedout
Definition: helper.h:127
#define NULL
Definition: types.h:166
struct HelperServerBase::@73 stats
void helperShutdown(helper *hlp)
Definition: helper.cc:740
bool overloaded() const
Definition: helper.cc:486
represents a single helper process abstraction
Definition: helper.h:173
MemBuf * wqueue
Definition: helper.h:251
unsigned int droppedRequests
requests not sent during helper overload
Definition: helper.h:114
Definition: MemBuf.h:24
Definition: helper.h:64
void helperStatefulShutdown(statefulhelper *hlp)
Definition: helper.cc:777
uint64_t pending
Definition: helper.h:232
std::map< uint64_t, Requests::iterator > RequestIndex
Definition: helper.h:266
struct timeval answer_time
Definition: helper.h:216
Ip::Address addr
Definition: helper.h:206
int requests
Definition: helper.h:125
bool willOverload() const
Definition: helper.cc:735
bool retryTimedOut
Whether the timed-out requests must retried.
Definition: helper.h:119
~helper()
Definition: helper.cc:823
a (temporary) lock on a (stateful) helper channel
Definition: ReservationId.h:18
RequestIndex requestsIndex
maps request IDs to requests
Definition: helper.h:267
helper protocol primitives
Definition: ChildConfig.h:13
void packStatsInto(Packable *p, const char *label=NULL) const
Dump some stats about the helper state to a Packable object.
Definition: helper.cc:677
time_t overloadStart
when the helper became overloaded (zero if it is not)
Definition: helper.h:115
Comm::ConnectionPointer writePipe
Definition: helper.h:208
bool retryBrokenHelper
Whether the requests must retried on BH replies.
Definition: helper.h:120
const char * id_name
Definition: helper.h:110
uint64_t replies
Definition: helper.h:231
friend void helperSubmit(helper *hlp, const char *buf, HLPCB *callback, void *data)
Definition: helper.cc:473
size_t roffset
Definition: helper.h:213
MemBuf * writebuf
Definition: helper.h:252
CBDATA_CHILD(helper_server)
represents a single "stateful helper" process
Definition: helper.h:295
Helper::Xaction * popRequest(int requestId)
Definition: helper.cc:893
Helper::Xaction * nextRequest()
Definition: helper.cc:1261
char * rbuf
Definition: helper.h:211
void handleKilledServer(HelperServerBase *srv, bool &needsNewServers)
Definition: helper.cc:833
bool trySubmit(const char *buf, HLPCB *callback, void *data, const Helper::ReservationId &reservation)
reserved servers indexed by reservation IDs
Definition: helper.cc:575
size_t rbuf_sz
Definition: helper.h:212
void initStats()
Definition: helper.cc:64
~statefulhelper()
Definition: helper.h:149
SBuf onTimedOutResponse
The response to use when helper response timedout.
Definition: helper.h:121
virtual ~HelperServerBase()
Definition: helper.cc:144
virtual helper * getParent() const =0
the helper object that created this server
helper * parent
Definition: helper.h:254
Helper::Xaction * replyXaction
Definition: helper.h:260
void helperSubmit(helper *hlp, const char *buf, HLPCB *callback, void *data)
Definition: helper.cc:473
bool queueFull() const
whether queuing an additional request would overload the helper
Definition: helper.cc:481
Helper::Request request
Definition: helper.h:42
virtual bool reserved()=0
whether the server is locked for exclusive use by a client
void HLPCB(void *, const Helper::Reply &)
Definition: forward.h:27
MEMPROXY_CLASS(Helper::Xaction)
bool ignoreToEom
Whether to ignore current message, because it is timed-out or other reason.
Definition: helper.h:263
Ip::Address addr
Definition: helper.h:113
int queue_size
Definition: helper.h:128
bool trySubmit(const char *buf, HLPCB *callback, void *data)
If possible, submit request. Otherwise, either kill Squid or return false.
Definition: helper.cc:546
#define false
Definition: GnuRegex.c:233
void closeWritePipeSafely(const char *name)
Definition: helper.cc:102
time_t timeout
Requests timeout.
Definition: helper.h:118
bool prepSubmit()
Definition: helper.cc:519
Helper::ReservationId reservationId
"confirmation ID" of the last
Definition: helper.h:316
void helperOpenServers(helper *hlp)
Definition: helper.cc:201
void checkForTimedOutRequests(bool const retry)
Definition: helper.cc:1517
virtual helper * getParent() const override
the helper object that created this server
Definition: helper.h:305
char eom
The char which marks the end of (response) message, normally ' '.
Definition: helper.h:122
Reservations reservations
Definition: helper.h:168
uint64_t nextRequestId
Definition: helper.h:249
Comm::ConnectionPointer readPipe
Definition: helper.h:207
Holds the required data to serve a helper request.
Definition: helper.h:38

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors