+A_ALLOC.3
+A_FREE.3
+A_REALLOC.3
CATCH.3
CREATE.3
DA.3
U16.3
U32.3
U8.3
+a_alloc.3
+a_free.3
+a_realloc.3
+arena_fakemalloc.3
+arena_global.3
+arena_stdlib.3
base64_decode.3
base64_encode.3
base64_init.3
.nf
.B "#include <mLib/alloc.h>"
+.BI "void *x_alloc(size_t " sz );
+.BI "char *x_strdup(const char *" s );
+.BI "void *x_realloc(void *" p ", size_t " sz );
+.BI "void x_free(void *" p );
+
.BI "void *xmalloc(size_t " sz );
.BI "void *xrealloc(void *" p ", size_t " sz );
.BI "char *xstrdup(const char *" s );
+.BI "void xfree(void *" p );
.fi
.SH DESCRIPTION
These functions allocate and return blocks of memory. If insufficient
.B EXC_NOMEM
exception is raised.
.PP
-The
-.B xmalloc
-and
-.B xrealloc
-functions are veneers over the standard
-.BR malloc (3)
+The functions
+.BR x_alloc ,
+.BR x_realloc ,
+.BR x_strdup
and
-.BR realloc (3)
-functions.
-.B xmalloc
-allocates a block of
-.I sz
-bytes and returns a pointer to the base of the block;
-.B xrealloc
-is given a pointer
-.I p
-to a block of memory, and returns the address of a new block of size
-.I sz
-bytes with the same contents as the original one (either truncated, if
-the new block is smaller, or padded with rubbish at the end if bigger).
+.BR x_free
+work with a given arena (see
+.BR arena (3)).
+.B x_alloc
+allocates a block of a given size;
+.B x_realloc
+resizes an allocated block;
+.B x_strdup
+allocates a copy of a null-terminated string; and
+.B x_free
+releases a block.
+.RB ( x_free
+is supplied for orthogonality's sake: it's equivalent to calling the
+.BR A_FREE (3)
+macro.)
.PP
The
-.B xstrdup
-function allocates and returns a block of memory containing a copy of
-the null-terminated string
-.IR p .
-The block is just large enough for the string and its null terminator.
-.PP
-The memory blocks allocated by these functions can be released by
-calling the standard
-.BR free (3)
-function.
-.SH "RETURN VALUE"
-The
.BR xmalloc ,
-.B xrealloc
+.BR xrealloc ,
+.BR xstrdup
and
-.B xstrdup
-functions return pointers to the blocks they allocated. They do not
-return if a block couldn't be allocated; instead, the exception
-.B EXC_NOMEM
-is raised.
+.BR xfree
+macros are provided as a convenient interface to failsafe memory
+allocation from the current arena
+.BR arena_global (3).
.SH "SEE ALSO"
-.BR malloc (3),
-.BR realloc (3),
-.BR free (3),
+.BR arena (3),
.BR exc (3),
.BR mLib (3).
.SH AUTHOR
--- /dev/null
+.\" -*-nroff-*-
+.TH arena 3 "3 June 2000" mLib
+.SH "NAME"
+arena \- control of memory allocation
+.\" @arena_global
+.\" @arena_stdlib
+.\" @arena_fakemalloc
+.\" @a_alloc
+.\" @a_realloc
+.\" @a_free
+.\" @A_ALLOC
+.\" @A_REALLOC
+.\" @A_FREE
+.SH "SYNOPSIS"
+.nf
+.B "#include <mLib/arena.h>"
+
+.BI "arena *arena_global;"
+.BI "arena arena_stdlib;"
+
+.BI "void *arena_fakerealloc(arena *" a ", void *" p ", size_t " sz );
+
+.BI "void *a_alloc(arena *" a ", size_t " sz );
+.BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz );
+.BI "void a_free(arena *" a );
+
+.BI "void *A_ALLOC(arena *" a ", size_t " sz );
+.BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz );
+.BI "void A_FREE(arena *" a );
+.fi
+.SH "DESCRIPTION"
+An
+.I arena
+is a place from which blocks of memory may be allocated and freed. The
+basic
+.B mLib
+library provides a single standard arena,
+.BR arena_stdlib ,
+which uses the usual
+.BR malloc (3)
+and
+.BR free (3)
+calls. The global variable
+.B arena_global
+is a pointer to a `current' arena, which is a good choice to use if
+you can't think of anything better.
+.PP
+The macros
+.BR A_ALLOC ,
+.B A_REALLOC
+and
+.B A_FREE
+behave like the standard C functions
+.BR malloc (3),
+.BR realloc (3)
+and
+.BR free (3),
+allocating, resizing and releasing blocks from a given arena. There are
+function-call equivalents with lower-case names too. For a more
+convenient interface to memory allocation, see
+.BR alloc (3).
+.PP
+.SS "Defining new arenas"
+An
+.B arena
+is a structure containing a single member,
+.BR ops ,
+which is a pointer to a structure of type
+.BR arena_ops .
+The
+.B arena
+structure may be followed in memory by data which is used by the arena's
+manager to maintain its state.
+.PP
+The
+.B arena_ops
+table contains function pointers which are called to perform various
+memory allocation tasks:
+.TP
+.BI "void *(*" alloc ")(arena *" a ", size_t " sz );
+Allocates a block of memory, of at least
+.I sz
+bytes in size, appropriately aligned, and returns its address.
+.TP
+.BI "void *(*" realloc ")(arena *" a ", void *" p ", size_t " sz );
+Resizes the block pointed to by
+.IR p ,
+so that it is at least
+.I sz
+bytes long. You can use
+.B arena_fakerealloc
+here, to fake resizing by allocating, copying and freeing, if your arena
+doesn't make doing something more efficient easy.
+.TP
+.BI "void (*" free ")(arena *" a ", void *" p );
+Frees the block pointed to by
+.IR p .
+.TP
+.BI "void (*" purge ")(arena *" a );
+Frees all blocks in the arena. Used when the arena is being destroyed.
+.PP
+The behaviour of the
+.IR alloc ,
+.I realloc
+and
+.I free
+calls with respect to null pointers and zero-sized blocks is as
+specified by the ANSI C standard.
+.SH "SEE ALSO"
+.BR alloc (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>
.nf
.B "#include <mLib/crc32.h>"
-.BI "int crc32(unsigned long " crc ", const void *" buf ", size_t " sz );
+.BI "uint32 crc32(uint32 " crc ", const void *" buf ", size_t " sz );
.BI CRC32( result ", " crc ", " buf ", " sz )
.fi
.SH DESCRIPTION
.VS
#ifndef FOO_V
# define FOO_V
- DA_DECL(foo_v, foo)
+ DA_DECL(foo_v, foo);
#endif
.VE
The macro
respectively, except that they interpret the sign of their second
arguments in the opposite way. This is useful if the argument is
unsigned (e.g., if it's based on
-.BR DA_LEN ). There are unsafed versions of both these macros too.
+.BR DA_LEN ).
+There are unsafe versions of both these macros too.
.SS "Stack operations"
Dynamic arrays support Perl-like stack operations. Given an array
(pointer)
char *buf; /* Pointer to string buffer */
size_t sz; /* Size of the buffer */
size_t len; /* Length of the string */
+ arena *a; /* Pointer to arena */
} dstr;
.VE
The
whose
.B len
is zero is an empty string.
+.PP
+The
+.I a
+member refers to the arena from which the string's buffer has been
+allocated. Immediately after creation, this is set to be
+.BR arena_stdlib (3);
+you can set it to point to any other arena of your choice before the
+buffer is allocated.
.SS "Creation and destruction"
The caller is responsible for allocating the
.B dstr
.BI "void lbuf_close(lbuf *" b );
.BI "size_t lbuf_free(lbuf *" b ", char **" p );
.BI "void lbuf_snarf(lbuf *" b ", const void *" p ", size_t " sz );
+.BI "void lbuf_setsize(lbuf *" b ", size_t " sz );
.BI "void lbuf_init(lbuf *" b ,
.BI " void (*" func ")(char *" s ", void *" p ),
.BI " void *" p );
+.BI "void lbuf_destroy(lbuf *" b );
.fi
.SH "DESCRIPTION"
The declarations in
A pointer argument to be passed to the function when a completed line of
text arrives.
.PP
-Since the line buffer requires no memory except for the actual
-.B lbuf
-object, and doesn't hook itself onto anything else, it can just be
-thrown away when you don't want it any more. No explicit finalization
-is required.
+The amount of memory set aside for reading lines is configurable. It
+may be set by calling
+.B lbuf_setsize
+at any time when the buffer is empty. The default limit is 256 bytes.
+Lines longer than the limit are truncated. 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 line buffer must be destroyed after use by calling
+.BR lbuf_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.
.BI "void selbuf_enable(selbuf *" b );
.BI "void selbuf_disable(selbuf *" b );
+.BI "void selbuf_setsize(selbuf *" b ", size_t " sz );
.BI "void selbuf_init(selbuf *" b ,
.BI " sel_state *" s ,
.BI " int " fd ,
.BI " void (*" func ")(char *" s ", void *" p ),
.BI " void *" p );
+.BI "void selbuf_destroy(selbuf *" b );
.fi
.SH DESCRIPTION
The
exact rules about what your line handling function should and shouldn't
do.
.PP
-All the data for a
+The data for a
.B selbuf
selector is stored in an object of type
.BR selbuf .
the next
.B sel_select
call.
+.PP
+The line buffer has a finite amount of memory for reading strings. The
+size of this buffer is set by calling
+.B selbuf_setsize
+with the requested size. The default buffer size is 256 bytes.
+.PP
+When it's finished with, a line buffer selector must be destroyed by
+calling
+.BR selbuf_destroy .
.SH "SEE ALSO"
.BR lbuf (3),
.BR sel (3),
~mdw / mLib / commitdiff