From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8877 invoked by alias); 10 Feb 2004 20:38:21 -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 8864 invoked from network); 10 Feb 2004 20:38:20 -0000 Received: from unknown (HELO localhost.redhat.com) (66.30.197.194) by sources.redhat.com with SMTP; 10 Feb 2004 20:38:20 -0000 Received: by localhost.redhat.com (Postfix, from userid 469) id A8EE01A4484; Tue, 10 Feb 2004 15:34:41 -0500 (EST) From: Elena Zannoni MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <16425.16481.598965.602145@localhost.redhat.com> Date: Tue, 10 Feb 2004 20:38: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: <7494-Tue10Feb2004220655+0200-eliz@elta.co.il> References: <16425.5280.824503.7068@localhost.redhat.com> <6654-Tue10Feb2004210510+0200-eliz@elta.co.il> <16425.13661.237505.892571@localhost.redhat.com> <7494-Tue10Feb2004220655+0200-eliz@elta.co.il> X-SW-Source: 2004-02/txt/msg00259.txt.bz2 Eli Zaretskii writes: > > From: Elena Zannoni > > 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