helper.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2020 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:
68  inline helper(const char *name) :
69  cmdline(NULL),
70  id_name(name),
71  ipc_type(0),
72  droppedRequests(0),
73  overloadStart(0),
74  last_queue_warn(0),
75  last_restart(0),
76  timeout(0),
79  eom('\n') {
80  memset(&stats, 0, sizeof(stats));
81  }
82  ~helper();
83 
86 
88  bool trySubmit(const char *buf, HLPCB * callback, void *data);
89 
93 
95  void packStatsInto(Packable *p, const char *label = NULL) const;
98  bool willOverload() const;
99 
103  void handleKilledServer(HelperServerBase *srv, bool &needsNewServers);
104 
105 public:
108  std::queue<Helper::Xaction *> queue;
109  const char *id_name;
111  int ipc_type;
113  unsigned int droppedRequests;
114  time_t overloadStart;
116  time_t last_restart;
117  time_t timeout;
121  char eom;
122 
123  struct _stats {
124  int requests;
125  int replies;
126  int timedout;
129  } stats;
130 
131 protected:
132  friend void helperSubmit(helper * hlp, const char *buf, HLPCB * callback, void *data);
133  bool queueFull() const;
134  bool overloaded() const;
135  void syncQueueStats();
136  bool prepSubmit();
137  void submit(const char *buf, HLPCB * callback, void *data);
138 };
139 
140 class statefulhelper : public helper
141 {
143 
144 public:
145  typedef std::unordered_map<Helper::ReservationId, helper_stateful_server *> Reservations;
146 
147  inline statefulhelper(const char *name) : helper(name) {}
148  inline ~statefulhelper() {}
149 
150 public:
153 
155  void cancelReservation(const Helper::ReservationId reservation);
156 
157 private:
158  friend void helperStatefulSubmit(statefulhelper * hlp, const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
159 
162 
163  void submit(const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
164  bool trySubmit(const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
165 
168 };
169 
172 {
173 public:
174  virtual ~HelperServerBase();
180  void closePipesSafely(const char *name);
181 
188  void closeWritePipeSafely(const char *name);
189 
190  // TODO: Teach each child to report its child-specific state instead.
192  virtual bool reserved() = 0;
193 
195  virtual void dropQueued();
196 
198  virtual helper *getParent() const = 0;
199 
200 public:
204  int pid;
208  void *hIpc;
209 
210  char *rbuf;
211  size_t rbuf_sz;
212  size_t roffset;
213 
214  struct timeval dispatch_time;
215  struct timeval answer_time;
216 
218 
219  struct _helper_flags {
220  bool writing;
221  bool closing;
222  bool shutdown;
223  } flags;
224 
225  typedef std::list<Helper::Xaction *> Requests;
227 
228  struct {
229  uint64_t uses; //< requests sent to this helper
230  uint64_t replies; //< replies received from this helper
231  uint64_t pending; //< queued lookups waiting to be sent to this helper
232  uint64_t releases; //< times release() has been called on this helper (if stateful)
233  uint64_t timedout; //< requests which timed-out
234  } stats;
235  void initStats();
236 };
237 
238 class MemBuf;
239 class CommTimeoutCbParams;
240 
241 // TODO: Rename to StatelessHelperServer and rename HelperServerBase to HelperServer.
244 {
246 
247 public:
248  uint64_t nextRequestId;
249 
252 
254 
260 
263 
264  // STL says storing std::list iterators is safe when changing the list
265  typedef std::map<uint64_t, Requests::iterator> RequestIndex;
267 
268  virtual ~helper_server();
273  Helper::Xaction *popRequest(int requestId);
274 
277  void checkForTimedOutRequests(bool const retry);
278 
279  /*HelperServerBase API*/
280  virtual bool reserved() override {return false;}
281  virtual void dropQueued() override;
282  virtual helper *getParent() const override {return parent;}
283 
285  static void requestTimeout(const CommTimeoutCbParams &io);
286 
288  static void HelperServerClosed(helper_server *srv);
289 };
290 
291 // TODO: Rename to StatefulHelperServer and rename HelperServerBase to HelperServer.
294 {
296 
297 public:
298  virtual ~helper_stateful_server();
299  void reserve();
300  void clearReservation();
301 
302  /* HelperServerBase API */
303  virtual bool reserved() override {return reservationId.reserved();}
304  virtual helper *getParent() const override {return parent;}
305 
307  static void HelperServerClosed(helper_stateful_server *srv);
308 
310 
311  // Reservations temporary lock the server for an exclusive "client" use. The
312  // client keeps the reservation ID as a proof of her reservation. If a
313  // reservation expires, and the server is reserved for another client, then
314  // the reservation ID presented by the late client will not match ours.
317 };
318 
319 /* helper.c */
320 void helperOpenServers(helper * hlp);
322 void helperSubmit(helper * hlp, const char *buf, HLPCB * callback, void *data);
323 void helperStatefulSubmit(statefulhelper * hlp, const char *buf, HLPCB * callback, void *data, uint64_t reservation);
324 void helperShutdown(helper * hlp);
326 
327 #endif /* SQUID_HELPER_H */
328 
virtual helper * getParent() const override
the helper object that created this server
Definition: helper.h:282
std::list< Helper::Xaction * > Requests
Definition: helper.h:225
void closePipesSafely(const char *name)
Definition: helper.cc:73
dlink_node link
Definition: helper.h:217
time_t reservationStart
when the last reservation was made
Definition: helper.h:316
void submitRequest(Helper::Xaction *r)
Definition: helper.cc:441
Helper::ChildConfig childs
Configuration settings for number running.
Definition: helper.h:110
void syncQueueStats()
synchronizes queue-dependent measurements with the current queue state
Definition: helper.cc:487
represents a single "stateless helper" process
Definition: helper.h:244
wordlist * cmdline
Definition: helper.h:106
dlink_list servers
Definition: helper.h:107
statefulhelper(const char *name)
Definition: helper.h:147
bool reserved() const
Definition: ReservationId.h:22
void helperStatefulOpenServers(statefulhelper *hlp)
Definition: helper.cc:327
helper_stateful_server * findServer(const Helper::ReservationId &reservation)
Definition: helper.cc:609
struct helper::_stats stats
statefulhelper * parent
Definition: helper.h:309
virtual ~helper_stateful_server()
Definition: helper.cc:177
virtual ~helper_server()
Definition: helper.cc:147
virtual void dropQueued()
dequeues and sends a Helper::Unknown answer to all queued requests
Definition: helper.cc:123
struct HelperServerBase::_helper_flags flags
friend void helperStatefulSubmit(statefulhelper *hlp, const char *buf, HLPCB *callback, void *data, const Helper::ReservationId &reservation)
Definition: helper.cc:562
uint64_t timedout
Definition: helper.h:233
const InstanceId< HelperServerBase > index
Definition: helper.h:203
int avg_svc_time
Definition: helper.h:128
#define CBDATA_CLASS(type)
Definition: cbdata.h:302
int ipc_type
Definition: helper.h:111
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:552
static void requestTimeout(const CommTimeoutCbParams &io)
Read timeout handler.
Definition: helper.cc:1552
time_t last_queue_warn
Definition: helper.h:115
static void HelperServerClosed(helper_stateful_server *srv)
close handler to handle exited server processes
Definition: helper.cc:871
std::queue< Helper::Xaction * > queue
Definition: helper.h:108
virtual bool reserved() override
whether the server is locked for exclusive use by a client
Definition: helper.h:280
virtual bool reserved() override
whether the server is locked for exclusive use by a client
Definition: helper.h:303
helper(const char *name)
Definition: helper.h:68
Helper::Reply reply
Definition: helper.h:43
struct timeval dispatch_time
Definition: helper.h:214
virtual void dropQueued() override
dequeues and sends a Helper::Unknown answer to all queued requests
Definition: helper.cc:171
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:142
static void HelperServerClosed(helper_server *srv)
close handler to handle exited server processes
Definition: helper.cc:852
uint64_t uses
Definition: helper.h:229
void submit(const char *buf, HLPCB *callback, void *data, const Helper::ReservationId &reservation)
Definition: helper.cc:640
Requests requests
requests in order of submission/expiration
Definition: helper.h:226
void cancelReservation(const Helper::ReservationId reservation)
undo reserveServer(), clear the reservation and kick the queue
Definition: helper.cc:593
time_t last_restart
Definition: helper.h:116
uint64_t releases
Definition: helper.h:232
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:580
void * hIpc
Definition: helper.h:208
int timedout
Definition: helper.h:126
#define NULL
Definition: types.h:166
void helperShutdown(helper *hlp)
Definition: helper.cc:735
bool overloaded() const
Definition: helper.cc:481
represents a single helper process abstraction
Definition: helper.h:172
MemBuf * wqueue
Definition: helper.h:250
unsigned int droppedRequests
requests not sent during helper overload
Definition: helper.h:113
Definition: MemBuf.h:24
Definition: helper.h:64
void helperStatefulShutdown(statefulhelper *hlp)
Definition: helper.cc:772
uint64_t pending
Definition: helper.h:231
std::map< uint64_t, Requests::iterator > RequestIndex
Definition: helper.h:265
struct timeval answer_time
Definition: helper.h:215
void const char HLPCB void * data
Definition: stub_helper.cc:16
Ip::Address addr
Definition: helper.h:205
int requests
Definition: helper.h:124
bool willOverload() const
Definition: helper.cc:730
~helper()
Definition: helper.cc:818
bool retryTimedOut
Whether the timed-out requests must retried.
Definition: helper.h:118
a (temporary) lock on a (stateful) helper channel
Definition: ReservationId.h:18
RequestIndex requestsIndex
maps request IDs to requests
Definition: helper.h:266
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:672
time_t overloadStart
when the helper became overloaded (zero if it is not)
Definition: helper.h:114
Comm::ConnectionPointer writePipe
Definition: helper.h:207
bool retryBrokenHelper
Whether the requests must retried on BH replies.
Definition: helper.h:119
const char * id_name
Definition: helper.h:109
uint64_t replies
Definition: helper.h:230
friend void helperSubmit(helper *hlp, const char *buf, HLPCB *callback, void *data)
Definition: helper.cc:468
size_t roffset
Definition: helper.h:212
MemBuf * writebuf
Definition: helper.h:251
CBDATA_CHILD(helper_server)
represents a single "stateful helper" process
Definition: helper.h:294
Helper::Xaction * popRequest(int requestId)
Definition: helper.cc:888
Helper::Xaction * nextRequest()
Definition: helper.cc:1257
char * rbuf
Definition: helper.h:210
void handleKilledServer(HelperServerBase *srv, bool &needsNewServers)
Definition: helper.cc:828
bool trySubmit(const char *buf, HLPCB *callback, void *data, const Helper::ReservationId &reservation)
reserved servers indexed by reservation IDs
Definition: helper.cc:570
size_t rbuf_sz
Definition: helper.h:211
void initStats()
Definition: helper.cc:63
~statefulhelper()
Definition: helper.h:148
SBuf onTimedOutResponse
The response to use when helper response timedout.
Definition: helper.h:120
struct HelperServerBase::@75 stats
virtual ~HelperServerBase()
Definition: helper.cc:139
void const char HLPCB * callback
Definition: stub_helper.cc:16
virtual helper * getParent() const =0
the helper object that created this server
helper * parent
Definition: helper.h:253
Helper::Xaction * replyXaction
Definition: helper.h:259
void helperSubmit(helper *hlp, const char *buf, HLPCB *callback, void *data)
Definition: helper.cc:468
bool queueFull() const
whether queuing an additional request would overload the helper
Definition: helper.cc:476
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:262
Ip::Address addr
Definition: helper.h:112
int queue_size
Definition: helper.h:127
bool trySubmit(const char *buf, HLPCB *callback, void *data)
If possible, submit request. Otherwise, either kill Squid or return false.
Definition: helper.cc:541
#define false
Definition: GnuRegex.c:233
void closeWritePipeSafely(const char *name)
Definition: helper.cc:99
time_t timeout
Requests timeout.
Definition: helper.h:117
bool prepSubmit()
Definition: helper.cc:514
Helper::ReservationId reservationId
"confirmation ID" of the last
Definition: helper.h:315
void helperOpenServers(helper *hlp)
Definition: helper.cc:196
void checkForTimedOutRequests(bool const retry)
Definition: helper.cc:1513
virtual helper * getParent() const override
the helper object that created this server
Definition: helper.h:304
char eom
The char which marks the end of (response) message, normally ' '.
Definition: helper.h:121
void const char * buf
Definition: stub_helper.cc:16
Reservations reservations
Definition: helper.h:167
uint64_t nextRequestId
Definition: helper.h:248
Comm::ConnectionPointer readPipe
Definition: helper.h:206
Holds the required data to serve a helper request.
Definition: helper.h:38

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors