mirror of
http://git.haproxy.org/git/haproxy.git/
synced 2025-02-21 21:26:58 +00:00
CLEANUP: Prevent channel-t.h from being detected as C++ by GitHub
GitHub uses github/linguist to determine the programming language used for each source file to show statistics and to power the search. In cases of unique file extensions this is easy, but for `.h` files the situation is less clear as they are used for C, C++, Objective C and more. In these cases linguist makes use of heuristics to determine the language. One of these heuristics for C++ is that the file contains a line beginning with `try`, only preceded by whitespace indentation. This heuristic matches the long comment at the bottom of `channel-t.h`, as one sentence includes the word `try` after a linebreak. Fix this misdetection by changing the comment to follow the convention that all lines start with an asterisk.
This commit is contained in:
Tim Duesterhus
Willy Tarreau
parent
901972e261
commit
7386668cbf
@ -207,98 +207,98 @@ struct channel {
|
||||
|
||||
|
||||
/* Note about the channel structure
|
||||
|
||||
A channel stores information needed to reliably transport data in a single
|
||||
direction. It stores status flags, timeouts, counters, subscribed analysers,
|
||||
pointers to a data producer and to a data consumer, and information about
|
||||
the amount of data which is allowed to flow directly from the producer to
|
||||
the consumer without waking up the analysers.
|
||||
|
||||
A channel may buffer data into two locations :
|
||||
- a visible buffer (->buf)
|
||||
- an invisible buffer which right now consists in a pipe making use of
|
||||
kernel buffers that cannot be tampered with.
|
||||
|
||||
Data stored into the first location may be analysed and altered by analysers
|
||||
while data stored in pipes is only aimed at being transported from one
|
||||
network socket to another one without being subject to memory copies. This
|
||||
buffer may only be used when both the socket layer and the data layer of the
|
||||
producer and the consumer support it, which typically is the case with Linux
|
||||
splicing over sockets, and when there are enough data to be transported
|
||||
without being analyzed (transport of TCP/HTTP payload or tunnelled data,
|
||||
which is indicated by ->to_forward).
|
||||
|
||||
In order not to mix data streams, the producer may only feed the invisible
|
||||
data with data to forward, and only when the visible buffer is empty. The
|
||||
producer may not always be able to feed the invisible buffer due to platform
|
||||
limitations (lack of kernel support).
|
||||
|
||||
Conversely, the consumer must always take data from the invisible data first
|
||||
before ever considering visible data. There is no limit to the size of data
|
||||
to consume from the invisible buffer, as platform-specific implementations
|
||||
will rarely leave enough control on this. So any byte fed into the invisible
|
||||
buffer is expected to reach the destination file descriptor, by any means.
|
||||
However, it's the consumer's responsibility to ensure that the invisible
|
||||
data has been entirely consumed before consuming visible data. This must be
|
||||
reflected by ->pipe->data. This is very important as this and only this can
|
||||
ensure strict ordering of data between buffers.
|
||||
|
||||
The producer is responsible for decreasing ->to_forward. The ->to_forward
|
||||
parameter indicates how many bytes may be fed into either data buffer
|
||||
without waking the parent up. The special value CHN_INFINITE_FORWARD is
|
||||
never decreased nor increased.
|
||||
|
||||
The buf->o parameter says how many bytes may be consumed from the visible
|
||||
buffer. This parameter is updated by any buffer_write() as well as any data
|
||||
forwarded through the visible buffer. Since the ->to_forward attribute
|
||||
applies to data after buf->p, an analyser will not see a buffer which has a
|
||||
non-null ->to_forward with buf->i > 0. A producer is responsible for raising
|
||||
buf->o by min(to_forward, buf->i) when it injects data into the buffer.
|
||||
|
||||
The consumer is responsible for decreasing ->buf->o when it sends data
|
||||
from the visible buffer, and ->pipe->data when it sends data from the
|
||||
invisible buffer.
|
||||
|
||||
A real-world example consists in part in an HTTP response waiting in a
|
||||
buffer to be forwarded. We know the header length (300) and the amount of
|
||||
data to forward (content-length=9000). The buffer already contains 1000
|
||||
bytes of data after the 300 bytes of headers. Thus the caller will set
|
||||
buf->o to 300 indicating that it explicitly wants to send those data, and
|
||||
set ->to_forward to 9000 (content-length). This value must be normalised
|
||||
immediately after updating ->to_forward : since there are already 1300 bytes
|
||||
in the buffer, 300 of which are already counted in buf->o, and that size
|
||||
is smaller than ->to_forward, we must update buf->o to 1300 to flush the
|
||||
whole buffer, and reduce ->to_forward to 8000. After that, the producer may
|
||||
try to feed the additional data through the invisible buffer using a
|
||||
platform-specific method such as splice().
|
||||
|
||||
The ->to_forward entry is also used to detect whether we can fill the buffer
|
||||
or not. The idea is that we need to save some space for data manipulation
|
||||
(mainly header rewriting in HTTP) so we don't want to have a full buffer on
|
||||
input before processing a request or response. Thus, we ensure that there is
|
||||
always global.maxrewrite bytes of free space. Since we don't want to forward
|
||||
chunks without filling the buffer, we rely on ->to_forward. When ->to_forward
|
||||
is null, we may have some processing to do so we don't want to fill the
|
||||
buffer. When ->to_forward is non-null, we know we don't care for at least as
|
||||
many bytes. In the end, we know that each of the ->to_forward bytes will
|
||||
eventually leave the buffer. So as long as ->to_forward is larger than
|
||||
global.maxrewrite, we can fill the buffer. If ->to_forward is smaller than
|
||||
global.maxrewrite, then we don't want to fill the buffer with more than
|
||||
buf->size - global.maxrewrite + ->to_forward.
|
||||
|
||||
A buffer may contain up to 5 areas :
|
||||
- the data waiting to be sent. These data are located between buf->p-o and
|
||||
buf->p ;
|
||||
- the data to process and possibly transform. These data start at
|
||||
buf->p and may be up to ->i bytes long.
|
||||
- the data to preserve. They start at ->p and stop at ->p+i. The limit
|
||||
between the two solely depends on the protocol being analysed.
|
||||
- the spare area : it is the remainder of the buffer, which can be used to
|
||||
store new incoming data. It starts at ->p+i and is up to ->size-i-o long.
|
||||
It may be limited by global.maxrewrite.
|
||||
- the reserved area : this is the area which must not be filled and is
|
||||
reserved for possible rewrites ; it is up to global.maxrewrite bytes
|
||||
long.
|
||||
*
|
||||
* A channel stores information needed to reliably transport data in a single
|
||||
* direction. It stores status flags, timeouts, counters, subscribed analysers,
|
||||
* pointers to a data producer and to a data consumer, and information about
|
||||
* the amount of data which is allowed to flow directly from the producer to
|
||||
* the consumer without waking up the analysers.
|
||||
*
|
||||
* A channel may buffer data into two locations :
|
||||
* - a visible buffer (->buf)
|
||||
* - an invisible buffer which right now consists in a pipe making use of
|
||||
* kernel buffers that cannot be tampered with.
|
||||
*
|
||||
* Data stored into the first location may be analysed and altered by analysers
|
||||
* while data stored in pipes is only aimed at being transported from one
|
||||
* network socket to another one without being subject to memory copies. This
|
||||
* buffer may only be used when both the socket layer and the data layer of the
|
||||
* producer and the consumer support it, which typically is the case with Linux
|
||||
* splicing over sockets, and when there are enough data to be transported
|
||||
* without being analyzed (transport of TCP/HTTP payload or tunnelled data,
|
||||
* which is indicated by ->to_forward).
|
||||
*
|
||||
* In order not to mix data streams, the producer may only feed the invisible
|
||||
* data with data to forward, and only when the visible buffer is empty. The
|
||||
* producer may not always be able to feed the invisible buffer due to platform
|
||||
* limitations (lack of kernel support).
|
||||
*
|
||||
* Conversely, the consumer must always take data from the invisible data first
|
||||
* before ever considering visible data. There is no limit to the size of data
|
||||
* to consume from the invisible buffer, as platform-specific implementations
|
||||
* will rarely leave enough control on this. So any byte fed into the invisible
|
||||
* buffer is expected to reach the destination file descriptor, by any means.
|
||||
* However, it's the consumer's responsibility to ensure that the invisible
|
||||
* data has been entirely consumed before consuming visible data. This must be
|
||||
* reflected by ->pipe->data. This is very important as this and only this can
|
||||
* ensure strict ordering of data between buffers.
|
||||
*
|
||||
* The producer is responsible for decreasing ->to_forward. The ->to_forward
|
||||
* parameter indicates how many bytes may be fed into either data buffer
|
||||
* without waking the parent up. The special value CHN_INFINITE_FORWARD is
|
||||
* never decreased nor increased.
|
||||
*
|
||||
* The buf->o parameter says how many bytes may be consumed from the visible
|
||||
* buffer. This parameter is updated by any buffer_write() as well as any data
|
||||
* forwarded through the visible buffer. Since the ->to_forward attribute
|
||||
* applies to data after buf->p, an analyser will not see a buffer which has a
|
||||
* non-null ->to_forward with buf->i > 0. A producer is responsible for raising
|
||||
* buf->o by min(to_forward, buf->i) when it injects data into the buffer.
|
||||
*
|
||||
* The consumer is responsible for decreasing ->buf->o when it sends data
|
||||
* from the visible buffer, and ->pipe->data when it sends data from the
|
||||
* invisible buffer.
|
||||
*
|
||||
* A real-world example consists in part in an HTTP response waiting in a
|
||||
* buffer to be forwarded. We know the header length (300) and the amount of
|
||||
* data to forward (content-length=9000). The buffer already contains 1000
|
||||
* bytes of data after the 300 bytes of headers. Thus the caller will set
|
||||
* buf->o to 300 indicating that it explicitly wants to send those data, and
|
||||
* set ->to_forward to 9000 (content-length). This value must be normalised
|
||||
* immediately after updating ->to_forward : since there are already 1300 bytes
|
||||
* in the buffer, 300 of which are already counted in buf->o, and that size
|
||||
* is smaller than ->to_forward, we must update buf->o to 1300 to flush the
|
||||
* whole buffer, and reduce ->to_forward to 8000. After that, the producer may
|
||||
* try to feed the additional data through the invisible buffer using a
|
||||
* platform-specific method such as splice().
|
||||
*
|
||||
* The ->to_forward entry is also used to detect whether we can fill the buffer
|
||||
* or not. The idea is that we need to save some space for data manipulation
|
||||
* (mainly header rewriting in HTTP) so we don't want to have a full buffer on
|
||||
* input before processing a request or response. Thus, we ensure that there is
|
||||
* always global.maxrewrite bytes of free space. Since we don't want to forward
|
||||
* chunks without filling the buffer, we rely on ->to_forward. When ->to_forward
|
||||
* is null, we may have some processing to do so we don't want to fill the
|
||||
* buffer. When ->to_forward is non-null, we know we don't care for at least as
|
||||
* many bytes. In the end, we know that each of the ->to_forward bytes will
|
||||
* eventually leave the buffer. So as long as ->to_forward is larger than
|
||||
* global.maxrewrite, we can fill the buffer. If ->to_forward is smaller than
|
||||
* global.maxrewrite, then we don't want to fill the buffer with more than
|
||||
* buf->size - global.maxrewrite + ->to_forward.
|
||||
*
|
||||
* A buffer may contain up to 5 areas :
|
||||
* - the data waiting to be sent. These data are located between buf->p-o and
|
||||
* buf->p ;
|
||||
* - the data to process and possibly transform. These data start at
|
||||
* buf->p and may be up to ->i bytes long.
|
||||
* - the data to preserve. They start at ->p and stop at ->p+i. The limit
|
||||
* between the two solely depends on the protocol being analysed.
|
||||
* - the spare area : it is the remainder of the buffer, which can be used to
|
||||
* store new incoming data. It starts at ->p+i and is up to ->size-i-o long.
|
||||
* It may be limited by global.maxrewrite.
|
||||
* - the reserved area : this is the area which must not be filled and is
|
||||
* reserved for possible rewrites ; it is up to global.maxrewrite bytes
|
||||
* long.
|
||||
*/
|
||||
|
||||
#endif /* _HAPROXY_CHANNEL_T_H */
|
||||
|
||||
Loading…
Reference in New Issue
Block a user