helper.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 1996-2023 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 "base/RefCount.h"
17#include "cbdata.h"
18#include "comm/forward.h"
19#include "dlink.h"
20#include "helper/ChildConfig.h"
21#include "helper/forward.h"
22#include "helper/Reply.h"
23#include "helper/Request.h"
25#include "ip/Address.h"
26#include "sbuf/SBuf.h"
27
28#include <list>
29#include <map>
30#include <queue>
31#include <unordered_map>
32
34class MemBuf;
35class Packable;
36class wordlist;
37
38namespace Helper
39{
41class Xaction {
43public:
44 Xaction(HLPCB *c, void *d, const char *b): request(c, d, b) {}
47};
48
49class SessionBase;
50
66class Client: public RefCountable
67{
68public:
70
73 static Pointer Make(const char *name);
74
75 virtual ~Client();
76
79
81 bool trySubmit(const char *buf, HLPCB * callback, void *data);
82
85 void submitRequest(Xaction *);
86
88 void packStatsInto(Packable *p, const char *label = nullptr) const;
91 bool willOverload() const;
92
96 void handleKilledServer(SessionBase *, bool &needsNewServers);
97
101 void handleFewerServers(bool madeProgress);
102
104 void callBack(Xaction &);
105
108 virtual void openSessions();
109
112
113public:
114 wordlist *cmdline = nullptr;
116 std::queue<Xaction *> queue;
117 const char *id_name = nullptr;
119 int ipc_type = 0;
121 unsigned int droppedRequests = 0;
122 time_t overloadStart = 0;
123 time_t last_queue_warn = 0;
124 time_t last_restart = 0;
125 time_t timeout = 0;
126 bool retryTimedOut = false;
127 bool retryBrokenHelper = false;
129 char eom = '\n';
130
131 struct _stats {
132 int requests = 0;
133 int replies = 0;
134 int timedout = 0;
135 int queue_size = 0;
138
139protected:
141 explicit Client(const char * const name): id_name(name) {}
142
143 bool queueFull() const;
144 bool overloaded() const;
145 void syncQueueStats();
146 bool prepSubmit();
147 void submit(const char *buf, HLPCB * callback, void *data);
148};
149
150} // namespace Helper
151
152// TODO: Rename to a *Client.
154{
155public:
157 typedef std::unordered_map<Helper::ReservationId, helper_stateful_server *> Reservations;
158
159 ~statefulhelper() override = default;
160
161 static Pointer Make(const char *name);
162
165
167 void cancelReservation(const Helper::ReservationId reservation);
168
169 /* Helper::Client API */
170 void openSessions() override;
171
172private:
173 friend void helperStatefulSubmit(const statefulhelper::Pointer &, const char *buf, HLPCB *, void *cbData, const Helper::ReservationId &);
174
175 explicit statefulhelper(const char * const name): Helper::Client(name) {}
176
179
180 void submit(const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
181 bool trySubmit(const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
182
185};
186
187namespace Helper
188{
189
192{
193public:
194 ~SessionBase() override;
195
201 void closePipesSafely(const char *name);
202
209 void closeWritePipeSafely(const char *name);
210
211 // TODO: Teach each child to report its child-specific state instead.
213 virtual bool reserved() = 0;
214
216 virtual void dropQueued(Client &);
217
218public:
222
223 int pid;
227 void *hIpc;
228
229 char *rbuf;
230 size_t rbuf_sz;
231 size_t roffset;
232
233 struct timeval dispatch_time;
234 struct timeval answer_time;
235
237
243
244 using Requests = std::list<Xaction *>;
246
247 struct {
248 uint64_t uses; //< requests sent to this helper
249 uint64_t replies; //< replies received from this helper
250 uint64_t pending; //< queued lookups waiting to be sent to this helper
251 uint64_t releases; //< times release() has been called on this helper (if stateful)
252 uint64_t timedout; //< requests which timed-out
254 void initStats();
255};
256
259class Session: public SessionBase
260{
262
263public:
265
268
270
276
279
280 // STL says storing std::list iterators is safe when changing the list
281 typedef std::map<uint64_t, Requests::iterator> RequestIndex;
283
284 ~Session() override;
285
290 Xaction *popRequest(int requestId);
291
294 void checkForTimedOutRequests(bool const retry);
295
296 /* SessionBase API */
297 bool reserved() override {return false;}
298 void dropQueued(Client &) override;
299
301 static void requestTimeout(const CommTimeoutCbParams &io);
302
304 static void HelperServerClosed(Session *);
305};
306
307} // namespace Helper
308
309// TODO: Rename to a *Session, matching renamed statefulhelper.
313{
315
316public:
317 ~helper_stateful_server() override;
318 void reserve();
319 void clearReservation();
320
321 /* HelperServerBase API */
322 bool reserved() override {return reservationId.reserved();}
323
326
328
329 // Reservations temporary lock the server for an exclusive "client" use. The
330 // client keeps the reservation ID as a proof of her reservation. If a
331 // reservation expires, and the server is reserved for another client, then
332 // the reservation ID presented by the late client will not match ours.
335};
336
337void helperSubmit(const Helper::Client::Pointer &, const char *buf, HLPCB *, void *cbData);
338void helperStatefulSubmit(const statefulhelper::Pointer &, const char *buf, HLPCB *, void *cbData, uint64_t reservation);
341
342#endif /* SQUID_HELPER_H */
343
#define RefCountable
The locking interface for use on Reference-Counted classes.
Definition: Lock.h:66
Definition: Client.h:35
time_t timeout
Requests timeout.
Definition: helper.h:125
bool retryBrokenHelper
Whether the requests must retried on BH replies.
Definition: helper.h:127
bool queueFull() const
whether queuing an additional request would overload the helper
Definition: helper.cc:488
Ip::Address addr
Definition: helper.h:120
dlink_list servers
Definition: helper.h:115
time_t last_restart
Definition: helper.h:124
Client(const char *const name)
Definition: helper.h:141
void sessionClosed(SessionBase &)
handles exited helper process
Definition: helper.cc:901
const char * id_name
Definition: helper.h:117
unsigned int droppedRequests
requests not sent during helper overload
Definition: helper.h:121
Xaction * nextRequest()
Definition: helper.cc:1295
void handleKilledServer(SessionBase *, bool &needsNewServers)
Definition: helper.cc:863
bool willOverload() const
Definition: helper.cc:754
virtual ~Client()
Definition: helper.cc:853
void packStatsInto(Packable *p, const char *label=nullptr) const
Dump some stats about the helper state to a Packable object.
Definition: helper.cc:696
void handleFewerServers(bool madeProgress)
Definition: helper.cc:881
char eom
The char which marks the end of (response) message, normally ' '.
Definition: helper.h:129
void submit(const char *buf, HLPCB *callback, void *data)
dispatches or enqueues a helper requests; does not enforce queue limits
Definition: helper.cc:564
SBuf onTimedOutResponse
The response to use when helper response timedout.
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:553
void syncQueueStats()
synchronizes queue-dependent measurements with the current queue state
Definition: helper.cc:499
std::queue< Xaction * > queue
Definition: helper.h:116
bool prepSubmit()
Definition: helper.cc:526
time_t last_queue_warn
Definition: helper.h:123
void submitRequest(Xaction *)
Definition: helper.cc:455
time_t overloadStart
when the helper became overloaded (zero if it is not)
Definition: helper.h:122
ChildConfig childs
Configuration settings for number running.
Definition: helper.h:118
bool overloaded() const
Definition: helper.cc:493
void callBack(Xaction &)
sends transaction response to the transaction initiator
Definition: helper.cc:572
bool retryTimedOut
Whether the timed-out requests must retried.
Definition: helper.h:126
struct Helper::Client::_stats stats
wordlist * cmdline
Definition: helper.h:114
static Pointer Make(const char *name)
Definition: helper.cc:759
virtual void openSessions()
Definition: helper.cc:192
int ipc_type
Definition: helper.h:119
a (temporary) lock on a (stateful) helper channel
Definition: ReservationId.h:18
bool reserved() const
Definition: ReservationId.h:22
represents a single helper process
Definition: helper.h:192
uint64_t timedout
Definition: helper.h:252
uint64_t replies
Definition: helper.h:249
struct Helper::SessionBase::_helper_flags flags
uint64_t pending
Definition: helper.h:250
uint64_t releases
Definition: helper.h:251
dlink_node link
Definition: helper.h:236
Requests requests
requests in order of submission/expiration
Definition: helper.h:245
Ip::Address addr
Definition: helper.h:224
const InstanceId< SessionBase > index
Definition: helper.h:221
void closePipesSafely(const char *name)
Definition: helper.cc:72
struct timeval dispatch_time
Definition: helper.h:233
virtual void dropQueued(Client &)
dequeues and sends an Unknown answer to all queued requests
Definition: helper.cc:126
struct timeval answer_time
Definition: helper.h:234
uint64_t uses
Definition: helper.h:248
virtual bool reserved()=0
whether the server is locked for exclusive use by a client
void initStats()
Definition: helper.cc:62
struct Helper::SessionBase::@68 stats
~SessionBase() override
Definition: helper.cc:138
Comm::ConnectionPointer readPipe
Definition: helper.h:225
void closeWritePipeSafely(const char *name)
Definition: helper.cc:100
std::list< Xaction * > Requests
Definition: helper.h:244
Comm::ConnectionPointer writePipe
Definition: helper.h:226
MemBuf * wqueue
Definition: helper.h:266
static void HelperServerClosed(Session *)
close handler to handle exited server processes
Definition: helper.cc:912
bool reserved() override
whether the server is locked for exclusive use by a client
Definition: helper.h:297
void dropQueued(Client &) override
dequeues and sends an Unknown answer to all queued requests
Definition: helper.cc:169
uint64_t nextRequestId
Definition: helper.h:264
void checkForTimedOutRequests(bool const retry)
Definition: helper.cc:1550
MemBuf * writebuf
Definition: helper.h:267
Client::Pointer parent
Definition: helper.h:269
bool ignoreToEom
Whether to ignore current message, because it is timed-out or other reason.
Definition: helper.h:278
Xaction * replyXaction
Definition: helper.h:275
CBDATA_CHILD(Session)
~Session() override
Definition: helper.cc:146
Xaction * popRequest(int requestId)
Definition: helper.cc:929
RequestIndex requestsIndex
maps request IDs to requests
Definition: helper.h:282
std::map< uint64_t, Requests::iterator > RequestIndex
Definition: helper.h:281
static void requestTimeout(const CommTimeoutCbParams &io)
Read timeout handler.
Definition: helper.cc:1588
Holds the required data to serve a helper request.
Definition: helper.h:41
Xaction(HLPCB *c, void *d, const char *b)
Definition: helper.h:44
Helper::Reply reply
Definition: helper.h:46
MEMPROXY_CLASS(Helper::Xaction)
Helper::Request request
Definition: helper.h:45
Definition: MemBuf.h:24
Definition: SBuf.h:94
bool reserved() override
whether the server is locked for exclusive use by a client
Definition: helper.h:322
~helper_stateful_server() override
Definition: helper.cc:175
statefulhelper::Pointer parent
Definition: helper.h:327
time_t reservationStart
when the last reservation was made
Definition: helper.h:334
static void HelperServerClosed(helper_stateful_server *srv)
close handler to handle exited server processes
Definition: helper.cc:921
CBDATA_CHILD(helper_stateful_server)
Helper::ReservationId reservationId
"confirmation ID" of the last
Definition: helper.h:333
void submit(const char *buf, HLPCB *callback, void *data, const Helper::ReservationId &reservation)
Definition: helper.cc:664
helper_stateful_server * findServer(const Helper::ReservationId &reservation)
Definition: helper.cc:633
~statefulhelper() override=default
std::unordered_map< Helper::ReservationId, helper_stateful_server * > Reservations
Definition: helper.h:157
static Pointer Make(const char *name)
Definition: helper.cc:765
void reserveServer(helper_stateful_server *srv)
reserve the given server
Definition: helper.cc:604
void cancelReservation(const Helper::ReservationId reservation)
undo reserveServer(), clear the reservation and kick the queue
Definition: helper.cc:617
void openSessions() override
Definition: helper.cc:329
statefulhelper(const char *const name)
Definition: helper.h:175
Reservations reservations
Definition: helper.h:184
friend void helperStatefulSubmit(const statefulhelper::Pointer &, const char *buf, HLPCB *, void *cbData, const Helper::ReservationId &)
Definition: helper.cc:586
bool trySubmit(const char *buf, HLPCB *callback, void *data, const Helper::ReservationId &reservation)
reserved servers indexed by reservation IDs
Definition: helper.cc:594
void HLPCB(void *, const Helper::Reply &)
Definition: forward.h:33
void helperSubmit(const Helper::Client::Pointer &, const char *buf, HLPCB *, void *cbData)
Definition: helper.cc:480
void helperShutdown(const Helper::Client::Pointer &)
Definition: helper.cc:771
void helperStatefulSubmit(const statefulhelper::Pointer &, const char *buf, HLPCB *, void *cbData, uint64_t reservation)
void helperStatefulShutdown(const statefulhelper::Pointer &)
Definition: helper.cc:807
helper protocol primitives
Definition: helper.h:39

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors