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

[Nick Duffek <nsd at redhat dot com>]

On 14-Dec-2000, Eli Zaretskii wrote:

>In an @itemize list, the @item needs to be alone on its line

FYI, there are several locations in gdb.texinfo and gdbint.texinfo that
don't follow that convention.

Here's the patch with the changes you requested.  I'll commit it unless my
alloca(0) patch doesn't get approved, in which case I'll have to make a
minor change.

Nick

Index: gdb/doc/gdbint.texinfo
===================================================================
diff -up gdb/doc/gdbint.texinfo gdb/doc/gdbint.texinfo
--- gdb/doc/gdbint.texinfo	Thu Dec 14 11:43:26 2000
+++ gdb/doc/gdbint.texinfo	Thu Dec 14 11:42:45 2000
@@ -2867,6 +2867,67 @@ 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 @samp{alloca (0)} is called
+periodically.  In addition, @value{GDBN} calls @samp{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