2
* include/types/buffers.h
3
* Buffer management definitions, macros and inline functions.
5
* Copyright (C) 2000-2009 Willy Tarreau - w@1wt.eu
7
* This library is free software; you can redistribute it and/or
8
* modify it under the terms of the GNU Lesser General Public
9
* License as published by the Free Software Foundation, version 2.1
12
* This library is distributed in the hope that it will be useful,
13
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15
* Lesser General Public License for more details.
17
* You should have received a copy of the GNU Lesser General Public
18
* License along with this library; if not, write to the Free Software
19
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22
#ifndef _TYPES_BUFFERS_H
23
#define _TYPES_BUFFERS_H
25
#include <common/config.h>
26
#include <common/memory.h>
27
#include <types/stream_interface.h>
29
/* The BF_* macros designate Buffer Flags, which may be ORed in the bit field
30
* member 'flags' in struct buffer. Here we have several types of flags :
32
* - pure status flags, reported by the lower layer, which must be cleared
33
* before doing further I/O :
34
* BF_*_NULL, BF_*_PARTIAL
36
* - pure status flags, reported by mid-layer, which must also be cleared
37
* before doing further I/O :
38
* BF_*_TIMEOUT, BF_*_ERROR
40
* - read-only indicators reported by lower levels :
41
* BF_STREAMER, BF_STREAMER_FAST
43
* - write-once status flags reported by the mid-level : BF_SHUTR, BF_SHUTW
45
* - persistent control flags managed only by higher level :
46
* BF_SHUT*_NOW, BF_*_ENA, BF_HIJACK
48
* The flags have been arranged for readability, so that the read and write
49
* bits have the same position in a byte (read being the lower byte and write
50
* the second one). All flag names are relative to the buffer. For instance,
51
* 'write' indicates the direction from the buffer to the stream interface.
54
#define BF_READ_NULL 0x000001 /* last read detected on producer side */
55
#define BF_READ_PARTIAL 0x000002 /* some data were read from producer */
56
#define BF_READ_TIMEOUT 0x000004 /* timeout while waiting for producer */
57
#define BF_READ_ERROR 0x000008 /* unrecoverable error on producer side */
58
#define BF_READ_ACTIVITY (BF_READ_NULL|BF_READ_PARTIAL|BF_READ_ERROR)
60
#define BF_FULL 0x000010 /* buffer cannot accept any more data (l >= max len) */
61
#define BF_SHUTR 0x000020 /* producer has already shut down */
62
#define BF_SHUTR_NOW 0x000040 /* the producer must shut down for reads ASAP */
63
#define BF_READ_NOEXP 0x000080 /* producer should not expire */
65
#define BF_WRITE_NULL 0x000100 /* write(0) or connect() succeeded on consumer side */
66
#define BF_WRITE_PARTIAL 0x000200 /* some data were written to the consumer */
67
#define BF_WRITE_TIMEOUT 0x000400 /* timeout while waiting for consumer */
68
#define BF_WRITE_ERROR 0x000800 /* unrecoverable error on consumer side */
69
#define BF_WRITE_ACTIVITY (BF_WRITE_NULL|BF_WRITE_PARTIAL|BF_WRITE_ERROR)
71
#define BF_OUT_EMPTY 0x001000 /* send_max and pipe are empty. Set by last change. */
72
#define BF_SHUTW 0x002000 /* consumer has already shut down */
73
#define BF_SHUTW_NOW 0x004000 /* the consumer must shut down for writes ASAP */
74
#define BF_AUTO_CLOSE 0x008000 /* producer can forward shutdown to other side */
76
/* When either BF_SHUTR_NOW or BF_HIJACK is set, it is strictly forbidden for
77
* the producer to alter the buffer contents. When BF_SHUTW_NOW is set, the
78
* consumer is free to perform a shutw() when it has consumed the last contents,
79
* otherwise the session processor will do it anyway.
81
* The SHUT* flags work like this :
83
* SHUTR SHUTR_NOW meaning
84
* 0 0 normal case, connection still open and data is being read
85
* 0 1 closing : the producer cannot feed data anymore but can close
86
* 1 0 closed: the producer has closed its input channel.
89
* SHUTW SHUTW_NOW meaning
90
* 0 0 normal case, connection still open and data is being written
91
* 0 1 closing: the consumer can send last data and may then close
92
* 1 0 closed: the consumer has closed its output channel.
95
* The SHUTW_NOW flag should be set by the session processor when SHUTR and AUTO_CLOSE
96
* are both set. It may also be set by a hijacker at the end of data. And it may also
97
* be set by the producer when it detects SHUTR while directly forwarding data to the
100
* The SHUTR_NOW flag is mostly used to force the producer to abort when an error is
101
* detected on the consumer side.
104
#define BF_STREAMER 0x010000 /* the producer is identified as streaming data */
105
#define BF_STREAMER_FAST 0x020000 /* the consumer seems to eat the stream very fast */
107
#define BF_HIJACK 0x040000 /* the producer is temporarily replaced by ->hijacker */
108
#define BF_ANA_TIMEOUT 0x080000 /* the analyser timeout has expired */
109
#define BF_READ_ATTACHED 0x100000 /* the read side is attached for the first time */
110
#define BF_KERN_SPLICING 0x200000 /* kernel splicing desired for this buffer */
111
#define BF_READ_DONTWAIT 0x400000 /* wake the task up after every read (eg: HTTP request) */
112
#define BF_AUTO_CONNECT 0x800000 /* consumer may attempt to establish a new connection */
114
#define BF_DONT_READ 0x1000000 /* disable reading for now */
115
#define BF_EXPECT_MORE 0x2000000 /* more data expected to be sent very soon (one-shoot) */
116
#define BF_SEND_DONTWAIT 0x4000000 /* don't wait for sending data (one-shoot) */
117
#define BF_NEVER_WAIT 0x8000000 /* never wait for sending data (permanent) */
119
/* Use these masks to clear the flags before going back to lower layers */
120
#define BF_CLEAR_READ (~(BF_READ_NULL|BF_READ_PARTIAL|BF_READ_ERROR|BF_READ_ATTACHED))
121
#define BF_CLEAR_WRITE (~(BF_WRITE_NULL|BF_WRITE_PARTIAL|BF_WRITE_ERROR))
122
#define BF_CLEAR_TIMEOUT (~(BF_READ_TIMEOUT|BF_WRITE_TIMEOUT|BF_ANA_TIMEOUT))
124
/* Masks which define input events for stream analysers */
125
#define BF_MASK_ANALYSER (BF_READ_ATTACHED|BF_READ_ACTIVITY|BF_READ_TIMEOUT|BF_ANA_TIMEOUT|BF_WRITE_ACTIVITY)
127
/* Mask for static flags which are not events, but might change during processing */
128
#define BF_MASK_STATIC (BF_OUT_EMPTY|BF_FULL|BF_HIJACK|BF_AUTO_CLOSE|BF_AUTO_CONNECT|BF_SHUTR|BF_SHUTW|BF_SHUTR_NOW|BF_SHUTW_NOW)
131
/* Analysers (buffer->analysers).
132
* Those bits indicate that there are some processing to do on the buffer
133
* contents. It will probably evolve into a linked list later. Those
134
* analysers could be compared to higher level processors.
135
* The field is blanked by buffer_init() and only by analysers themselves
138
#define AN_REQ_INSPECT 0x00000001 /* inspect request contents */
139
#define AN_REQ_WAIT_HTTP 0x00000002 /* wait for an HTTP request */
140
#define AN_REQ_HTTP_PROCESS_FE 0x00000004 /* process the frontend's HTTP part */
141
#define AN_REQ_SWITCHING_RULES 0x00000008 /* apply the switching rules */
142
#define AN_REQ_HTTP_PROCESS_BE 0x00000010 /* process the backend's HTTP part */
143
#define AN_REQ_HTTP_INNER 0x00000020 /* inner processing of HTTP request */
144
#define AN_REQ_HTTP_TARPIT 0x00000040 /* wait for end of HTTP tarpit */
145
#define AN_REQ_HTTP_BODY 0x00000080 /* inspect HTTP request body */
146
#define AN_REQ_STICKING_RULES 0x00000100 /* table persistence matching */
148
#define AN_REQ_PRST_RDP_COOKIE 0x00000400 /* persistence on rdp cookie */
149
#define AN_REQ_HTTP_XFER_BODY 0x00000800 /* forward request body */
151
/* response analysers */
152
#define AN_RES_INSPECT 0x00010000 /* content inspection */
153
#define AN_RES_WAIT_HTTP 0x00020000 /* wait for HTTP response */
154
#define AN_RES_HTTP_PROCESS_BE 0x00040000 /* process backend's HTTP part */
155
#define AN_RES_HTTP_PROCESS_FE 0x00040000 /* process frontend's HTTP part (same for now) */
156
#define AN_RES_STORE_RULES 0x00080000 /* table persistence matching */
157
#define AN_RES_HTTP_XFER_BODY 0x00100000 /* forward response body */
160
/* Magic value to forward infinite size (TCP, ...), used with ->to_forward */
161
#define BUF_INFINITE_FORWARD MAX_RANGE(int)
163
/* describes a chunk of string */
165
char *str; /* beginning of the string itself. Might not be 0-terminated */
166
size_t size; /* total size of the buffer, 0 if the *str is read-only */
167
int len; /* current size of the string from first to last char. <0 = uninit. */
170
/* needed for a declaration below */
174
unsigned int flags; /* BF_* */
175
int rex; /* expiration date for a read, in ticks */
176
int wex; /* expiration date for a write or connect, in ticks */
177
int rto; /* read timeout, in ticks */
178
int wto; /* write timeout, in ticks */
179
int cto; /* connect timeout, in ticks */
180
unsigned int l; /* data length */
181
char *r, *w, *lr; /* read ptr, write ptr, last read */
182
unsigned int size; /* buffer size in bytes */
183
unsigned int send_max; /* number of bytes the sender can consume om this buffer, <= l */
184
unsigned int to_forward; /* number of bytes to forward after send_max without a wake-up */
185
unsigned int analysers; /* bit field indicating what to do on the buffer */
186
int analyse_exp; /* expiration date for current analysers (if set) */
187
void (*hijacker)(struct session *, struct buffer *); /* alternative content producer */
188
unsigned char xfer_large; /* number of consecutive large xfers */
189
unsigned char xfer_small; /* number of consecutive small xfers */
190
unsigned long long total; /* total data read */
191
struct stream_interface *prod; /* producer attached to this buffer */
192
struct stream_interface *cons; /* consumer attached to this buffer */
193
struct pipe *pipe; /* non-NULL only when data present */
194
char data[0]; /* <size> bytes */
198
/* Note about the buffer structure
200
The buffer contains two length indicators, one to_forward counter and one
201
send_max limit. First, it must be understood that the buffer is in fact
203
- the visible data (->data, for ->l bytes)
204
- the invisible data, typically in kernel buffers forwarded directly from
205
the source stream sock to the destination stream sock (->pipe->data
206
bytes). Those are used only during forward.
208
In order not to mix data streams, the producer may only feed the invisible
209
data with data to forward, and only when the visible buffer is empty. The
210
consumer may not always be able to feed the invisible buffer due to platform
211
limitations (lack of kernel support).
213
Conversely, the consumer must always take data from the invisible data first
214
before ever considering visible data. There is no limit to the size of data
215
to consume from the invisible buffer, as platform-specific implementations
216
will rarely leave enough control on this. So any byte fed into the invisible
217
buffer is expected to reach the destination file descriptor, by any means.
218
However, it's the consumer's responsibility to ensure that the invisible
219
data has been entirely consumed before consuming visible data. This must be
220
reflected by ->pipe->data. This is very important as this and only this can
221
ensure strict ordering of data between buffers.
223
The producer is responsible for decreasing ->to_forward and increasing
224
->send_max. The ->to_forward parameter indicates how many bytes may be fed
225
into either data buffer without waking the parent up. The special value
226
BUF_INFINITE_FORWARD is never decreased nor increased. The ->send_max
227
parameter says how many bytes may be read from the visible buffer. Thus it
228
may never exceed ->l. This parameter is updated by any buffer_write() as
229
well as any data forwarded through the visible buffer.
231
The consumer is responsible for decreasing ->send_max when it sends data
232
from the visible buffer, and ->pipe->data when it sends data from the
235
A real-world example consists in part in an HTTP response waiting in a
236
buffer to be forwarded. We know the header length (300) and the amount of
237
data to forward (content-length=9000). The buffer already contains 1000
238
bytes of data after the 300 bytes of headers. Thus the caller will set
239
->send_max to 300 indicating that it explicitly wants to send those data,
240
and set ->to_forward to 9000 (content-length). This value must be normalised
241
immediately after updating ->to_forward : since there are already 1300 bytes
242
in the buffer, 300 of which are already counted in ->send_max, and that size
243
is smaller than ->to_forward, we must update ->send_max to 1300 to flush the
244
whole buffer, and reduce ->to_forward to 8000. After that, the producer may
245
try to feed the additional data through the invisible buffer using a
246
platform-specific method such as splice().
248
The ->to_forward entry is also used to detect whether we can fill the buffer
249
or not. The idea is that we need to save some space for data manipulation
250
(mainly header rewriting in HTTP) so we don't want to have a full buffer on
251
input before processing a request or response. Thus, we ensure that there is
252
always global.maxrewrite bytes of free space. Since we don't want to forward
253
chunks without filling the buffer, we rely on ->to_forward. When ->to_forward
254
is null, we may have some processing to do so we don't want to fill the
255
buffer. When ->to_forward is non-null, we know we don't care for at least as
256
many bytes. In the end, we know that each of the ->to_forward bytes will
257
eventually leave the buffer. So as long as ->to_forward is larger than
258
global.maxrewrite, we can fill the buffer. If ->to_forward is smaller than
259
global.maxrewrite, then we don't want to fill the buffer with more than
260
->size - global.maxrewrite + ->to_forward.
262
Note that this also means that anyone touching ->to_forward must also take
263
care of updating the BF_FULL flag. For this reason, it's really advised to
264
use buffer_forward() only.
267
#endif /* _TYPES_BUFFERS_H */
added
removed
include/types/buffers.h
