Re: [RFA] alloca coding standard

[Nick Duffek <nsd at redhat dot com>]

Thanks for the comments.  Here's an updated patch that I hope addresses
the concerns raised.  In particular:

On 13-Nov-2000, Eli Zaretskii wrote:

>I suggest an index entry here, e.g. "@findex alloca usage".

Agreed.  I also added a @cindex entry.

>I'd suggest to say how much is a "page", at least for a couple of
>popular architectures.

I changed it to "1 page or 512 bytes, whichever is larger" so that
developers needn't know the page size.

>This should be `alloca', not `alloc'.

Whoops, thanks.

>Finally, perhaps something should be said about functions that could
>potentially be called recursively

I added a cautionary sentence about recursive functions.

On 13-Nov-2000, Andrew Cagney wrote:

>I'd suggest first allowing for the discussion which is clarifying all
>the issues to settle down and only after that start looking at something
>recording guidelines for alloca.

After the discussion settles down, I'll resubmit the patch if it still
seems applicable.

On 13-Nov-2000, Fernando Nasser wrote:

>What user command?  The GUI ad other script languages call random functions
>in GDB.  And their command loops may even be in another process!

Good point.  I reworded the documentation to cover more interfaces and to
be less specific about where they call alloca (0).

Nick

[patch follows]

Index: gdb/doc/gdbint.texinfo
===================================================================
diff -up gdb/doc/gdbint.texinfo gdb/doc/gdbint.texinfo
--- gdb/doc/gdbint.texinfo	Mon Nov 13 15:08:57 2000
+++ gdb/doc/gdbint.texinfo	Mon Nov 13 15:08:06 2000
@@ -2854,6 +2854,31 @@ visible to random source files.
 All static functions must be declared in a block near the top of the
 source file.
 
+@subsection Alloca
+@findex alloca
+@cindex alloca
+
+@code{alloca} may be used for allocating up to one page or 512 bytes of
+memory per function call, whichever is larger.
+
+The size limit is a compromise between the benefits of @code{alloca} and
+the risk of stack overflow, which can happen on systems that have
+fixed-length stack regions or bounds on frame sizes.
+
+In deeply recursive functions, a smaller limit may be necessary to avoid
+overflowing the stack.
+
+For systems that use libiberty's @code{alloca} emulation, it is
+important that @code{alloca} be called when the stack is shallow to
+garbage-collect freed space.  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 emulation of @code{alloca}.
+
 @subsection Clean Design
 
 In addition to getting the syntax right, there's the little question of