Re: [RFA/doco] add obstacks to gdbint.texi

[Elena Zannoni <ezannoni@redhat.com>]

Eli Zaretskii writes:
 > > From: Elena Zannoni <ezannoni@redhat.com>
 > > Date: Tue, 10 Feb 2004 12:28:00 -0500
 > > 
 > > Eli, I am sure it's not perfect.
 > 
 > Actually, it's quite close.
 > 
 > > How do I quote function names, for instance?
 > 
 > Any programming-language symbol should have the @code markup:
 > @code{xmalloc}, @code{xrealloc}, etc.
 > 
 > > +@cindex libiberty library
 > > +
 > > +The libiberty library provides a set of functions and features that
 > 
 > "libiberty" is (almost) a file name, so it should be in @file, both in
 > the index entry and in the text.
 > 

done

 > > +@value{GDBN} uses various features provided by the libiberty library,
 > > +for instance the memory management functions xfree and xmalloc, and
 > > +the obstack extension.
 > 
 > I would put "obstack" either in @code or in @samp.

all over or just that sentence? I just did the sentence, because in
other places we talk about obstacks in general, not 'obstack' the
name/variable.

 > 
 > > +@subsection obstacks in @value{GDBN}
 > 
 > Please add a @cindex entry here so that people could find the info
 > about obstacks quickly.
 > 
 > > +a stack. Objects (of any nature, size and alignment) are allocated and
 > > +freed in a LIFO fashion on an obstack. (See the libiberty's
 > 
 > "LIFO" is an acronym, so it's better to say "@acronym{LIFO}"; the
 > result after typesetting by TeX will look prettier.
 > 

done

 > Finally, there are many places where there's only one blank after a
 > dot that ends a sentence.  Please make that 2 spaces.

Ok, is there something in .emacs that I should set to get this done when
I do an 'esc-q' for instance? 

 > 
 > Last, but certainly not least, thanks for taking time to write this.

Here is the revision:

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.183
diff -u -p -r1.183 gdbint.texinfo
--- gdbint.texinfo      26 Jan 2004 20:52:13 -0000      1.183
+++ gdbint.texinfo      10 Feb 2004 19:50:14 -0000
@@ -4678,6 +4678,65 @@ library because it's also used in binuti
 @section mmalloc
  
 @section libiberty
+@cindex @code{libiberty} library
+
+The @code{libiberty} library provides a set of functions and features that
+integrate and improve on functionality found in modern operating
+systems.  Broadly speaking, such features can be divided into three
+groups: supplemental functions (functions that may be missing in some
+environments and operating systems), replacement functions (providing
+a uniform and easier to use interface for commonly used standard
+functions), and extensions (which provide additional functionality
+beyond standard functions).
+
+@value{GDBN} uses various features provided by the @code{libiberty} library,
+for instance the memory management functions @code{xfree} and @code{xmalloc}, and
+the @samp{obstack} extension.
+
+@subsection obstacks in @value{GDBN}
+@cindex obstacks
+
+The obstack mechanism provides a convenient way to allocate and free
+chunks of memory.  Each obstack is a pool of memory that is managed
+like a stack.  Objects (of any nature, size and alignment) are
+allocated and freed in a @acronym{LIFO} fashion on an obstack (see
+@code{libiberty}'s documenatation for a more detailed explanation of
+obstacks).
+
+The most noticeable use of the obstacks in @value{GDBN} is in object
+files.  There is an obstack associated with each internal
+representation of an object file.  Lots of things get allocated on
+these obstacks: dictionary entries, blocks, blockvectors, symbols,
+minimal symbols, types, vectors of fundamental types, class fields of
+types, object files section lists, object files section offets lists,
+line tables, symbol tables, partial symbol tables, string tables,
+symbol table private data, macros tables, debug information sections
+and entries, import and export lists (som), unwind information (hppa),
+dwarf2 location expressions data.  Plus various strings such as
+directory names strings, debug format strings, names of types.
+
+An essential and convenient property of all data on obstacks is that
+memory for it gets allocated (with obstack_alloc) at various times
+during a debugging sesssion, but it is released all at once using the
+obstack_free function.  The obstack_free function takes a pointer to
+where in the stack it must start the deletion from (much like the
+cleanup chains have a pointer to where to start the cleanups).
+Because of the stack like structure of the obstacks, this allows to
+free only a top portion of the obstack.  There are a few instances in
+@value{GDBN} where such thing happens.  Calls to obstack_free are done
+after some local data is allocated to the obstack.  Only the local data
+is deleted from the obstack.  Of course this assumes that nothing
+between the obstack_alloc and the obstack_free allocates anything else
+on the same obstack.  For this reason it is best and safest to use
+temporary obstacks.
+
+Releasing the whole obstack is also not safe per se.  It is safe only
+under the condition that we know the obstacks memory is no longer
+needed.  In @value{GDBN} we get rid of the obstacks only when we get
+rid of the whole objfile(s), for instance upon reading a new symbol
+file.
+
+
  
 @section gnu-regex
 @cindex regular expressions library