2
linebuf - a dbuf replacement for the New World Order(tm)
4
By Adrian Chadd <adrian@creative.net.au>
6
$Id: linebuf.txt 6 2005-09-10 01:02:21Z nenolod $
12
I could probably learn the dbuf history, but basically its evil. The
13
general idea is that a dbuf holds incoming and outgoing data streams.
14
The trouble is that well.. it was evil. You can check it out by getting
15
the old src/dbuf.c and include/dbuf.h files if you really want.
21
The linebuf system is a replacement for the dbuf code. The general idea here
22
is that the data should be buffered in "lines" rather than just linearly
23
like in the dbuf code. This lends to easier manipulation at a later date
24
(think flushing data lines to a socket, and even "sharing" linebufs to
25
reduce the copying required for one to many delivery.)
27
The linebuf system is broken into two structures, the buf_head and buf_line .
28
buf_head contains the buffer information (queue head/tail, length, allocated
29
length and the write offset for flushing), and buf_line contains the
30
line buffer information (buffer and various flags.)
32
linebuf->terminated is *only* set when a CR/LF combination is received.
34
linebuf->overflow is set if we get more data than we should, and we simply
35
truncate the incoming data.
37
linebuf->flushing is set when we are currently writing the buffer. We should
38
_NEVER_ be appending to a buffer which we're flushing!
40
When you get a buffer through linebuf_get() or write one through
41
linebuf_flush(), it will *always* be terminated with a CR/LF (and a NUL if
48
To use a linebuf, you simply stick a buf_head_t in your structure somewhere.
49
You then use the following routines:
52
linebuf_parse(buf_head_t *bufhead, char *buf, int len)
54
Parse the given buf. This routine does some complex manipulation:
56
- if there is an incomplete buffer at the tail, buf is parsed to try and
57
fill that incomplete buffer
58
- a buffer is completed by a CR/LF/CRLF/LFCR. It accepts everything purely
59
because I wanted to be "liberal in what you accept" ..
60
- If a buffer is terminated, the linebuf is flagged terminated
61
- If more data is trying to be squeezed into the buffer than space LEFT
62
in the buffer, we skip to the next "CRLF", and tag the buffer terminated
64
- We treat multiple runs of CR/LF/CRLF/LFCR as a single CRLF. This is just
65
a little extra goody to stop people sending hundreds of "CRLF"s and creating
67
- The number of lines parsed is returned (so you can implement per-line flood
72
linebuf_put(buf_head_t *bufhead, char *buf, int len)
74
Parse the given buf, ASSUMING it is a single buffer line. This is useful
75
for server-generated messages where you know you have a single line, and
76
you don't want to go through the overhead of parsing the data just for
81
linebuf_get(buf_head_t *bufhead, char *buf, int maxlen)
83
Get a single line from the buffer. This removes data from the head of the
84
buffer. If the first buffer is empty or is not terminated, 0 is returned
85
which indicates that there is no data to parse. Terminated buffers are
86
returned (CR/LF/NUL), and the length INCLUDING the CR/LF/NUL is returned.
87
The buffer is copied and the linebuf is then deallocated.
91
linebuf_flush(int fd, buf_head_t *bufhead)
93
Attempt to flush some data to the given socket. bufhead->writeofs tracks
94
where in the head buffer we currently are. If the buffer is not terminated,
95
-1 is returned with errno == EWOULDBLOCK to simulate a "retry me" condition.
98
linebuf_flush() returns whatever write() returns, and sets (ie doesn't touch
99
after write()) errno accordingly.
103
linebuf_len(buf_head_t *bufhead)
105
Return the length of the buffer, in bytes. This should be used when calculating
106
how big a buffer is for statistics.
110
linebuf_alloclen(buf_head_t *bufhead)
112
Return how big the *allocated* space is. This is much more suitable for
113
anti-flood checking, as someone might be sending a whole bunch of 1-byte
114
linebufs which might not trigger a recvq / sendq limit but might chew up
122
* Remember that the trailing NUL isn't covered in the string length.
128
* all the buffers are a fixed size - here they are current 513 bytes
129
(510 bytes + CR/LF/NUL)
135
* linebuf_flush() should be changed a little so if the buffer isn't
136
terminated, we *dont* retry flushing a buffer until we get more data.
138
* Implement a reference-friendly linebuf to reduce copies ..
added
removed
doc/technical/linebuf.txt
