/* 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 */
projects / thirdparty / haproxy.git / commitdiff
