This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
Re: [RFA/doco] add obstacks to gdbint.texi
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