memory.texi

一个C源代码分析器

@item void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
Add @var{size} uninitialized bytes to a growing object.
@xref{Growing Objects}.

@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
Add @var{size} bytes, copied from @var{address}, to a growing object.
@xref{Growing Objects}.

@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
Add @var{size} bytes, copied from @var{address}, to a growing object,
and then add another byte containing a null character.  @xref{Growing
Objects}.

@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char})
Add one byte containing @var{data-char} to a growing object.
@xref{Growing Objects}.

@item void *obstack_finish (struct obstack *@var{obstack-ptr})
Finalize the object that is growing and return its permanent address.
@xref{Growing Objects}.

@item int obstack_object_size (struct obstack *@var{obstack-ptr})
Get the current size of the currently growing object.  @xref{Growing
Objects}.

@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
Add @var{size} uninitialized bytes to a growing object without checking
that there is enough room.  @xref{Extra Fast Growing}.

@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char})
Add one byte containing @var{data-char} to a growing object without
checking that there is enough room.  @xref{Extra Fast Growing}.

@item int obstack_room (struct obstack *@var{obstack-ptr})
Get the amount of room now available for growing the current object.
@xref{Extra Fast Growing}.

@item int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
The mask used for aligning the beginning of an object.  This is an
lvalue.  @xref{Obstacks Data Alignment}.

@item int obstack_chunk_size (struct obstack *@var{obstack-ptr})
The size for allocating chunks.  This is an lvalue.  @xref{Obstack Chunks}.

@item void *obstack_base (struct obstack *@var{obstack-ptr})
Tentative starting address of the currently growing object.
@xref{Status of an Obstack}.

@item void *obstack_next_free (struct obstack *@var{obstack-ptr})
Address just after the end of the currently growing object.
@xref{Status of an Obstack}.
@end table

@node Variable Size Automatic
@section Automatic Storage with Variable Size
@cindex automatic freeing
@cindex @code{alloca} function
@cindex automatic storage with variable size

The function @code{alloca} supports a kind of half-dynamic allocation in
which blocks are allocated dynamically but freed automatically.

Allocating a block with @code{alloca} is an explicit action; you can
allocate as many blocks as you wish, and compute the size at run time.  But
all the blocks are freed when you exit the function that @code{alloca} was
called from, just as if they were automatic variables declared in that
function.  There is no way to free the space explicitly.

The prototype for @code{alloca} is in @file{stdlib.h}.  This function is
a BSD extension.
@pindex stdlib.h

@comment stdlib.h
@comment GNU, BSD
@deftypefun {void *} alloca (size_t @var{size});
The return value of @code{alloca} is the address of a block of @var{size}
bytes of storage, allocated in the stack frame of the calling function.
@end deftypefun

Do not use @code{alloca} inside the arguments of a function call---you
will get unpredictable results, because the stack space for the
@code{alloca} would appear on the stack in the middle of the space for
the function arguments.  An example of what to avoid is @code{foo (x,
alloca (4), y)}.
@c This might get fixed in future versions of GCC, but that won't make
@c it safe with compilers generally.

@menu
* Alloca Example::              Example of using @code{alloca}.
* Advantages of Alloca::        Reasons to use @code{alloca}.
* Disadvantages of Alloca::     Reasons to avoid @code{alloca}.
* GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
				 method of allocating dynamically and
				 freeing automatically.
@end menu

@node Alloca Example
@subsection @code{alloca} Example

As an example of use of @code{alloca}, here is a function that opens a file
name made from concatenating two argument strings, and returns a file
descriptor or minus one signifying failure:

@smallexample
int
open2 (char *str1, char *str2, int flags, int mode)
@{
  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  strcpy (name, str1);
  strcat (name, str2);
  return open (name, flags, mode);
@}
@end smallexample

@noindent
Here is how you would get the same results with @code{malloc} and
@code{free}:

@smallexample
int
open2 (char *str1, char *str2, int flags, int mode)
@{
  char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
  int desc;
  if (name == 0)
    fatal ("virtual memory exceeded");
  strcpy (name, str1);
  strcat (name, str2);
  desc = open (name, flags, mode);
  free (name);
  return desc;
@}
@end smallexample

As you can see, it is simpler with @code{alloca}.  But @code{alloca} has
other, more important advantages, and some disadvantages.

@node Advantages of Alloca
@subsection Advantages of @code{alloca}

Here are the reasons why @code{alloca} may be preferable to @code{malloc}:

@itemize @bullet
@item
Using @code{alloca} wastes very little space and is very fast.  (It is
open-coded by the GNU C compiler.)

@item
Since @code{alloca} does not have separate pools for different sizes of
block, space used for any size block can be reused for any other size.
@code{alloca} does not cause storage fragmentation.

@item
@cindex longjmp
Nonlocal exits done with @code{longjmp} (@pxref{Non-Local Exits})
automatically free the space allocated with @code{alloca} when they exit
through the function that called @code{alloca}.  This is the most
important reason to use @code{alloca}.

To illustrate this, suppose you have a function
@code{open_or_report_error} which returns a descriptor, like
@code{open}, if it succeeds, but does not return to its caller if it
fails.  If the file cannot be opened, it prints an error message and
jumps out to the command level of your program using @code{longjmp}.
Let's change @code{open2} (@pxref{Alloca Example}) to use this
subroutine:@refill

@smallexample
int
open2 (char *str1, char *str2, int flags, int mode)
@{
  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  strcpy (name, str1);
  strcat (name, str2);
  return open_or_report_error (name, flags, mode);
@}
@end smallexample

@noindent
Because of the way @code{alloca} works, the storage it allocates is
freed even when an error occurs, with no special effort required.

By contrast, the previous definition of @code{open2} (which uses
@code{malloc} and @code{free}) would develop a storage leak if it were
changed in this way.  Even if you are willing to make more changes to
fix it, there is no easy way to do so.
@end itemize

@node Disadvantages of Alloca
@subsection Disadvantages of @code{alloca}

@cindex @code{alloca} disadvantages
@cindex disadvantages of @code{alloca}
These are the disadvantages of @code{alloca} in comparison with
@code{malloc}:

@itemize @bullet
@item
If you try to allocate more storage than the machine can provide, you
don't get a clean error message.  Instead you get a fatal signal like
the one you would get from an infinite recursion; probably a
segmentation violation (@pxref{Program Error Signals}).

@item
Some non-GNU systems fail to support @code{alloca}, so it is less
portable.  However, a slower emulation of @code{alloca} written in C
is available for use on systems with this deficiency.
@end itemize

@node GNU C Variable-Size Arrays
@subsection GNU C Variable-Size Arrays
@cindex variable-sized arrays

In GNU C, you can replace most uses of @code{alloca} with an array of
variable size.  Here is how @code{open2} would look then:

@smallexample
int open2 (char *str1, char *str2, int flags, int mode)
@{
  char name[strlen (str1) + strlen (str2) + 1];
  strcpy (name, str1);
  strcat (name, str2);
  return open (name, flags, mode);
@}
@end smallexample

But @code{alloca} is not always equivalent to a variable-sized array, for
several reasons:

@itemize @bullet
@item
A variable size array's space is freed at the end of the scope of the
name of the array.  The space allocated with @code{alloca}
remains until the end of the function.

@item
It is possible to use @code{alloca} within a loop, allocating an
additional block on each iteration.  This is impossible with
variable-sized arrays.
@end itemize

@strong{Note:} If you mix use of @code{alloca} and variable-sized arrays
within one function, exiting a scope in which a variable-sized array was
declared frees all blocks allocated with @code{alloca} during the
execution of that scope.


@node Relocating Allocator
@section Relocating Allocator

@cindex relocating memory allocator
Any system of dynamic memory allocation has overhead: the amount of
space it uses is more than the amount the program asks for.  The
@dfn{relocating memory allocator} achieves very low overhead by moving
blocks in memory as necessary, on its own initiative.

@menu
* Relocator Concepts::		How to understand relocating allocation.
* Using Relocator::		Functions for relocating allocation.
@end menu

@node Relocator Concepts
@subsection Concepts of Relocating Allocation

@ifinfo
The @dfn{relocating memory allocator} achieves very low overhead by
moving blocks in memory as necessary, on its own initiative.
@end ifinfo

When you allocate a block with @code{malloc}, the address of the block
never changes unless you use @code{realloc} to change its size.  Thus,
you can safely store the address in various places, temporarily or
permanently, as you like.  This is not safe when you use the relocating
memory allocator, because any and all relocatable blocks can move
whenever you allocate memory in any fashion.  Even calling @code{malloc}
or @code{realloc} can move the relocatable blocks.

@cindex handle
For each relocatable block, you must make a @dfn{handle}---a pointer
object in memory, designated to store the address of that block.  The
relocating allocator knows where each block's handle is, and updates the
address stored there whenever it moves the block, so that the handle
always points to the block.  Each time you access the contents of the
block, you should fetch its address anew from the handle.

To call any of the relocating allocator functions from a signal handler
is almost certainly incorrect, because the signal could happen at any
time and relocate all the blocks.  The only way to make this safe is to
block the signal around any access to the contents of any relocatable
block---not a convenient mode of operation.  @xref{Nonreentrancy}.

@node Using Relocator
@subsection Allocating and Freeing Relocatable Blocks

@pindex malloc.h
In the descriptions below, @var{handleptr} designates the address of the
handle.  All the functions are declared in @file{malloc.h}; all are GNU
extensions.

@comment malloc.h
@comment GNU
@deftypefun {void *} r_alloc (void **@var{handleptr}, size_t @var{size})
This function allocates a relocatable block of size @var{size}.  It
stores the block's address in @code{*@var{handleptr}} and returns
a non-null pointer to indicate success.

If @code{r_alloc} can't get the space needed, it stores a null pointer
in @code{*@var{handleptr}}, and returns a null pointer.
@end deftypefun

@comment malloc.h
@comment GNU
@deftypefun void r_alloc_free (void **@var{handleptr})
This function is the way to free a relocatable block.  It frees the
block that @code{*@var{handleptr}} points to, and stores a null pointer
in @code{*@var{handleptr}} to show it doesn't point to an allocated
block any more.
@end deftypefun

@comment malloc.h
@comment GNU
@deftypefun {void *} r_re_alloc (void **@var{handleptr}, size_t @var{size})
The function @code{r_re_alloc} adjusts the size of the block that
@code{*@var{handleptr}} points to, making it @var{size} bytes long.  It
stores the address of the resized block in @code{*@var{handleptr}} and
returns a non-null pointer to indicate success.

If enough memory is not available, this function returns a null pointer
and does not modify @code{*@var{handleptr}}.
@end deftypefun

@node Memory Warnings
@section Memory Usage Warnings
@cindex memory usage warnings
@cindex warnings of memory almost full

@pindex malloc.c
You can ask for warnings as the program approaches running out of memory
space, by calling @code{memory_warnings}.  This tells @code{malloc} to
check memory usage every time it asks for more memory from the operating
system.  This is a GNU extension declared in @file{malloc.h}.

@comment malloc.h
@comment GNU
@deftypefun void memory