.SS "Creation and destruction"
The caller is responsible for allocating the
.B dstr
-structure. It can be initialized in any of the following ways:
+structure. It can be initialized:
.hP \*o
-Using the macro
+using the macro
.B DSTR_INIT
-as an initializer in the declaration of the object.
+as an initializer in the declaration of the object,
.hP \*o
-Passing its address to the
+passing its address to the
.B dstr_create
-function.
+function, or
.hP \*o
-Passing its address to the (equivalent)
+passing its address to the (equivalent)
.B DCREATE
macro.
.PP
The implementation is not complete. Many decisions have been left to
the user, including:
.hP \*o
-How keys should be represented, hashed and compared.
+how keys should be represented, hashed and compared;
.hP \*o
-How objects contained within the table should be allocated.
+how objects contained within the table should be allocated; and
.hP \*o
-When the hashtable should be extended.
+when the hashtable should be extended.
.PP
A complete hashtable implementation will need to take the above
decisions. If you just want a prepackaged solution, see
.PP
Clearly, since an
.B lbuf_flush
-call can emit more than one line, so it must be aware that the line
-handler isn't interested in any more lines. However, this fact must
-also be signalled to the higher-level object so that it can detach
-itself from its data source.
+call can emit more than one line, it must be aware that the line handler
+isn't interested in any more lines. 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 line buffer
exports one of its structure members,
.I pk
to a packet buffer structure; a pointer
.I p
- to a chunk of data to read; and the size
+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.
The
.B pkbuf_snarf
function is trivially implemented in terms of the more complex
-.B pkbuf_free / pkbuf_flush
+.BR pkbuf_free / pkbuf_flush
interface.
.SS "Packet breaking and the handler function"
The function
.PP
Clearly, since an
.B pkbuf_flush
-call can emit more than one packet, so it must be aware that the packet
+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.
.BI "void selpk_disable(selpk *" pk );
.BI "void selpk_want(selpk *" pk ", size_t " sz );
.BI "void selpk_init(selpk *" pk ", sel_state *" s ", int " fd ,
-.BI " pkbuf *" func ", void *" p );
+.BI " pkbuf_func *" func ", void *" p );
.BI "void selpk_destroy(selpk *" b );
.fi
.SH DESCRIPTION