[RFA] doc/gdbint.texinfo: memory allocation section

[Nick Duffek <nsd at redhat dot com>]

I didn't get any complaints about the memory allocation section I proposed
in the gdb list (thread subject "Re: alloca() in gdbint.texi"), so I'm
submitting it for approval.

I changed it slightly to reflect my recent discovery that the "x"
functions (xmalloc etc.) come from both gdb/defs.h and
include/libiberty.h.

ChangeLog:

	* gdbint.texinfo (Memory Allocation): New subsection.

Okay to apply?

Nick

Index: gdb/doc/gdbint.texinfo
===================================================================
diff -up gdb/doc/gdbint.texinfo gdb/doc/gdbint.texinfo
--- gdb/doc/gdbint.texinfo	Wed Dec 13 12:57:49 2000
+++ gdb/doc/gdbint.texinfo	Wed Dec 13 12:57:40 2000
@@ -2867,6 +2867,61 @@ visible to random source files.
 All static functions must be declared in a block near the top of the
 source file.
 
+@subsection Memory Allocation
+@cindex memory allocation
+@cindex heap allocation
+@cindex stack allocation
+@findex malloc
+@findex xmalloc
+@findex realloc
+@findex xrealloc
+@findex alloca
+
+Heap memory must be allocated using @code{xmalloc}, @code{xstrdup},
+@code{xasprintf}, and other @code{x} functions declared
+in @file{gdb/defs.h} and @file{include/libiberty.h}.  These functions
+have the following advantages over their C library counterparts:
+
+@itemize @bullet
+@item The size parameter to @code{xmalloc}, @code{xcalloc}, and
+@code{xrealloc} may be 0.
+@item The pointer parameter to @code{xrealloc} may be NULL.
+@item Out-of-memory conditions are handled gracefully.
+@end itemize
+
+In addition, small amounts of memory may be allocated from the stack
+using @code{alloca}, which is useful for avoiding cleanup chains in
+functions that might return nonlocally.
+
+However, @code{alloca} should be used sparingly because:
+
+@itemize @bullet
+@item Stack space often is limited.  For example, the default stack
+limit is 8 megabytes on many UNIXes, 2 megabytes on Digital UNIX, and
+512 kilobytes in DJGPP-compiled programs.
+@item Some systems impose limits on stack frame sizes.  It is rumored
+that AIX limits stack frames to 64 kilobytes, and other systems may
+have problems with frames larger than a page.
+@item Out-of-stack conditions are not handled gracefully.
+@end itemize
+
+As a rule of thumb, @code{alloca} should be used only for allocations
+guaranteed to be less than a kilobyte or so.
+
+On some systems, @value{GDBN} uses libiberty's @code{alloca} emulation
+because a native @code{alloca} is not available.  To support those
+systems, it is important that @value{GDBN} garbage-collect freed space
+by calling @code{alloca} when the stack is shallow.  Toward that end,
+each interface to the @value{GDBN} core --- for example, GDBTK, libgdb,
+and the text console --- should ensure that @code{alloca (0)} is called
+periodically.  In addition, @value{GDBN} calls @code{alloca (0)} once
+per inferior wait.
+
+Because @value{GDBN} and other GNU programs use @code{alloca}, they are
+not portable to systems that neither provide a native @code{alloca} nor
+support libiberty's @code{alloca} emulation.  Since GCC provides a
+native @code{alloca}, such systems are rare.
+
 @subsection Clean Design
 
 In addition to getting the syntax right, there's the little question of