From cededfbe1efb12e68c1defe008f1d69d97f4cbe3 Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Sat, 17 Jun 2000 10:34:55 +0000 Subject: [PATCH] Update for new arena management. Organization: Straylight/Edgeware From: mdw --- man/.cvsignore | 9 ++++ man/alloc.3 | 72 ++++++++++++++----------------- man/arena.3 | 113 +++++++++++++++++++++++++++++++++++++++++++++++++ man/crc32.3 | 2 +- man/darray.3 | 5 ++- man/dstr.3 | 9 ++++ man/lbuf.3 | 22 +++++++--- man/selbuf.3 | 13 +++++- 8 files changed, 196 insertions(+), 49 deletions(-) create mode 100644 man/arena.3 diff --git a/man/.cvsignore b/man/.cvsignore index f70943b..a13a764 100644 --- a/man/.cvsignore +++ b/man/.cvsignore @@ -1,3 +1,6 @@ +A_ALLOC.3 +A_FREE.3 +A_REALLOC.3 CATCH.3 CREATE.3 DA.3 @@ -96,6 +99,12 @@ TV_SUBL.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 diff --git a/man/alloc.3 b/man/alloc.3 index bc345f1..ed3a036 100644 --- a/man/alloc.3 +++ b/man/alloc.3 @@ -9,9 +9,15 @@ alloc \- mLib low-level memory allocation .nf .B "#include " +.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 @@ -19,52 +25,38 @@ memory is available, an .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 diff --git a/man/arena.3 b/man/arena.3 new file mode 100644 index 0000000..d7631c2 --- /dev/null +++ b/man/arena.3 @@ -0,0 +1,113 @@ +.\" -*-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 " + +.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, diff --git a/man/crc32.3 b/man/crc32.3 index 3d2dead..79a6bd9 100644 --- a/man/crc32.3 +++ b/man/crc32.3 @@ -15,7 +15,7 @@ crc32 \- calculate 32-bit CRC .nf .B "#include " -.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 diff --git a/man/darray.3 b/man/darray.3 index c5d9366..3b796b1 100644 --- a/man/darray.3 +++ b/man/darray.3 @@ -121,7 +121,7 @@ be used to prevent multiple declarations, e.g., .VS #ifndef FOO_V # define FOO_V - DA_DECL(foo_v, foo) + DA_DECL(foo_v, foo); #endif .VE The macro @@ -284,7 +284,8 @@ and 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) diff --git a/man/dstr.3 b/man/dstr.3 index 998e3f3..959a7aa 100644 --- a/man/dstr.3 +++ b/man/dstr.3 @@ -103,6 +103,7 @@ typedef struct dstr { 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 @@ -159,6 +160,14 @@ element is zero) and the nonexistent string (a null pointer). Any 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 diff --git a/man/lbuf.3 b/man/lbuf.3 index beab46f..e238a8c 100644 --- a/man/lbuf.3 +++ b/man/lbuf.3 @@ -15,9 +15,11 @@ lbuf \- split lines out of asynchronously received blocks .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 @@ -55,11 +57,21 @@ function to which the line buffer should pass completed lines of text. 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. diff --git a/man/selbuf.3 b/man/selbuf.3 index bedae52..e15beaa 100644 --- a/man/selbuf.3 +++ b/man/selbuf.3 @@ -11,11 +11,13 @@ selbuf \- line-buffering input selector .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 @@ -31,7 +33,7 @@ what gets considered to be a line of text and what doesn't, and 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 . @@ -88,6 +90,15 @@ queued up from the last I/O operation: it doesn't necessarily wait for 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]