--- /dev/null
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.TH assoc 3 "23 January 2001" mLib
+.SH NAME
+assoc \- tables indexed by atoms
+.\" @assoc_create
+.\" @assoc_destroy
+.\" @assoc_find
+.\" @assoc_remove
+.\" @assoc_mkiter
+.\" @assoc_next
+.\"
+.\" @ASSOC_ATOM
+.\"
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/assoc.h>"
+
+.BI "void assoc_create(assoc_table *" t );
+.BI "void assoc_destroy(assoc_table *" t );
+
+.BI "void *assoc_find(assoc_table *" t ", atom *" a ", size_t " sz ", unsigned *" f );
+.BI "void assoc_remove(assoc_table *" t ", void *" b );
+
+.BI "atom *ASSOC_ATOM(const void *" p );
+
+.BI "void assoc_mkiter(assoc_iter *" i ", assoc_table *" t );
+.BI "void *assoc_next(assoc_iter *" i );
+.fi
+.SH DESCRIPTION
+An
+.I "association table"
+is a data structure which maps atoms (see
+.BR atom (3))
+to arbitrary values. It works in a similar way to the symbol tables
+implemented by
+.BR sym (3),
+except that it uses atoms rather than blocks of data as keys.
+.PP
+Like
+.BR sym (3),
+it implements an
+.I intrusive
+table: the value structures must include an
+.B assoc_base
+structure.
+.PP
+There are three main data structures:
+.TP
+.B assoc_table
+Keeps track of the information associated with a particular table.
+.TP
+.B assoc_base
+The header which must be attached to the front of all the value objects.
+.TP
+.B assoc_iter
+An iterator object, used for enumerating all of the associations stored
+in the table
+.PP
+All of the above structures should be considered
+.IR opaque :
+don't try looking inside.
+.SS "Creation and destruction"
+The
+.B assoc_table
+object itself needs to be allocated by the caller. It is initialized by
+passing it to the function
+.BR assoc_create .
+After initialization, the table contains no entries.
+.PP
+Initializing an association table involves allocating some memory. If
+this allocation fails, an
+.B EXC_NOMEM
+exception is raised.
+.PP
+When an association table is no longer needed, the memory occupied by
+the values and other maintenance structures can be reclaimed by calling
+.BR assoc_destroy .
+Any bits of user data attached to values should previously have been
+destroyed.
+.SS "Adding, searching and removing"
+Most of the actual work is done by the function
+.BR assoc_find .
+It does both lookup and creation, depending on its arguments. To do its
+job, it needs to know the following bits of information:
+.TP
+.BI "assoc_table *" t
+A pointer to an association table to manipulate.
+.TP
+.BI "atom *" a
+The address of the atom to use as a key.
+.TP
+.BI "size_t " sz
+The size of the value block to allocate if the key could not be found.
+If this is zero, no value is allocated, and a null pointer is returned
+to indicate an unsuccessful lookup.
+.TP
+.BI "unsigned *" f
+The address of a `found' flag to set. This is an output parameter. On
+exit,
+.B assoc_find
+will set the value of
+.BI * f
+to zero if the key could not be found, or nonzero if it was found. This
+can be used to tell whether the value returned has been newly allocated,
+or whether it was already in the table.
+.PP
+A symbol can be removed from the table by calling
+.BR assoc_remove ,
+passing the association table itself, and the value block that needs
+removing.
+.SS "Enquiries about associations"
+Given a pointer
+.I a
+to an association, the expression
+.BI ASSOC_ATOM( a )
+has as its value a poinetr to the atom which is that association's key.
+.SS "Enumerating associations"
+Enumerating the values in an association table is fairly simple.
+Allocate an
+.B assoc_iter
+object from somewhere. Attach it to an association table by calling
+.BR assoc_mkiter ,
+and passing in the addresses of the iterator and the symbol table.
+Then, each call to
+.B assoc_next
+will return a different value from the association table, until all of
+them have been enumerated, at which point,
+.B assoc_next
+returns a null pointer.
+.PP
+It's safe to remove the symbol you've just been returned by
+.BR assoc_next .
+However, it's not safe to remove any other symbol. So don't do that.
+.PP
+When you've finished with an iterator, it's safe to just throw it away.
+You don't need to call any functions beforehand.
+.SH SEE ALSO
+.BR atom (3),
+.BR hash (3),
+.BR sym (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>
--- /dev/null
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.TH atom 3 "21 January 2001" mLib
+.SH NAME
+atom \- atom table manager
+.\" @atom_createtable
+.\" @atom_destroytable
+.\" @atom_intern
+.\" @atom_nintern
+.\" @atom_gensym
+.\" @atom_name
+.\" @atom_len
+.\" @atom_hash
+.\" @atom_mkiter
+.\" @atom_next
+.\"
+.\" @ATOM_GLOBAL
+.\" @INTERN
+.\" @GENSYM
+.\" @ATOM_NAME
+.\" @ATOM_LEN
+.\" @ATOM_HASH
+.\"
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/atom.h>"
+
+.BI "void atom_createtable(atom_table *" t );
+.BI "void atom_destroytable(atom_table *" t );
+
+.BI "atom *atom_intern(atom_table *" t ", const char *" p );
+.BI "atom *atom_nintern(atom_table *" t ", const char *" p ", size_t " n );
+.BI "atom *atom_gensym(atom_table *" t );
+.BI "atom *INTERN(const char *" p );
+.BI "atom *GENSYM;"
+
+.BI "const char *atom_name(const atom *" a );
+.BI "size_t atom_len(const atom *" a );
+.BI "uint32 atom_hash(const atom *" a );
+.BI "const char *ATOM_NAME(const atom *" a );
+.BI "size_t ATOM_LEN(const atom *" a );
+.BI "uint32 ATOM_HASH(const atom *" a );
+
+.BI "void atom_mkiter(atom_iter *" i ", atom_table *" t );
+.BI "atom *atom_next(atom_iter *" i );
+
+.BI "extern atom_table *ATOM_GLOBAL;"
+.fi
+.SH DESCRIPTION
+The
+.B atom
+functions and macros implement a data type similar to immutable strings,
+with an additional property: that the addresses of two atoms from the
+same table are equal if and only if they contain the same text. Atom
+strings don't have to be null-terminated, although the interface is
+simpler if you know that all of your atoms are null-terminated. It's
+also possible to make
+.IR "uninterned atoms" :
+see below.
+.PP
+If a necessary memory allocation fails during an atom operation, the
+exception
+.B EXC_NOMEM
+is raised.
+.PP
+Atoms are useful for speeding up string comparisons, and for saving
+memory when many possibly-identical strings need storing.
+.PP
+There is a global atom table, named
+.BR ATOM_GLOBAL ,
+available for general use. You can initialize your own atom table if
+either you want to ensure that the atoms are not shared with some other
+table, or if you want to be able to free the atoms later. Private atom
+tables have the type
+.BR atom_table ;
+initialize it using the function
+.B atom_createtable
+and free it when you're finished using
+.BR atom_destroytable .
+.SS "Creating atoms from strings"
+The process of making atoms from strings is called
+.IR interning .
+The function
+.B atom_nintern
+takes an atom table, a string, and a length, and returns an atom with
+the same text. If your string is null-terminated, you can instead use
+.B atom_intern
+which has no length argument; if, in addition, you want to use the
+global atom table, you can use the single-argument
+.B INTERN
+macro, which takes just a null-terminated string.
+.PP
+A terminating null byte is always appended to an atom name. This is not
+considered to be a part of the name itself, and does not contribute to
+the atom's length as reported by the
+.B ATOM_LEN
+macro.
+.SS "Uninterned atoms"
+You can make an atom which is guaranteed to be distinct from every other
+atom, and has no sensible text string, by calling
+.BR atom_gensym ,
+passing it the address of your atom table. The macro
+.B GENSYM
+(which doesn't look like a function, and has no parentheses following
+it!) will return a unique atom from the global table. Uninterned atoms
+have a generated name of the form
+.RB ` *gen- \fInnn * '
+where
+.I nnn
+is an atom-table-specific sequence number. This text is there as a
+debugging convenience, and doesn't mean that the uninterned atom has the
+same address as an interned atom with the same text.
+.SS "Other enquiries about atoms"
+Atoms can be interrogated to find their names and hashes. The macro
+.B ATOM_NAME
+returns a pointer to the atom's name (its text);
+.B ATOM_LEN
+returns the length of the atom's name, excluding the terminating null;
+and
+.B ATOM_HASH
+returns the atom's hash value, which is useful if you want to use the
+atom as a key in some other structure. There are lower-case function
+versions of these, which have the same effect. There is little point in
+using the functions.
+.SS "Enumerating atoms"
+You can iterate over the atoms in an atom table. The
+.B atom_mkiter
+function initializes an iterator object to iterate over a particular
+atom table;
+.B atom_next
+returns the next atom from the iterator. Atoms are not returned in any
+particular order.
+.SH SEE ALSO
+.BR assoc (3),
+.BR hash (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>
.BR hash (3).
.PP
The
+.BR atom (3)
+module implements
+.IR atoms ,
+which are essentially strings with the property that two atoms have the
+same address if and only if they have the same text, so they can be used
+for rapid string comparisons. The
+.BR assoc (3)
+module implements a hash table which uses atoms as keys, thus saving
+time spent hashing and comparing hash keys, and the space used for the
+keys.
+.PP
+The
.BR darray (3)
module implements dynamically resizing arrays which support Perl-like
stack operations efficiently.
module implements a `line buffer', which is an object that emits
completed lines of text from an incoming asynchronous data stream. It's
remarkably handy in programs that want to read lines from pipes and
-sockets can't block while waiting for a line-end to arrive.
+sockets can't block while waiting for a line-end to arrive. Similarly,
+the
+.BR pkbuf (3)
+module implements a `packet buffer', which waits for packets of given
+lengths to arrive before dispatching them to a handler.
.PP
The
.BR tv (3)
.BR selbuf (3)
module attaches to the
.B sel
-system and sends an event when lines of text arrive on a file. It's
-useful when reading text from a network connection.
+system and sends an event when lines of text arrive from a file. It's
+useful when reading text from a network connection. Similarly,
+.BR selpk (3)
+sents events when packets of given sizes arrive from a file.
.PP
The
.BR sig (3)
.PP
The
.BR ident (3)
-module provides a nonblocking ident (RFC931) client.
-.PP
-The
+module provides a nonblocking ident (RFC931) client. The
.BR bres (3)
module does background hostname and address resolution.
.SH "SEE ALSO"
.BR alloc (3),
+.BR assoc (3),
+.BR atom (3),
.BR base64 (3),
.BR bits (3),
.BR bres (3),
.BR lbuf (3),
.BR lock (3),
.BR mdwopt (3),
+.BR pkbuf (3),
.BR quis (3),
.BR report (3),
.BR sel (3),
.BR selbuf (3),
+.BR selpk (3),
.BR sig (3),
.BR str (3),
.BR sub (3),
~mdw / mLib / commitdiff