@@@ wip type definitions in manpage synopses

[mLib] / buf / pkbuf.3

.\" -*-nroff-*-
.TH pkbuf 3 "16 July 2000" "Straylight/Edgeware" "mLib utilities library"
.SH "NAME"
pkbuf \- split packets out of asynchronously received blocks
.\" @pkbuf_flush
.\" @pkbuf_close
.\" @pkbuf_free
.\" @pkbuf_snarf
.\" @pkbuf_want
.\" @pkbuf_init
.\" @pkbuf_destroy
.SH "SYNOPSIS"
.nf
.B "#include <mLib/pkbuf.h>"

.B "enum {"
.B "\h'4n'PKBUF_ENABLE = ..."
.B "};"

.B "typedef struct {"
.B "\h'4n'unsigned f;"
.B "\h'4n'..."
.B "} pkbuf;"

.ds mT \fBtypedef void pkbuf_func(
.B "\*(mToctet *" b ", size_t " sz ", pkbuf *" p ,
.BI "\h'\w'\*(mT'u'size_t *" keep ", void *" p );

.BI "void pkbuf_flush(pkbuf *" pk ", octet *" p ", size_t " len );
.BI "void pkbuf_close(pkbuf *" pk );
.BI "size_t pkbuf_free(pkbuf *" pk ", octet **" p );
.BI "void pkbuf_snarf(pkbuf *" pk ", const void *" p ", size_t " sz );
.BI "void pkbuf_want(pkbuf *" pk ", size_t " want );
.BI "void pkbuf_init(pkbuf *" pk ", pkbuf_func *" func ", void *" p );
.BI "void pkbuf_destroy(pkbuf *" pk );
.fi
.SH "DESCRIPTION"
The declarations in
.B <mLib/pkbuf.h>
implement a
.IR "packet buffer" .
Given unpredictably-sized chunks of data, the packet buffer extracts
completed packets of data, with sizes ascertained by a handler
function.
.PP
The state of a packet buffer is stored in an object of type
.BR pkbuf .
This is a structure which must be allocated by the caller.  The
structure should normally be considered opaque (see the section on
.B Disablement
for an exception to this).
.SS "Initialization and finalization"
The function
.B pkbuf_init
initializes a packet buffer ready for use.  It is given three arguments:
.TP
.BI "pkbuf *" pk
A pointer to the block of memory to use for the packet buffer.  The packet
buffer will allocate memory to store incoming data automatically: this
structure just contains bookkeeping information.
.TP
.BI "pkbuf_func *" func
The
.I packet-handler
function to which the packet buffer should pass packets of data when
they're received.  See
.B "Packet breaking and the handler function"
below.
.TP
.BI "void *" p
A pointer argument to be passed to the function when a packet arrives.
.PP
By default, the buffer is
allocated from the current arena,
.BR arena_global (3);
this may be changed by altering the buffer's
.B a
member to refer to a different arena at any time when the buffer is
unallocated.
.PP
A packet buffer must be destroyed after use by calling
.BR pkbuf_destroy ,
passing it the address of the buffer block.
.SS "Inserting data into the buffer"
There are two interfaces for inserting data into the buffer.  One's much
simpler than the other, although it's less expressive.
.PP
The simple interface is
.BR pkbuf_snarf .
This function is given three arguments: a pointer
.I pk
to a packet buffer structure; a pointer
.I p
to a chunk of data to read; and the size
.I sz
of the chunk of data.  The data is pushed through the packet buffer and
any complete packets are passed on to the packet handler.
.PP
The complex interface is the pair of functions
.I pkbuf_free
and
.IR pkbuf_flush .
.PP
The
.B pkbuf_free
function returns the address and size of a free portion of the packet
buffer's memory into which data may be written.  The function is passed
the address
.I pk
of the packet buffer.  Its result is the size of the free area, and it
writes the base address of this free space to the location pointed to by
the argument
.IR p .
The caller's data must be written to ascending memory locations starting
at
.BI * p
and no data may be written beyond the end of the free space.  However,
it isn't necessary to completely fill the buffer.
.PP
Once the free area has had some data written to it,
.B pkbuf_flush
is called to examine the new data and break it into packets.  This is
given three arguments:
.TP
.BI "pkbuf *" pk
The address of the packet buffer.
.TP
.BI "octet *" p
The address at which the new data has been written.  This must be the
base address returned from
.BR pkbuf_free .
.TP
.BI "size_t " len
The number of bytes which have been written to the buffer.
.PP
The
.B pkbuf_flush
function breaks the new data into packets as described below, and passes
each one in turn to the packet-handler function.
.PP
The
.B pkbuf_snarf
function is trivially implemented in terms of the more complex
.BR pkbuf_free / pkbuf_flush
interface.
.SS "Packet breaking and the handler function"
The function
.B pkbuf_want
is used to inform the packet buffer of the expected length of the next
packet.  It is given the pointer
.I pk
to the packet buffer and a size
.I sz
of the packet.
.PP
When enough data has arrived, the packet-handler function is called.  It
is passed:
.TP
.BI "octet *" b
A pointer to the packet data in the buffer, or zero to signify
end-of-file.
.TP
.BI "size_t " sz
The size of the packet, as previously configured via
.BR pkbuf_want .
.TP
.BI "pkbuf *" pk
A pointer to the packet buffer.
.TP
.BI "size_t *" keep
A location in which to store the number of bytes of the current packet
to be retained.  The bytes kept are from the end of the current packet:
if you want to keep bytes from the beginning of the packet, you should
move them into the right place.
.TP
.BI "void *" p
The pointer which was set up in the call to
.BR pkbuf_init .
.PP
.SS "Flushing the remaining data"
When the client program knows that there's no more data arriving (for
example, an end-of-file condition exists on its data source) it should
call the function
.BR pkbuf_close .
This will call the handler one final time with a null pointer to inform
it of the end-of-file.
.SS "Disablement"
The packet buffer is intended to be used in higher-level program
objects, such as the packet selector described in
.BR selpk (3).
Unfortunately, a concept from this high level needs to exist at the
packet buffer level, which complicates the description somewhat.  The
idea is that, when a packet-handler attached to some higher-level object
decides that it's read enough, it can
.I disable
the object so that it doesn't see any more data.
.PP
Clearly, since an
.B pkbuf_flush
call can emit more than one packet, it must be aware that the packet
handler isn't interested in any more packet.  However, this fact must
also be signalled to the higher-level object so that it can detach
itself from its data source.
.PP
Rather than invent some complex interface for this, the packet buffer
exports one of its structure members, a flags words called
.BR f .
A higher-level object wishing to disable the packet buffer simply clears
the bit
.B PKBUF_ENABLE
in this flags word.
.PP
Disabling a buffer causes an immediate return from
.BR pkbuf_flush .
However, it is not permitted for the functions
.B pkbuf_flush
or
.B pkbuf_close
to be called on a disabled buffer.  (This condition isn't checked for;
it'll just do the wrong thing.)  Furthermore, the
.B pkbuf_snarf
function does not handle disablement at all, because it would complicate
the interface so much that it wouldn't have any advantage over the more
general
.BR pkbuf_free / pkbuf_flush .
.SH "SEE ALSO"
.BR lbuf (3),
.BR selpk (3),
.BR mLib (3).
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>