From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 29141 invoked by alias); 10 Feb 2004 19:51:26 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 29133 invoked from network); 10 Feb 2004 19:51:25 -0000 Received: from unknown (HELO localhost.redhat.com) (66.30.197.194) by sources.redhat.com with SMTP; 10 Feb 2004 19:51:25 -0000 Received: by localhost.redhat.com (Postfix, from userid 469) id 506351A4484; Tue, 10 Feb 2004 14:47:41 -0500 (EST) From: Elena Zannoni MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <16425.13661.237505.892571@localhost.redhat.com> Date: Tue, 10 Feb 2004 19:51:00 -0000 To: Eli Zaretskii Cc: Elena Zannoni , gdb-patches@sources.redhat.com Subject: Re: [RFA/doco] add obstacks to gdbint.texi In-Reply-To: <6654-Tue10Feb2004210510+0200-eliz@elta.co.il> References: <16425.5280.824503.7068@localhost.redhat.com> <6654-Tue10Feb2004210510+0200-eliz@elta.co.il> X-SW-Source: 2004-02/txt/msg00253.txt.bz2 Eli Zaretskii writes: > > From: Elena Zannoni > > 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