From: Tim Duesterhus Date: Sat, 19 Jun 2021 14:56:30 +0000 (+0200) Subject: CLEANUP: Prevent channel-t.h from being detected as C++ by GitHub X-Git-Tag: v2.5-dev1~65 X-Git-Url: http://git.haproxy.org/?a=commitdiff_plain;h=7386668cbf7eba555d8b421f4360e9d4541c7e99;p=haproxy-2.5.git 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. --- diff --git a/include/haproxy/channel-t.h b/include/haproxy/channel-t.h index 8bd06e1..8feb62d 100644 --- a/include/haproxy/channel-t.h +++ b/include/haproxy/channel-t.h @@ -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 */