CLEANUP: channel: usr CF_/CHN_ prefixes instead of BF_/BUF_
Get rid of these confusing BF_* flags. Now channel naming should clearly
be used everywhere appropriate.
No code was changed, only a renaming was performed. The comments about
channel operations was updated.
diff --git a/include/types/channel.h b/include/types/channel.h
index 224d0da..2ef3b3e 100644
--- a/include/types/channel.h
+++ b/include/types/channel.h
@@ -27,25 +27,25 @@
#include <common/buffer.h>
#include <types/stream_interface.h>
-/* The BF_* macros designate Channel Flags (originally "Buffer Flags"), which
- * may be ORed in the bit field member 'flags' in struct channel. Here we have
- * several types of flags :
+/* The CF_* macros designate Channel Flags, which may be ORed in the bit field
+ * member 'flags' in struct channel. Here we have several types of flags :
*
- * - pure status flags, reported by the lower layer, which must be cleared
+ * - pure status flags, reported by the data layer, which must be cleared
* before doing further I/O :
- * BF_*_NULL, BF_*_PARTIAL
+ * CF_*_NULL, CF_*_PARTIAL
*
- * - pure status flags, reported by mid-layer, which must also be cleared
- * before doing further I/O :
- * BF_*_TIMEOUT, BF_*_ERROR
+ * - pure status flags, reported by stream-interface layer, which must also
+ * be cleared before doing further I/O :
+ * CF_*_TIMEOUT, CF_*_ERROR
*
- * - read-only indicators reported by lower levels :
- * BF_STREAMER, BF_STREAMER_FAST
+ * - read-only indicators reported by lower data levels :
+ * CF_STREAMER, CF_STREAMER_FAST
*
- * - write-once status flags reported by the mid-level : BF_SHUTR, BF_SHUTW
+ * - write-once status flags reported by the stream-interface layer :
+ * CF_SHUTR, CF_SHUTW
*
- * - persistent control flags managed only by higher level :
- * BF_SHUT*_NOW, BF_*_ENA, BF_HIJACK
+ * - persistent control flags managed only by application level :
+ * CF_SHUT*_NOW, CF_*_ENA, CF_HIJACK
*
* The flags have been arranged for readability, so that the read and write
* bits have the same position in a byte (read being the lower byte and write
@@ -53,30 +53,30 @@
* 'write' indicates the direction from the channel to the stream interface.
*/
-#define BF_READ_NULL 0x000001 /* last read detected on producer side */
-#define BF_READ_PARTIAL 0x000002 /* some data were read from producer */
-#define BF_READ_TIMEOUT 0x000004 /* timeout while waiting for producer */
-#define BF_READ_ERROR 0x000008 /* unrecoverable error on producer side */
-#define BF_READ_ACTIVITY (BF_READ_NULL|BF_READ_PARTIAL|BF_READ_ERROR)
+#define CF_READ_NULL 0x00000001 /* last read detected on producer side */
+#define CF_READ_PARTIAL 0x00000002 /* some data were read from producer */
+#define CF_READ_TIMEOUT 0x00000004 /* timeout while waiting for producer */
+#define CF_READ_ERROR 0x00000008 /* unrecoverable error on producer side */
+#define CF_READ_ACTIVITY (CF_READ_NULL|CF_READ_PARTIAL|CF_READ_ERROR)
-/* unused: 0x000010 */
-#define BF_SHUTR 0x000020 /* producer has already shut down */
-#define BF_SHUTR_NOW 0x000040 /* the producer must shut down for reads ASAP */
-#define BF_READ_NOEXP 0x000080 /* producer should not expire */
+/* unused: 0x00000010 */
+#define CF_SHUTR 0x00000020 /* producer has already shut down */
+#define CF_SHUTR_NOW 0x00000040 /* the producer must shut down for reads ASAP */
+#define CF_READ_NOEXP 0x00000080 /* producer should not expire */
-#define BF_WRITE_NULL 0x000100 /* write(0) or connect() succeeded on consumer side */
-#define BF_WRITE_PARTIAL 0x000200 /* some data were written to the consumer */
-#define BF_WRITE_TIMEOUT 0x000400 /* timeout while waiting for consumer */
-#define BF_WRITE_ERROR 0x000800 /* unrecoverable error on consumer side */
-#define BF_WRITE_ACTIVITY (BF_WRITE_NULL|BF_WRITE_PARTIAL|BF_WRITE_ERROR)
+#define CF_WRITE_NULL 0x00000100 /* write(0) or connect() succeeded on consumer side */
+#define CF_WRITE_PARTIAL 0x00000200 /* some data were written to the consumer */
+#define CF_WRITE_TIMEOUT 0x00000400 /* timeout while waiting for consumer */
+#define CF_WRITE_ERROR 0x00000800 /* unrecoverable error on consumer side */
+#define CF_WRITE_ACTIVITY (CF_WRITE_NULL|CF_WRITE_PARTIAL|CF_WRITE_ERROR)
-/* unused: 0x001000 */
-#define BF_SHUTW 0x002000 /* consumer has already shut down */
-#define BF_SHUTW_NOW 0x004000 /* the consumer must shut down for writes ASAP */
-#define BF_AUTO_CLOSE 0x008000 /* producer can forward shutdown to other side */
+/* unused: 0x00001000 */
+#define CF_SHUTW 0x00002000 /* consumer has already shut down */
+#define CF_SHUTW_NOW 0x00004000 /* the consumer must shut down for writes ASAP */
+#define CF_AUTO_CLOSE 0x00008000 /* producer can forward shutdown to other side */
-/* When either BF_SHUTR_NOW or BF_HIJACK is set, it is strictly forbidden for
- * the producer to alter the buffer contents. When BF_SHUTW_NOW is set, the
+/* When either CF_SHUTR_NOW or CF_HIJACK is set, it is strictly forbidden for
+ * the producer to alter the buffer contents. When CF_SHUTW_NOW is set, the
* consumer is free to perform a shutw() when it has consumed the last contents,
* otherwise the session processor will do it anyway.
*
@@ -103,33 +103,34 @@
* detected on the consumer side.
*/
-#define BF_STREAMER 0x010000 /* the producer is identified as streaming data */
-#define BF_STREAMER_FAST 0x020000 /* the consumer seems to eat the stream very fast */
+#define CF_STREAMER 0x00010000 /* the producer is identified as streaming data */
+#define CF_STREAMER_FAST 0x00020000 /* the consumer seems to eat the stream very fast */
-#define BF_HIJACK 0x040000 /* the producer is temporarily replaced by ->hijacker */
-#define BF_ANA_TIMEOUT 0x080000 /* the analyser timeout has expired */
-#define BF_READ_ATTACHED 0x100000 /* the read side is attached for the first time */
-#define BF_KERN_SPLICING 0x200000 /* kernel splicing desired for this channel */
-#define BF_READ_DONTWAIT 0x400000 /* wake the task up after every read (eg: HTTP request) */
-#define BF_AUTO_CONNECT 0x800000 /* consumer may attempt to establish a new connection */
+#define CF_HIJACK 0x00040000 /* the producer is temporarily replaced by ->hijacker */
+#define CF_ANA_TIMEOUT 0x00080000 /* the analyser timeout has expired */
+#define CF_READ_ATTACHED 0x00100000 /* the read side is attached for the first time */
+#define CF_KERN_SPLICING 0x00200000 /* kernel splicing desired for this channel */
+#define CF_READ_DONTWAIT 0x00400000 /* wake the task up after every read (eg: HTTP request) */
+#define CF_AUTO_CONNECT 0x00800000 /* consumer may attempt to establish a new connection */
-#define BF_DONT_READ 0x1000000 /* disable reading for now */
-#define BF_EXPECT_MORE 0x2000000 /* more data expected to be sent very soon (one-shoot) */
-#define BF_SEND_DONTWAIT 0x4000000 /* don't wait for sending data (one-shoot) */
-#define BF_NEVER_WAIT 0x8000000 /* never wait for sending data (permanent) */
+#define CF_DONT_READ 0x01000000 /* disable reading for now */
+#define CF_EXPECT_MORE 0x02000000 /* more data expected to be sent very soon (one-shoot) */
+#define CF_SEND_DONTWAIT 0x04000000 /* don't wait for sending data (one-shoot) */
+#define CF_NEVER_WAIT 0x08000000 /* never wait for sending data (permanent) */
-#define BF_WAKE_ONCE 0x10000000 /* pretend there is activity on this channel (one-shoot) */
+#define CF_WAKE_ONCE 0x10000000 /* pretend there is activity on this channel (one-shoot) */
+/* unused: 0x20000000, 0x20000000, 0x80000000 */
/* Use these masks to clear the flags before going back to lower layers */
-#define BF_CLEAR_READ (~(BF_READ_NULL|BF_READ_PARTIAL|BF_READ_ERROR|BF_READ_ATTACHED))
-#define BF_CLEAR_WRITE (~(BF_WRITE_NULL|BF_WRITE_PARTIAL|BF_WRITE_ERROR))
-#define BF_CLEAR_TIMEOUT (~(BF_READ_TIMEOUT|BF_WRITE_TIMEOUT|BF_ANA_TIMEOUT))
+#define CF_CLEAR_READ (~(CF_READ_NULL|CF_READ_PARTIAL|CF_READ_ERROR|CF_READ_ATTACHED))
+#define CF_CLEAR_WRITE (~(CF_WRITE_NULL|CF_WRITE_PARTIAL|CF_WRITE_ERROR))
+#define CF_CLEAR_TIMEOUT (~(CF_READ_TIMEOUT|CF_WRITE_TIMEOUT|CF_ANA_TIMEOUT))
/* Masks which define input events for stream analysers */
-#define BF_MASK_ANALYSER (BF_READ_ATTACHED|BF_READ_ACTIVITY|BF_READ_TIMEOUT|BF_ANA_TIMEOUT|BF_WRITE_ACTIVITY|BF_WAKE_ONCE)
+#define CF_MASK_ANALYSER (CF_READ_ATTACHED|CF_READ_ACTIVITY|CF_READ_TIMEOUT|CF_ANA_TIMEOUT|CF_WRITE_ACTIVITY|CF_WAKE_ONCE)
/* Mask for static flags which cause analysers to be woken up when they change */
-#define BF_MASK_STATIC (BF_SHUTR|BF_SHUTW|BF_SHUTR_NOW|BF_SHUTW_NOW)
+#define CF_MASK_STATIC (CF_SHUTR|CF_SHUTW|CF_SHUTR_NOW|CF_SHUTW_NOW)
/* Analysers (channel->analysers).
@@ -164,13 +165,13 @@
/* Magic value to forward infinite size (TCP, ...), used with ->to_forward */
-#define BUF_INFINITE_FORWARD MAX_RANGE(int)
+#define CHN_INFINITE_FORWARD MAX_RANGE(int)
/* needed for a declaration below */
struct session;
struct channel {
- unsigned int flags; /* BF_* */
+ unsigned int flags; /* CF_* */
int rex; /* expiration date for a read, in ticks */
int wex; /* expiration date for a write or connect, in ticks */
int rto; /* read timeout, in ticks */
@@ -188,16 +189,28 @@
struct buffer buf; /* embedded buffer for now, will move */
};
+
+/* Note about the channel structure
-/* Note about the buffer 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.
- The buffer contains two length indicators, one to_forward counter and one
- ->o limit. First, it must be understood that the buffer is in fact
- split in two parts :
- - the visible data (->data, for ->l bytes)
- - the invisible data, typically in kernel buffers forwarded directly from
- the source stream sock to the destination stream sock (->pipe->data
- bytes). Those are used only during forward.
+ 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
@@ -214,19 +227,19 @@
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 and increasing
- ->o. The ->to_forward parameter indicates how many bytes may be fed
- into either data buffer without waking the parent up. The special value
- BUF_INFINITE_FORWARD is never decreased nor increased. The ->o
- parameter says how many bytes may be consumed from the visible buffer. Thus
- it may never exceed ->l. 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 ->w+o, an analyser will not see a
- buffer which has a non-null to_forward with o < l. A producer is
- responsible for raising ->o by min(to_forward, l-o) when it
- injects data into the buffer.
+ 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 consumer is responsible for decreasing ->o when it sends data
+ 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.
@@ -234,11 +247,11 @@
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
- ->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
+ 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 ->o, and that size
- is smaller than ->to_forward, we must update ->o to 1300 to flush the
+ 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().
@@ -255,21 +268,19 @@
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
- ->size - global.maxrewrite + ->to_forward.
+ vuf->size - global.maxrewrite + ->to_forward.
A buffer may contain up to 5 areas :
- - the data waiting to be sent. These data are located between ->w and
- ->w+o ;
+ - 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
- ->w+o and may be up to r-w bytes long. Generally ->lr remains in
- this area ;
- - the data to preserve. They start at the end of the previous one and stop
- at ->r. The limit between the two solely depends on the protocol being
- analysed ; ->lr may be used as a marker.
+ 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 ->r and is up to ->size-l long. It
- may be limited by global.maxrewrite.
- - the reserved are : this is the area which must not be filled and is
+ 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.
*/