[RFA/doco] add obstacks to gdbint.texi

[RFA/doco] add obstacks to gdbint.texi

[Elena Zannoni]

Eli, I am sure it's not perfect. How do I quote function names, for
instance?


2004-02-10  Elena Zannoni  <ezannoni@redhat.com>

	* gdbint.texinfo (Support Libraries): Add doco about obstacks and
	minimal information about libiberty.


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 17:27:58 -0000
@@ -4678,6 +4678,63 @@ library because it's also used in binuti
 @section mmalloc
  
 @section libiberty
+@cindex libiberty library
+
+The 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 libiberty library,
+for instance the memory management functions xfree and xmalloc, and
+the obstack extension.
+
+@subsection obstacks in @value{GDBN}
+
+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 LIFO fashion on an obstack. (See the 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

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

[Eli Zaretskii]

> 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.

> +@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.

> +@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.

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

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

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

[Daniel Jacobowitz]

Thanks for doing this!

On Tue, Feb 10, 2004 at 12:28:00PM -0500, Elena Zannoni wrote:
> +@value{GDBN} uses various features provided by the libiberty library,
> +for instance the memory management functions xfree and xmalloc, and
> +the obstack extension.

Actually, we don't use xfree and xmalloc from libiberty; we use our own
copy in utils.c that behave similarly.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

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

[Elena Zannoni]

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

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

[Eli Zaretskii]

> From: Elena Zannoni <ezannoni@redhat.com>
> Date: Tue, 10 Feb 2004 14:47:41 -0500
>  > 
>  > I would put "obstack" either in @code or in @samp.
> 
> all over or just that sentence?

All over, I think.

>  > 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? 

It does that for me by default.  If it doesn't for you, perhaps you
have sentence-end-double-space set to nil somehow.

> +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).

obstack_free, obstack_alloc, etc. are functions, so they need @code.

Otherwise, fine; thanks.

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

[Elena Zannoni]

Daniel Jacobowitz writes:
 > Thanks for doing this!
 > 
 > On Tue, Feb 10, 2004 at 12:28:00PM -0500, Elena Zannoni wrote:
 > > +@value{GDBN} uses various features provided by the libiberty library,
 > > +for instance the memory management functions xfree and xmalloc, and
 > > +the obstack extension.
 > 
 > Actually, we don't use xfree and xmalloc from libiberty; we use our own
 > copy in utils.c that behave similarly.
 > 

duh, true. libiberty doesn't even have xfree.  So what do we use from
libiberty? demangler, floatformat, obstack, getopt, what else?

elena

 > -- 
 > Daniel Jacobowitz
 > MontaVista Software                         Debian GNU/Linux Developer

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

[Daniel Jacobowitz]

On Tue, Feb 10, 2004 at 03:02:58PM -0500, Elena Zannoni wrote:
> Daniel Jacobowitz writes:
>  > Thanks for doing this!
>  > 
>  > On Tue, Feb 10, 2004 at 12:28:00PM -0500, Elena Zannoni wrote:
>  > > +@value{GDBN} uses various features provided by the libiberty library,
>  > > +for instance the memory management functions xfree and xmalloc, and
>  > > +the obstack extension.
>  > 
>  > Actually, we don't use xfree and xmalloc from libiberty; we use our own
>  > copy in utils.c that behave similarly.
>  > 
> 
> duh, true. libiberty doesn't even have xfree.  So what do we use from
> libiberty? demangler, floatformat, obstack, getopt, what else?

I know I added a use of lbasename.  Oh, and make_relative_prefix.  I
think we use buildargv somewhere but that might just be in the
simulators.  Concat probably has snuck in somewhere.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

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

[Elena Zannoni]

Eli Zaretskii writes:
 > > From: Elena Zannoni <ezannoni@redhat.com>
 > > Date: Tue, 10 Feb 2004 14:47:41 -0500
 > >  > 
 > >  > I would put "obstack" either in @code or in @samp.
 > > 
 > > all over or just that sentence?
 > 
 > All over, I think.
 > 
 > >  > 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? 
 > 
 > It does that for me by default.  If it doesn't for you, perhaps you
 > have sentence-end-double-space set to nil somehow.

Something screwy with my emacs, no doubt. But the variable is set
correctly.

 > 
 > > +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).
 > 
 > obstack_free, obstack_alloc, etc. are functions, so they need @code.
 > 

ok. Also corrected the lie about xmalloc/xfree.

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 20:37:22 -0000
@@ -4678,6 +4678,66 @@ 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 C++ demangler, the @acronym{IEEE} floating
+format support functions, the input options parser @samp{getopt}, the
+@samp{obstack} extension, and other functions.
+
+@subsection @code{obstacks} in @value{GDBN}
+@cindex @code{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
+@code{obstacks}).
+
+The most noticeable use of the @code{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 @code{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 @code{obstacks} is
+that memory for it gets allocated (with @code{obstack_alloc}) at
+various times during a debugging sesssion, but it is released all at
+once using the @code{obstack_free} function.  The @code{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
+@code{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 @code{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
+@code{obstack_alloc} and the @code{obstack_free} allocates anything
+else on the same obstack.  For this reason it is best and safest to
+use temporary @code{obstacks}.
+
+Releasing the whole obstack is also not safe per se.  It is safe only
+under the condition that we know the @code{obstacks} memory is no
+longer needed.  In @value{GDBN} we get rid of the @code{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

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

[Eli Zaretskii]

> From: Elena Zannoni <ezannoni@redhat.com>
> Date: Tue, 10 Feb 2004 15:34:41 -0500
>  > > 
>  > > Ok, is there something in .emacs that I should set to get this done when
>  > > I do an 'esc-q' for instance? 
>  > 
>  > It does that for me by default.  If it doesn't for you, perhaps you
>  > have sentence-end-double-space set to nil somehow.
> 
> Something screwy with my emacs, no doubt. But the variable is set
> correctly.

Then perhaps you have some non-default setting for sentence-end.

> ok. Also corrected the lie about xmalloc/xfree.
> 
> Index: gdbint.texinfo

This version is fine, I have only one more suggestion:

> +@value{GDBN} uses various features provided by the @code{libiberty}
> +library, for instance the C++ demangler, the @acronym{IEEE} floating

The "C++" thingie will look prettier in the printed manual if you
spell it as "C@t{++}", as then TeX will typeset the "++" part with a
typewriter face, as it does with the C operator "++" in a code
fragment.

Thanks.

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

[Elena Zannoni]

Eli Zaretskii writes:
 > 
 > > +@value{GDBN} uses various features provided by the @code{libiberty}
 > > +library, for instance the C++ demangler, the @acronym{IEEE} floating
 > 
 > The "C++" thingie will look prettier in the printed manual if you
 > spell it as "C@t{++}", as then TeX will typeset the "++" part with a
 > typewriter face, as it does with the C operator "++" in a code
 > fragment.
 > 
 > Thanks.


OK, done and committed.

and BTW, there are other occurrences of C++ in the docs, since I am at
it, should I do a pass and change them all?

elena

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

[Eli Zaretskii]

> From: Elena Zannoni <ezannoni@redhat.com>
> Date: Wed, 11 Feb 2004 10:37:28 -0500
> 
> and BTW, there are other occurrences of C++ in the docs, since I am at
> it, should I do a pass and change them all?

Please do.  TIA.