1169695Skan@node Obstacks,Licenses,Functions,Top 2169695Skan@chapter Obstacks 3169695Skan@cindex obstacks 4169695Skan 5169695SkanAn @dfn{obstack} is a pool of memory containing a stack of objects. You 6169695Skancan create any number of separate obstacks, and then allocate objects in 7169695Skanspecified obstacks. Within each obstack, the last object allocated must 8169695Skanalways be the first one freed, but distinct obstacks are independent of 9169695Skaneach other. 10169695Skan 11169695SkanAside from this one constraint of order of freeing, obstacks are totally 12169695Skangeneral: an obstack can contain any number of objects of any size. They 13169695Skanare implemented with macros, so allocation is usually very fast as long as 14169695Skanthe objects are usually small. And the only space overhead per object is 15169695Skanthe padding needed to start each object on a suitable boundary. 16169695Skan 17169695Skan@menu 18169695Skan* Creating Obstacks:: How to declare an obstack in your program. 19169695Skan* Preparing for Obstacks:: Preparations needed before you can 20169695Skan use obstacks. 21169695Skan* Allocation in an Obstack:: Allocating objects in an obstack. 22169695Skan* Freeing Obstack Objects:: Freeing objects in an obstack. 23169695Skan* Obstack Functions:: The obstack functions are both 24169695Skan functions and macros. 25169695Skan* Growing Objects:: Making an object bigger by stages. 26169695Skan* Extra Fast Growing:: Extra-high-efficiency (though more 27169695Skan complicated) growing objects. 28169695Skan* Status of an Obstack:: Inquiries about the status of an obstack. 29169695Skan* Obstacks Data Alignment:: Controlling alignment of objects in obstacks. 30169695Skan* Obstack Chunks:: How obstacks obtain and release chunks; 31169695Skan efficiency considerations. 32169695Skan* Summary of Obstacks:: 33169695Skan@end menu 34169695Skan 35169695Skan@node Creating Obstacks 36169695Skan@section Creating Obstacks 37169695Skan 38169695SkanThe utilities for manipulating obstacks are declared in the header 39169695Skanfile @file{obstack.h}. 40169695Skan@pindex obstack.h 41169695Skan 42169695Skan@comment obstack.h 43169695Skan@comment GNU 44169695Skan@deftp {Data Type} {struct obstack} 45169695SkanAn obstack is represented by a data structure of type @code{struct 46169695Skanobstack}. This structure has a small fixed size; it records the status 47169695Skanof the obstack and how to find the space in which objects are allocated. 48169695SkanIt does not contain any of the objects themselves. You should not try 49169695Skanto access the contents of the structure directly; use only the functions 50169695Skandescribed in this chapter. 51169695Skan@end deftp 52169695Skan 53169695SkanYou can declare variables of type @code{struct obstack} and use them as 54169695Skanobstacks, or you can allocate obstacks dynamically like any other kind 55169695Skanof object. Dynamic allocation of obstacks allows your program to have a 56169695Skanvariable number of different stacks. (You can even allocate an 57169695Skanobstack structure in another obstack, but this is rarely useful.) 58169695Skan 59169695SkanAll the functions that work with obstacks require you to specify which 60169695Skanobstack to use. You do this with a pointer of type @code{struct obstack 61169695Skan*}. In the following, we often say ``an obstack'' when strictly 62169695Skanspeaking the object at hand is such a pointer. 63169695Skan 64169695SkanThe objects in the obstack are packed into large blocks called 65169695Skan@dfn{chunks}. The @code{struct obstack} structure points to a chain of 66169695Skanthe chunks currently in use. 67169695Skan 68169695SkanThe obstack library obtains a new chunk whenever you allocate an object 69169695Skanthat won't fit in the previous chunk. Since the obstack library manages 70169695Skanchunks automatically, you don't need to pay much attention to them, but 71169695Skanyou do need to supply a function which the obstack library should use to 72169695Skanget a chunk. Usually you supply a function which uses @code{malloc} 73169695Skandirectly or indirectly. You must also supply a function to free a chunk. 74169695SkanThese matters are described in the following section. 75169695Skan 76169695Skan@node Preparing for Obstacks 77169695Skan@section Preparing for Using Obstacks 78169695Skan 79169695SkanEach source file in which you plan to use the obstack functions 80169695Skanmust include the header file @file{obstack.h}, like this: 81169695Skan 82169695Skan@smallexample 83169695Skan#include <obstack.h> 84169695Skan@end smallexample 85169695Skan 86169695Skan@findex obstack_chunk_alloc 87169695Skan@findex obstack_chunk_free 88169695SkanAlso, if the source file uses the macro @code{obstack_init}, it must 89169695Skandeclare or define two functions or macros that will be called by the 90169695Skanobstack library. One, @code{obstack_chunk_alloc}, is used to allocate 91169695Skanthe chunks of memory into which objects are packed. The other, 92169695Skan@code{obstack_chunk_free}, is used to return chunks when the objects in 93169695Skanthem are freed. These macros should appear before any use of obstacks 94169695Skanin the source file. 95169695Skan 96169695SkanUsually these are defined to use @code{malloc} via the intermediary 97169695Skan@code{xmalloc} (@pxref{Unconstrained Allocation, , , libc, The GNU C Library Reference Manual}). This is done with 98169695Skanthe following pair of macro definitions: 99169695Skan 100169695Skan@smallexample 101169695Skan#define obstack_chunk_alloc xmalloc 102169695Skan#define obstack_chunk_free free 103169695Skan@end smallexample 104169695Skan 105169695Skan@noindent 106169695SkanThough the memory you get using obstacks really comes from @code{malloc}, 107169695Skanusing obstacks is faster because @code{malloc} is called less often, for 108169695Skanlarger blocks of memory. @xref{Obstack Chunks}, for full details. 109169695Skan 110169695SkanAt run time, before the program can use a @code{struct obstack} object 111169695Skanas an obstack, it must initialize the obstack by calling 112169695Skan@code{obstack_init}. 113169695Skan 114169695Skan@comment obstack.h 115169695Skan@comment GNU 116169695Skan@deftypefun int obstack_init (struct obstack *@var{obstack-ptr}) 117169695SkanInitialize obstack @var{obstack-ptr} for allocation of objects. This 118169695Skanfunction calls the obstack's @code{obstack_chunk_alloc} function. If 119169695Skanallocation of memory fails, the function pointed to by 120169695Skan@code{obstack_alloc_failed_handler} is called. The @code{obstack_init} 121169695Skanfunction always returns 1 (Compatibility notice: Former versions of 122169695Skanobstack returned 0 if allocation failed). 123169695Skan@end deftypefun 124169695Skan 125169695SkanHere are two examples of how to allocate the space for an obstack and 126169695Skaninitialize it. First, an obstack that is a static variable: 127169695Skan 128169695Skan@smallexample 129169695Skanstatic struct obstack myobstack; 130169695Skan@dots{} 131169695Skanobstack_init (&myobstack); 132169695Skan@end smallexample 133169695Skan 134169695Skan@noindent 135169695SkanSecond, an obstack that is itself dynamically allocated: 136169695Skan 137169695Skan@smallexample 138169695Skanstruct obstack *myobstack_ptr 139169695Skan = (struct obstack *) xmalloc (sizeof (struct obstack)); 140169695Skan 141169695Skanobstack_init (myobstack_ptr); 142169695Skan@end smallexample 143169695Skan 144169695Skan@comment obstack.h 145169695Skan@comment GNU 146169695Skan@defvar obstack_alloc_failed_handler 147169695SkanThe value of this variable is a pointer to a function that 148169695Skan@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate 149169695Skanmemory. The default action is to print a message and abort. 150169695SkanYou should supply a function that either calls @code{exit} 151169695Skan(@pxref{Program Termination, , , libc, The GNU C Library Reference Manual}) or @code{longjmp} (@pxref{Non-Local 152169695SkanExits, , , libc, The GNU C Library Reference Manual}) and doesn't return. 153169695Skan 154169695Skan@smallexample 155169695Skanvoid my_obstack_alloc_failed (void) 156169695Skan@dots{} 157169695Skanobstack_alloc_failed_handler = &my_obstack_alloc_failed; 158169695Skan@end smallexample 159169695Skan 160169695Skan@end defvar 161169695Skan 162169695Skan@node Allocation in an Obstack 163169695Skan@section Allocation in an Obstack 164169695Skan@cindex allocation (obstacks) 165169695Skan 166169695SkanThe most direct way to allocate an object in an obstack is with 167169695Skan@code{obstack_alloc}, which is invoked almost like @code{malloc}. 168169695Skan 169169695Skan@comment obstack.h 170169695Skan@comment GNU 171169695Skan@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size}) 172169695SkanThis allocates an uninitialized block of @var{size} bytes in an obstack 173169695Skanand returns its address. Here @var{obstack-ptr} specifies which obstack 174169695Skanto allocate the block in; it is the address of the @code{struct obstack} 175169695Skanobject which represents the obstack. Each obstack function or macro 176169695Skanrequires you to specify an @var{obstack-ptr} as the first argument. 177169695Skan 178169695SkanThis function calls the obstack's @code{obstack_chunk_alloc} function if 179169695Skanit needs to allocate a new chunk of memory; it calls 180169695Skan@code{obstack_alloc_failed_handler} if allocation of memory by 181169695Skan@code{obstack_chunk_alloc} failed. 182169695Skan@end deftypefun 183169695Skan 184169695SkanFor example, here is a function that allocates a copy of a string @var{str} 185169695Skanin a specific obstack, which is in the variable @code{string_obstack}: 186169695Skan 187169695Skan@smallexample 188169695Skanstruct obstack string_obstack; 189169695Skan 190169695Skanchar * 191169695Skancopystring (char *string) 192169695Skan@{ 193169695Skan size_t len = strlen (string) + 1; 194169695Skan char *s = (char *) obstack_alloc (&string_obstack, len); 195169695Skan memcpy (s, string, len); 196169695Skan return s; 197169695Skan@} 198169695Skan@end smallexample 199169695Skan 200169695SkanTo allocate a block with specified contents, use the function 201169695Skan@code{obstack_copy}, declared like this: 202169695Skan 203169695Skan@comment obstack.h 204169695Skan@comment GNU 205169695Skan@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 206169695SkanThis allocates a block and initializes it by copying @var{size} 207169695Skanbytes of data starting at @var{address}. It calls 208169695Skan@code{obstack_alloc_failed_handler} if allocation of memory by 209169695Skan@code{obstack_chunk_alloc} failed. 210169695Skan@end deftypefun 211169695Skan 212169695Skan@comment obstack.h 213169695Skan@comment GNU 214169695Skan@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 215169695SkanLike @code{obstack_copy}, but appends an extra byte containing a null 216169695Skancharacter. This extra byte is not counted in the argument @var{size}. 217169695Skan@end deftypefun 218169695Skan 219169695SkanThe @code{obstack_copy0} function is convenient for copying a sequence 220169695Skanof characters into an obstack as a null-terminated string. Here is an 221169695Skanexample of its use: 222169695Skan 223169695Skan@smallexample 224169695Skanchar * 225169695Skanobstack_savestring (char *addr, int size) 226169695Skan@{ 227169695Skan return obstack_copy0 (&myobstack, addr, size); 228169695Skan@} 229169695Skan@end smallexample 230169695Skan 231169695Skan@noindent 232169695SkanContrast this with the previous example of @code{savestring} using 233169695Skan@code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}). 234169695Skan 235169695Skan@node Freeing Obstack Objects 236169695Skan@section Freeing Objects in an Obstack 237169695Skan@cindex freeing (obstacks) 238169695Skan 239169695SkanTo free an object allocated in an obstack, use the function 240169695Skan@code{obstack_free}. Since the obstack is a stack of objects, freeing 241169695Skanone object automatically frees all other objects allocated more recently 242169695Skanin the same obstack. 243169695Skan 244169695Skan@comment obstack.h 245169695Skan@comment GNU 246169695Skan@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) 247169695SkanIf @var{object} is a null pointer, everything allocated in the obstack 248169695Skanis freed. Otherwise, @var{object} must be the address of an object 249169695Skanallocated in the obstack. Then @var{object} is freed, along with 250169695Skaneverything allocated in @var{obstack} since @var{object}. 251169695Skan@end deftypefun 252169695Skan 253169695SkanNote that if @var{object} is a null pointer, the result is an 254169695Skanuninitialized obstack. To free all memory in an obstack but leave it 255169695Skanvalid for further allocation, call @code{obstack_free} with the address 256169695Skanof the first object allocated on the obstack: 257169695Skan 258169695Skan@smallexample 259169695Skanobstack_free (obstack_ptr, first_object_allocated_ptr); 260169695Skan@end smallexample 261169695Skan 262169695SkanRecall that the objects in an obstack are grouped into chunks. When all 263169695Skanthe objects in a chunk become free, the obstack library automatically 264169695Skanfrees the chunk (@pxref{Preparing for Obstacks}). Then other 265169695Skanobstacks, or non-obstack allocation, can reuse the space of the chunk. 266169695Skan 267169695Skan@node Obstack Functions 268169695Skan@section Obstack Functions and Macros 269169695Skan@cindex macros 270169695Skan 271169695SkanThe interfaces for using obstacks may be defined either as functions or 272169695Skanas macros, depending on the compiler. The obstack facility works with 273169695Skanall C compilers, including both @w{ISO C} and traditional C, but there are 274169695Skanprecautions you must take if you plan to use compilers other than GNU C. 275169695Skan 276169695SkanIf you are using an old-fashioned @w{non-ISO C} compiler, all the obstack 277169695Skan``functions'' are actually defined only as macros. You can call these 278169695Skanmacros like functions, but you cannot use them in any other way (for 279169695Skanexample, you cannot take their address). 280169695Skan 281169695SkanCalling the macros requires a special precaution: namely, the first 282169695Skanoperand (the obstack pointer) may not contain any side effects, because 283169695Skanit may be computed more than once. For example, if you write this: 284169695Skan 285169695Skan@smallexample 286169695Skanobstack_alloc (get_obstack (), 4); 287169695Skan@end smallexample 288169695Skan 289169695Skan@noindent 290169695Skanyou will find that @code{get_obstack} may be called several times. 291169695SkanIf you use @code{*obstack_list_ptr++} as the obstack pointer argument, 292169695Skanyou will get very strange results since the incrementation may occur 293169695Skanseveral times. 294169695Skan 295169695SkanIn @w{ISO C}, each function has both a macro definition and a function 296169695Skandefinition. The function definition is used if you take the address of the 297169695Skanfunction without calling it. An ordinary call uses the macro definition by 298169695Skandefault, but you can request the function definition instead by writing the 299169695Skanfunction name in parentheses, as shown here: 300169695Skan 301169695Skan@smallexample 302169695Skanchar *x; 303169695Skanvoid *(*funcp) (); 304169695Skan/* @r{Use the macro}. */ 305169695Skanx = (char *) obstack_alloc (obptr, size); 306169695Skan/* @r{Call the function}. */ 307169695Skanx = (char *) (obstack_alloc) (obptr, size); 308169695Skan/* @r{Take the address of the function}. */ 309169695Skanfuncp = obstack_alloc; 310169695Skan@end smallexample 311169695Skan 312169695Skan@noindent 313169695SkanThis is the same situation that exists in @w{ISO C} for the standard library 314169695Skanfunctions. @xref{Macro Definitions, , , libc, The GNU C Library Reference Manual}. 315169695Skan 316169695Skan@strong{Warning:} When you do use the macros, you must observe the 317169695Skanprecaution of avoiding side effects in the first operand, even in @w{ISO C}. 318169695Skan 319169695SkanIf you use the GNU C compiler, this precaution is not necessary, because 320169695Skanvarious language extensions in GNU C permit defining the macros so as to 321169695Skancompute each argument only once. 322169695Skan 323169695Skan@node Growing Objects 324169695Skan@section Growing Objects 325169695Skan@cindex growing objects (in obstacks) 326169695Skan@cindex changing the size of a block (obstacks) 327169695Skan 328169695SkanBecause memory in obstack chunks is used sequentially, it is possible to 329169695Skanbuild up an object step by step, adding one or more bytes at a time to the 330169695Skanend of the object. With this technique, you do not need to know how much 331169695Skandata you will put in the object until you come to the end of it. We call 332169695Skanthis the technique of @dfn{growing objects}. The special functions 333169695Skanfor adding data to the growing object are described in this section. 334169695Skan 335169695SkanYou don't need to do anything special when you start to grow an object. 336169695SkanUsing one of the functions to add data to the object automatically 337169695Skanstarts it. However, it is necessary to say explicitly when the object is 338169695Skanfinished. This is done with the function @code{obstack_finish}. 339169695Skan 340169695SkanThe actual address of the object thus built up is not known until the 341169695Skanobject is finished. Until then, it always remains possible that you will 342169695Skanadd so much data that the object must be copied into a new chunk. 343169695Skan 344169695SkanWhile the obstack is in use for a growing object, you cannot use it for 345169695Skanordinary allocation of another object. If you try to do so, the space 346169695Skanalready added to the growing object will become part of the other object. 347169695Skan 348169695Skan@comment obstack.h 349169695Skan@comment GNU 350169695Skan@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size}) 351169695SkanThe most basic function for adding to a growing object is 352169695Skan@code{obstack_blank}, which adds space without initializing it. 353169695Skan@end deftypefun 354169695Skan 355169695Skan@comment obstack.h 356169695Skan@comment GNU 357169695Skan@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size}) 358169695SkanTo add a block of initialized space, use @code{obstack_grow}, which is 359169695Skanthe growing-object analogue of @code{obstack_copy}. It adds @var{size} 360169695Skanbytes of data to the growing object, copying the contents from 361169695Skan@var{data}. 362169695Skan@end deftypefun 363169695Skan 364169695Skan@comment obstack.h 365169695Skan@comment GNU 366169695Skan@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size}) 367169695SkanThis is the growing-object analogue of @code{obstack_copy0}. It adds 368169695Skan@var{size} bytes copied from @var{data}, followed by an additional null 369169695Skancharacter. 370169695Skan@end deftypefun 371169695Skan 372169695Skan@comment obstack.h 373169695Skan@comment GNU 374169695Skan@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c}) 375169695SkanTo add one character at a time, use the function @code{obstack_1grow}. 376169695SkanIt adds a single byte containing @var{c} to the growing object. 377169695Skan@end deftypefun 378169695Skan 379169695Skan@comment obstack.h 380169695Skan@comment GNU 381169695Skan@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data}) 382169695SkanAdding the value of a pointer one can use the function 383169695Skan@code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes 384169695Skancontaining the value of @var{data}. 385169695Skan@end deftypefun 386169695Skan 387169695Skan@comment obstack.h 388169695Skan@comment GNU 389169695Skan@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data}) 390169695SkanA single value of type @code{int} can be added by using the 391169695Skan@code{obstack_int_grow} function. It adds @code{sizeof (int)} bytes to 392169695Skanthe growing object and initializes them with the value of @var{data}. 393169695Skan@end deftypefun 394169695Skan 395169695Skan@comment obstack.h 396169695Skan@comment GNU 397169695Skan@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr}) 398169695SkanWhen you are finished growing the object, use the function 399169695Skan@code{obstack_finish} to close it off and return its final address. 400169695Skan 401169695SkanOnce you have finished the object, the obstack is available for ordinary 402169695Skanallocation or for growing another object. 403169695Skan 404169695SkanThis function can return a null pointer under the same conditions as 405169695Skan@code{obstack_alloc} (@pxref{Allocation in an Obstack}). 406169695Skan@end deftypefun 407169695Skan 408169695SkanWhen you build an object by growing it, you will probably need to know 409169695Skanafterward how long it became. You need not keep track of this as you grow 410169695Skanthe object, because you can find out the length from the obstack just 411169695Skanbefore finishing the object with the function @code{obstack_object_size}, 412169695Skandeclared as follows: 413169695Skan 414169695Skan@comment obstack.h 415169695Skan@comment GNU 416169695Skan@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr}) 417169695SkanThis function returns the current size of the growing object, in bytes. 418169695SkanRemember to call this function @emph{before} finishing the object. 419169695SkanAfter it is finished, @code{obstack_object_size} will return zero. 420169695Skan@end deftypefun 421169695Skan 422169695SkanIf you have started growing an object and wish to cancel it, you should 423169695Skanfinish it and then free it, like this: 424169695Skan 425169695Skan@smallexample 426169695Skanobstack_free (obstack_ptr, obstack_finish (obstack_ptr)); 427169695Skan@end smallexample 428169695Skan 429169695Skan@noindent 430169695SkanThis has no effect if no object was growing. 431169695Skan 432169695Skan@cindex shrinking objects 433169695SkanYou can use @code{obstack_blank} with a negative size argument to make 434169695Skanthe current object smaller. Just don't try to shrink it beyond zero 435169695Skanlength---there's no telling what will happen if you do that. 436169695Skan 437169695Skan@node Extra Fast Growing 438169695Skan@section Extra Fast Growing Objects 439169695Skan@cindex efficiency and obstacks 440169695Skan 441169695SkanThe usual functions for growing objects incur overhead for checking 442169695Skanwhether there is room for the new growth in the current chunk. If you 443169695Skanare frequently constructing objects in small steps of growth, this 444169695Skanoverhead can be significant. 445169695Skan 446169695SkanYou can reduce the overhead by using special ``fast growth'' 447169695Skanfunctions that grow the object without checking. In order to have a 448169695Skanrobust program, you must do the checking yourself. If you do this checking 449169695Skanin the simplest way each time you are about to add data to the object, you 450169695Skanhave not saved anything, because that is what the ordinary growth 451169695Skanfunctions do. But if you can arrange to check less often, or check 452169695Skanmore efficiently, then you make the program faster. 453169695Skan 454169695SkanThe function @code{obstack_room} returns the amount of room available 455169695Skanin the current chunk. It is declared as follows: 456169695Skan 457169695Skan@comment obstack.h 458169695Skan@comment GNU 459169695Skan@deftypefun int obstack_room (struct obstack *@var{obstack-ptr}) 460169695SkanThis returns the number of bytes that can be added safely to the current 461169695Skangrowing object (or to an object about to be started) in obstack 462169695Skan@var{obstack} using the fast growth functions. 463169695Skan@end deftypefun 464169695Skan 465169695SkanWhile you know there is room, you can use these fast growth functions 466169695Skanfor adding data to a growing object: 467169695Skan 468169695Skan@comment obstack.h 469169695Skan@comment GNU 470169695Skan@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c}) 471169695SkanThe function @code{obstack_1grow_fast} adds one byte containing the 472169695Skancharacter @var{c} to the growing object in obstack @var{obstack-ptr}. 473169695Skan@end deftypefun 474169695Skan 475169695Skan@comment obstack.h 476169695Skan@comment GNU 477169695Skan@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data}) 478169695SkanThe function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)} 479169695Skanbytes containing the value of @var{data} to the growing object in 480169695Skanobstack @var{obstack-ptr}. 481169695Skan@end deftypefun 482169695Skan 483169695Skan@comment obstack.h 484169695Skan@comment GNU 485169695Skan@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data}) 486169695SkanThe function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes 487169695Skancontaining the value of @var{data} to the growing object in obstack 488169695Skan@var{obstack-ptr}. 489169695Skan@end deftypefun 490169695Skan 491169695Skan@comment obstack.h 492169695Skan@comment GNU 493169695Skan@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size}) 494169695SkanThe function @code{obstack_blank_fast} adds @var{size} bytes to the 495169695Skangrowing object in obstack @var{obstack-ptr} without initializing them. 496169695Skan@end deftypefun 497169695Skan 498169695SkanWhen you check for space using @code{obstack_room} and there is not 499169695Skanenough room for what you want to add, the fast growth functions 500169695Skanare not safe. In this case, simply use the corresponding ordinary 501169695Skangrowth function instead. Very soon this will copy the object to a 502169695Skannew chunk; then there will be lots of room available again. 503169695Skan 504169695SkanSo, each time you use an ordinary growth function, check afterward for 505169695Skansufficient space using @code{obstack_room}. Once the object is copied 506169695Skanto a new chunk, there will be plenty of space again, so the program will 507169695Skanstart using the fast growth functions again. 508169695Skan 509169695SkanHere is an example: 510169695Skan 511169695Skan@smallexample 512169695Skan@group 513169695Skanvoid 514169695Skanadd_string (struct obstack *obstack, const char *ptr, int len) 515169695Skan@{ 516169695Skan while (len > 0) 517169695Skan @{ 518169695Skan int room = obstack_room (obstack); 519169695Skan if (room == 0) 520169695Skan @{ 521169695Skan /* @r{Not enough room. Add one character slowly,} 522169695Skan @r{which may copy to a new chunk and make room.} */ 523169695Skan obstack_1grow (obstack, *ptr++); 524169695Skan len--; 525169695Skan @} 526169695Skan else 527169695Skan @{ 528169695Skan if (room > len) 529169695Skan room = len; 530169695Skan /* @r{Add fast as much as we have room for.} */ 531169695Skan len -= room; 532169695Skan while (room-- > 0) 533169695Skan obstack_1grow_fast (obstack, *ptr++); 534169695Skan @} 535169695Skan @} 536169695Skan@} 537169695Skan@end group 538169695Skan@end smallexample 539169695Skan 540169695Skan@node Status of an Obstack 541169695Skan@section Status of an Obstack 542169695Skan@cindex obstack status 543169695Skan@cindex status of obstack 544169695Skan 545169695SkanHere are functions that provide information on the current status of 546169695Skanallocation in an obstack. You can use them to learn about an object while 547169695Skanstill growing it. 548169695Skan 549169695Skan@comment obstack.h 550169695Skan@comment GNU 551169695Skan@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr}) 552169695SkanThis function returns the tentative address of the beginning of the 553169695Skancurrently growing object in @var{obstack-ptr}. If you finish the object 554169695Skanimmediately, it will have that address. If you make it larger first, it 555169695Skanmay outgrow the current chunk---then its address will change! 556169695Skan 557169695SkanIf no object is growing, this value says where the next object you 558169695Skanallocate will start (once again assuming it fits in the current 559169695Skanchunk). 560169695Skan@end deftypefun 561169695Skan 562169695Skan@comment obstack.h 563169695Skan@comment GNU 564169695Skan@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr}) 565169695SkanThis function returns the address of the first free byte in the current 566169695Skanchunk of obstack @var{obstack-ptr}. This is the end of the currently 567169695Skangrowing object. If no object is growing, @code{obstack_next_free} 568169695Skanreturns the same value as @code{obstack_base}. 569169695Skan@end deftypefun 570169695Skan 571169695Skan@comment obstack.h 572169695Skan@comment GNU 573169695Skan@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr}) 574169695SkanThis function returns the size in bytes of the currently growing object. 575169695SkanThis is equivalent to 576169695Skan 577169695Skan@smallexample 578169695Skanobstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr}) 579169695Skan@end smallexample 580169695Skan@end deftypefun 581169695Skan 582169695Skan@node Obstacks Data Alignment 583169695Skan@section Alignment of Data in Obstacks 584169695Skan@cindex alignment (in obstacks) 585169695Skan 586169695SkanEach obstack has an @dfn{alignment boundary}; each object allocated in 587169695Skanthe obstack automatically starts on an address that is a multiple of the 588169695Skanspecified boundary. By default, this boundary is 4 bytes. 589169695Skan 590169695SkanTo access an obstack's alignment boundary, use the macro 591169695Skan@code{obstack_alignment_mask}, whose function prototype looks like 592169695Skanthis: 593169695Skan 594169695Skan@comment obstack.h 595169695Skan@comment GNU 596169695Skan@deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr}) 597169695SkanThe value is a bit mask; a bit that is 1 indicates that the corresponding 598169695Skanbit in the address of an object should be 0. The mask value should be one 599169695Skanless than a power of 2; the effect is that all object addresses are 600169695Skanmultiples of that power of 2. The default value of the mask is 3, so that 601169695Skanaddresses are multiples of 4. A mask value of 0 means an object can start 602169695Skanon any multiple of 1 (that is, no alignment is required). 603169695Skan 604169695SkanThe expansion of the macro @code{obstack_alignment_mask} is an lvalue, 605169695Skanso you can alter the mask by assignment. For example, this statement: 606169695Skan 607169695Skan@smallexample 608169695Skanobstack_alignment_mask (obstack_ptr) = 0; 609169695Skan@end smallexample 610169695Skan 611169695Skan@noindent 612169695Skanhas the effect of turning off alignment processing in the specified obstack. 613169695Skan@end deftypefn 614169695Skan 615169695SkanNote that a change in alignment mask does not take effect until 616169695Skan@emph{after} the next time an object is allocated or finished in the 617169695Skanobstack. If you are not growing an object, you can make the new 618169695Skanalignment mask take effect immediately by calling @code{obstack_finish}. 619169695SkanThis will finish a zero-length object and then do proper alignment for 620169695Skanthe next object. 621169695Skan 622169695Skan@node Obstack Chunks 623169695Skan@section Obstack Chunks 624169695Skan@cindex efficiency of chunks 625169695Skan@cindex chunks 626169695Skan 627169695SkanObstacks work by allocating space for themselves in large chunks, and 628169695Skanthen parceling out space in the chunks to satisfy your requests. Chunks 629169695Skanare normally 4096 bytes long unless you specify a different chunk size. 630169695SkanThe chunk size includes 8 bytes of overhead that are not actually used 631169695Skanfor storing objects. Regardless of the specified size, longer chunks 632169695Skanwill be allocated when necessary for long objects. 633169695Skan 634169695SkanThe obstack library allocates chunks by calling the function 635169695Skan@code{obstack_chunk_alloc}, which you must define. When a chunk is no 636169695Skanlonger needed because you have freed all the objects in it, the obstack 637169695Skanlibrary frees the chunk by calling @code{obstack_chunk_free}, which you 638169695Skanmust also define. 639169695Skan 640169695SkanThese two must be defined (as macros) or declared (as functions) in each 641169695Skansource file that uses @code{obstack_init} (@pxref{Creating Obstacks}). 642169695SkanMost often they are defined as macros like this: 643169695Skan 644169695Skan@smallexample 645169695Skan#define obstack_chunk_alloc malloc 646169695Skan#define obstack_chunk_free free 647169695Skan@end smallexample 648169695Skan 649169695SkanNote that these are simple macros (no arguments). Macro definitions with 650169695Skanarguments will not work! It is necessary that @code{obstack_chunk_alloc} 651169695Skanor @code{obstack_chunk_free}, alone, expand into a function name if it is 652169695Skannot itself a function name. 653169695Skan 654169695SkanIf you allocate chunks with @code{malloc}, the chunk size should be a 655169695Skanpower of 2. The default chunk size, 4096, was chosen because it is long 656169695Skanenough to satisfy many typical requests on the obstack yet short enough 657169695Skannot to waste too much memory in the portion of the last chunk not yet used. 658169695Skan 659169695Skan@comment obstack.h 660169695Skan@comment GNU 661169695Skan@deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr}) 662169695SkanThis returns the chunk size of the given obstack. 663169695Skan@end deftypefn 664169695Skan 665169695SkanSince this macro expands to an lvalue, you can specify a new chunk size by 666169695Skanassigning it a new value. Doing so does not affect the chunks already 667169695Skanallocated, but will change the size of chunks allocated for that particular 668169695Skanobstack in the future. It is unlikely to be useful to make the chunk size 669169695Skansmaller, but making it larger might improve efficiency if you are 670169695Skanallocating many objects whose size is comparable to the chunk size. Here 671169695Skanis how to do so cleanly: 672169695Skan 673169695Skan@smallexample 674169695Skanif (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size}) 675169695Skan obstack_chunk_size (obstack_ptr) = @var{new-chunk-size}; 676169695Skan@end smallexample 677169695Skan 678169695Skan@node Summary of Obstacks 679169695Skan@section Summary of Obstack Functions 680169695Skan 681169695SkanHere is a summary of all the functions associated with obstacks. Each 682169695Skantakes the address of an obstack (@code{struct obstack *}) as its first 683169695Skanargument. 684169695Skan 685169695Skan@table @code 686169695Skan@item void obstack_init (struct obstack *@var{obstack-ptr}) 687169695SkanInitialize use of an obstack. @xref{Creating Obstacks}. 688169695Skan 689169695Skan@item void *obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size}) 690169695SkanAllocate an object of @var{size} uninitialized bytes. 691169695Skan@xref{Allocation in an Obstack}. 692169695Skan 693169695Skan@item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 694169695SkanAllocate an object of @var{size} bytes, with contents copied from 695169695Skan@var{address}. @xref{Allocation in an Obstack}. 696169695Skan 697169695Skan@item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 698169695SkanAllocate an object of @var{size}+1 bytes, with @var{size} of them copied 699169695Skanfrom @var{address}, followed by a null character at the end. 700169695Skan@xref{Allocation in an Obstack}. 701169695Skan 702169695Skan@item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) 703169695SkanFree @var{object} (and everything allocated in the specified obstack 704169695Skanmore recently than @var{object}). @xref{Freeing Obstack Objects}. 705169695Skan 706169695Skan@item void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size}) 707169695SkanAdd @var{size} uninitialized bytes to a growing object. 708169695Skan@xref{Growing Objects}. 709169695Skan 710169695Skan@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 711169695SkanAdd @var{size} bytes, copied from @var{address}, to a growing object. 712169695Skan@xref{Growing Objects}. 713169695Skan 714169695Skan@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 715169695SkanAdd @var{size} bytes, copied from @var{address}, to a growing object, 716169695Skanand then add another byte containing a null character. @xref{Growing 717169695SkanObjects}. 718169695Skan 719169695Skan@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char}) 720169695SkanAdd one byte containing @var{data-char} to a growing object. 721169695Skan@xref{Growing Objects}. 722169695Skan 723169695Skan@item void *obstack_finish (struct obstack *@var{obstack-ptr}) 724169695SkanFinalize the object that is growing and return its permanent address. 725169695Skan@xref{Growing Objects}. 726169695Skan 727169695Skan@item int obstack_object_size (struct obstack *@var{obstack-ptr}) 728169695SkanGet the current size of the currently growing object. @xref{Growing 729169695SkanObjects}. 730169695Skan 731169695Skan@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size}) 732169695SkanAdd @var{size} uninitialized bytes to a growing object without checking 733169695Skanthat there is enough room. @xref{Extra Fast Growing}. 734169695Skan 735169695Skan@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char}) 736169695SkanAdd one byte containing @var{data-char} to a growing object without 737169695Skanchecking that there is enough room. @xref{Extra Fast Growing}. 738169695Skan 739169695Skan@item int obstack_room (struct obstack *@var{obstack-ptr}) 740169695SkanGet the amount of room now available for growing the current object. 741169695Skan@xref{Extra Fast Growing}. 742169695Skan 743169695Skan@item int obstack_alignment_mask (struct obstack *@var{obstack-ptr}) 744169695SkanThe mask used for aligning the beginning of an object. This is an 745169695Skanlvalue. @xref{Obstacks Data Alignment}. 746169695Skan 747169695Skan@item int obstack_chunk_size (struct obstack *@var{obstack-ptr}) 748169695SkanThe size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}. 749169695Skan 750169695Skan@item void *obstack_base (struct obstack *@var{obstack-ptr}) 751169695SkanTentative starting address of the currently growing object. 752169695Skan@xref{Status of an Obstack}. 753169695Skan 754169695Skan@item void *obstack_next_free (struct obstack *@var{obstack-ptr}) 755169695SkanAddress just after the end of the currently growing object. 756169695Skan@xref{Status of an Obstack}. 757169695Skan@end table 758169695Skan 759