From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 28643 invoked by alias); 10 Feb 2004 17:31:41 -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 28629 invoked from network); 10 Feb 2004 17:31:39 -0000 Received: from unknown (HELO localhost.redhat.com) (66.30.197.194) by sources.redhat.com with SMTP; 10 Feb 2004 17:31:39 -0000 Received: by localhost.redhat.com (Postfix, from userid 469) id DD6A71A4484; Tue, 10 Feb 2004 12:28:00 -0500 (EST) From: Elena Zannoni MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <16425.5280.824503.7068@localhost.redhat.com> Date: Tue, 10 Feb 2004 17:31:00 -0000 To: eliz@elta.co.il Cc: gdb-patches@sources.redhat.com Subject: [RFA/doco] add obstacks to gdbint.texi X-SW-Source: 2004-02/txt/msg00239.txt.bz2 Eli, I am sure it's not perfect. How do I quote function names, for instance? 2004-02-10 Elena Zannoni * 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