obstacks.texi revision 1.1.1.3
1@node Obstacks 2@subsection Obstacks 3@cindex obstacks 4 5An @dfn{obstack} is a pool of memory containing a stack of objects. You 6can create any number of separate obstacks, and then allocate objects in 7specified obstacks. Within each obstack, the last object allocated must 8always be the first one freed, but distinct obstacks are independent of 9each other. 10 11Aside from this one constraint of order of freeing, obstacks are totally 12general: an obstack can contain any number of objects of any size. They 13are implemented with macros, so allocation is usually very fast as long as 14the objects are usually small. And the only space overhead per object is 15the padding needed to start each object on a suitable boundary. 16 17@menu 18* Creating Obstacks:: How to declare an obstack in your program. 19* Preparing for Obstacks:: Preparations needed before you can 20 use obstacks. 21* Allocation in an Obstack:: Allocating objects in an obstack. 22* Freeing Obstack Objects:: Freeing objects in an obstack. 23* Obstack Functions:: The obstack functions are both 24 functions and macros. 25* Growing Objects:: Making an object bigger by stages. 26* Extra Fast Growing:: Extra-high-efficiency (though more 27 complicated) growing objects. 28* Status of an Obstack:: Inquiries about the status of an obstack. 29* Obstacks Data Alignment:: Controlling alignment of objects in obstacks. 30* Obstack Chunks:: How obstacks obtain and release chunks; 31 efficiency considerations. 32* Summary of Obstacks:: 33@end menu 34 35@node Creating Obstacks 36@subsubsection Creating Obstacks 37 38The utilities for manipulating obstacks are declared in the header 39file @file{obstack.h}. 40@pindex obstack.h 41 42@comment obstack.h 43@comment GNU 44@deftp {Data Type} {struct obstack} 45An obstack is represented by a data structure of type @code{struct 46obstack}. This structure has a small fixed size; it records the status 47of the obstack and how to find the space in which objects are allocated. 48It does not contain any of the objects themselves. You should not try 49to access the contents of the structure directly; use only the functions 50described in this chapter. 51@end deftp 52 53You can declare variables of type @code{struct obstack} and use them as 54obstacks, or you can allocate obstacks dynamically like any other kind 55of object. Dynamic allocation of obstacks allows your program to have a 56variable number of different stacks. (You can even allocate an 57obstack structure in another obstack, but this is rarely useful.) 58 59All the functions that work with obstacks require you to specify which 60obstack to use. You do this with a pointer of type @code{struct obstack 61*}. In the following, we often say ``an obstack'' when strictly 62speaking the object at hand is such a pointer. 63 64The objects in the obstack are packed into large blocks called 65@dfn{chunks}. The @code{struct obstack} structure points to a chain of 66the chunks currently in use. 67 68The obstack library obtains a new chunk whenever you allocate an object 69that won't fit in the previous chunk. Since the obstack library manages 70chunks automatically, you don't need to pay much attention to them, but 71you do need to supply a function which the obstack library should use to 72get a chunk. Usually you supply a function which uses @code{malloc} 73directly or indirectly. You must also supply a function to free a chunk. 74These matters are described in the following section. 75 76@node Preparing for Obstacks 77@subsubsection Preparing for Using Obstacks 78 79Each source file in which you plan to use the obstack functions 80must include the header file @file{obstack.h}, like this: 81 82@smallexample 83#include <obstack.h> 84@end smallexample 85 86@findex obstack_chunk_alloc 87@findex obstack_chunk_free 88Also, if the source file uses the macro @code{obstack_init}, it must 89declare or define two functions or macros that will be called by the 90obstack library. One, @code{obstack_chunk_alloc}, is used to allocate 91the chunks of memory into which objects are packed. The other, 92@code{obstack_chunk_free}, is used to return chunks when the objects in 93them are freed. These macros should appear before any use of obstacks 94in the source file. 95 96Usually these are defined to use @code{malloc} via the intermediary 97@code{xmalloc} (@pxref{Unconstrained Allocation, , , libc, The GNU C Library Reference Manual}). This is done with 98the following pair of macro definitions: 99 100@smallexample 101#define obstack_chunk_alloc xmalloc 102#define obstack_chunk_free free 103@end smallexample 104 105@noindent 106Though the memory you get using obstacks really comes from @code{malloc}, 107using obstacks is faster because @code{malloc} is called less often, for 108larger blocks of memory. @xref{Obstack Chunks}, for full details. 109 110At run time, before the program can use a @code{struct obstack} object 111as an obstack, it must initialize the obstack by calling 112@code{obstack_init}. 113 114@comment obstack.h 115@comment GNU 116@deftypefun int obstack_init (struct obstack *@var{obstack-ptr}) 117Initialize obstack @var{obstack-ptr} for allocation of objects. This 118function calls the obstack's @code{obstack_chunk_alloc} function. If 119allocation of memory fails, the function pointed to by 120@code{obstack_alloc_failed_handler} is called. The @code{obstack_init} 121function always returns 1 (Compatibility notice: Former versions of 122obstack returned 0 if allocation failed). 123@end deftypefun 124 125Here are two examples of how to allocate the space for an obstack and 126initialize it. First, an obstack that is a static variable: 127 128@smallexample 129static struct obstack myobstack; 130@dots{} 131obstack_init (&myobstack); 132@end smallexample 133 134@noindent 135Second, an obstack that is itself dynamically allocated: 136 137@smallexample 138struct obstack *myobstack_ptr 139 = (struct obstack *) xmalloc (sizeof (struct obstack)); 140 141obstack_init (myobstack_ptr); 142@end smallexample 143 144@comment obstack.h 145@comment GNU 146@defvar obstack_alloc_failed_handler 147The value of this variable is a pointer to a function that 148@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate 149memory. The default action is to print a message and abort. 150You should supply a function that either calls @code{exit} 151(@pxref{Program Termination, , , libc, The GNU C Library Reference Manual}) or @code{longjmp} (@pxref{Non-Local 152Exits, , , libc, The GNU C Library Reference Manual}) and doesn't return. 153 154@smallexample 155void my_obstack_alloc_failed (void) 156@dots{} 157obstack_alloc_failed_handler = &my_obstack_alloc_failed; 158@end smallexample 159 160@end defvar 161 162@node Allocation in an Obstack 163@subsubsection Allocation in an Obstack 164@cindex allocation (obstacks) 165 166The most direct way to allocate an object in an obstack is with 167@code{obstack_alloc}, which is invoked almost like @code{malloc}. 168 169@comment obstack.h 170@comment GNU 171@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size}) 172This allocates an uninitialized block of @var{size} bytes in an obstack 173and returns its address. Here @var{obstack-ptr} specifies which obstack 174to allocate the block in; it is the address of the @code{struct obstack} 175object which represents the obstack. Each obstack function or macro 176requires you to specify an @var{obstack-ptr} as the first argument. 177 178This function calls the obstack's @code{obstack_chunk_alloc} function if 179it needs to allocate a new chunk of memory; it calls 180@code{obstack_alloc_failed_handler} if allocation of memory by 181@code{obstack_chunk_alloc} failed. 182@end deftypefun 183 184For example, here is a function that allocates a copy of a string @var{str} 185in a specific obstack, which is in the variable @code{string_obstack}: 186 187@smallexample 188struct obstack string_obstack; 189 190char * 191copystring (char *string) 192@{ 193 size_t len = strlen (string) + 1; 194 char *s = (char *) obstack_alloc (&string_obstack, len); 195 memcpy (s, string, len); 196 return s; 197@} 198@end smallexample 199 200To allocate a block with specified contents, use the function 201@code{obstack_copy}, declared like this: 202 203@comment obstack.h 204@comment GNU 205@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 206This allocates a block and initializes it by copying @var{size} 207bytes of data starting at @var{address}. It calls 208@code{obstack_alloc_failed_handler} if allocation of memory by 209@code{obstack_chunk_alloc} failed. 210@end deftypefun 211 212@comment obstack.h 213@comment GNU 214@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 215Like @code{obstack_copy}, but appends an extra byte containing a null 216character. This extra byte is not counted in the argument @var{size}. 217@end deftypefun 218 219The @code{obstack_copy0} function is convenient for copying a sequence 220of characters into an obstack as a null-terminated string. Here is an 221example of its use: 222 223@smallexample 224char * 225obstack_savestring (char *addr, int size) 226@{ 227 return obstack_copy0 (&myobstack, addr, size); 228@} 229@end smallexample 230 231@noindent 232Contrast this with the previous example of @code{savestring} using 233@code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}). 234 235@node Freeing Obstack Objects 236@subsubsection Freeing Objects in an Obstack 237@cindex freeing (obstacks) 238 239To free an object allocated in an obstack, use the function 240@code{obstack_free}. Since the obstack is a stack of objects, freeing 241one object automatically frees all other objects allocated more recently 242in the same obstack. 243 244@comment obstack.h 245@comment GNU 246@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) 247If @var{object} is a null pointer, everything allocated in the obstack 248is freed. Otherwise, @var{object} must be the address of an object 249allocated in the obstack. Then @var{object} is freed, along with 250everything allocated in @var{obstack} since @var{object}. 251@end deftypefun 252 253Note that if @var{object} is a null pointer, the result is an 254uninitialized obstack. To free all memory in an obstack but leave it 255valid for further allocation, call @code{obstack_free} with the address 256of the first object allocated on the obstack: 257 258@smallexample 259obstack_free (obstack_ptr, first_object_allocated_ptr); 260@end smallexample 261 262Recall that the objects in an obstack are grouped into chunks. When all 263the objects in a chunk become free, the obstack library automatically 264frees the chunk (@pxref{Preparing for Obstacks}). Then other 265obstacks, or non-obstack allocation, can reuse the space of the chunk. 266 267@node Obstack Functions 268@subsubsection Obstack Functions and Macros 269@cindex macros 270 271The interfaces for using obstacks may be defined either as functions or 272as macros, depending on the compiler. The obstack facility works with 273all C compilers, including both @w{ISO C} and traditional C, but there are 274precautions you must take if you plan to use compilers other than GNU C. 275 276If you are using an old-fashioned @w{non-ISO C} compiler, all the obstack 277``functions'' are actually defined only as macros. You can call these 278macros like functions, but you cannot use them in any other way (for 279example, you cannot take their address). 280 281Calling the macros requires a special precaution: namely, the first 282operand (the obstack pointer) may not contain any side effects, because 283it may be computed more than once. For example, if you write this: 284 285@smallexample 286obstack_alloc (get_obstack (), 4); 287@end smallexample 288 289@noindent 290you will find that @code{get_obstack} may be called several times. 291If you use @code{*obstack_list_ptr++} as the obstack pointer argument, 292you will get very strange results since the incrementation may occur 293several times. 294 295In @w{ISO C}, each function has both a macro definition and a function 296definition. The function definition is used if you take the address of the 297function without calling it. An ordinary call uses the macro definition by 298default, but you can request the function definition instead by writing the 299function name in parentheses, as shown here: 300 301@smallexample 302char *x; 303void *(*funcp) (); 304/* @r{Use the macro}. */ 305x = (char *) obstack_alloc (obptr, size); 306/* @r{Call the function}. */ 307x = (char *) (obstack_alloc) (obptr, size); 308/* @r{Take the address of the function}. */ 309funcp = obstack_alloc; 310@end smallexample 311 312@noindent 313This is the same situation that exists in @w{ISO C} for the standard library 314functions. @xref{Macro Definitions, , , libc, The GNU C Library Reference Manual}. 315 316@strong{Warning:} When you do use the macros, you must observe the 317precaution of avoiding side effects in the first operand, even in @w{ISO C}. 318 319If you use the GNU C compiler, this precaution is not necessary, because 320various language extensions in GNU C permit defining the macros so as to 321compute each argument only once. 322 323@node Growing Objects 324@subsubsection Growing Objects 325@cindex growing objects (in obstacks) 326@cindex changing the size of a block (obstacks) 327 328Because memory in obstack chunks is used sequentially, it is possible to 329build up an object step by step, adding one or more bytes at a time to the 330end of the object. With this technique, you do not need to know how much 331data you will put in the object until you come to the end of it. We call 332this the technique of @dfn{growing objects}. The special functions 333for adding data to the growing object are described in this section. 334 335You don't need to do anything special when you start to grow an object. 336Using one of the functions to add data to the object automatically 337starts it. However, it is necessary to say explicitly when the object is 338finished. This is done with the function @code{obstack_finish}. 339 340The actual address of the object thus built up is not known until the 341object is finished. Until then, it always remains possible that you will 342add so much data that the object must be copied into a new chunk. 343 344While the obstack is in use for a growing object, you cannot use it for 345ordinary allocation of another object. If you try to do so, the space 346already added to the growing object will become part of the other object. 347 348@comment obstack.h 349@comment GNU 350@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size}) 351The most basic function for adding to a growing object is 352@code{obstack_blank}, which adds space without initializing it. 353@end deftypefun 354 355@comment obstack.h 356@comment GNU 357@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size}) 358To add a block of initialized space, use @code{obstack_grow}, which is 359the growing-object analogue of @code{obstack_copy}. It adds @var{size} 360bytes of data to the growing object, copying the contents from 361@var{data}. 362@end deftypefun 363 364@comment obstack.h 365@comment GNU 366@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size}) 367This is the growing-object analogue of @code{obstack_copy0}. It adds 368@var{size} bytes copied from @var{data}, followed by an additional null 369character. 370@end deftypefun 371 372@comment obstack.h 373@comment GNU 374@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c}) 375To add one character at a time, use the function @code{obstack_1grow}. 376It adds a single byte containing @var{c} to the growing object. 377@end deftypefun 378 379@comment obstack.h 380@comment GNU 381@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data}) 382Adding the value of a pointer one can use the function 383@code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes 384containing the value of @var{data}. 385@end deftypefun 386 387@comment obstack.h 388@comment GNU 389@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data}) 390A single value of type @code{int} can be added by using the 391@code{obstack_int_grow} function. It adds @code{sizeof (int)} bytes to 392the growing object and initializes them with the value of @var{data}. 393@end deftypefun 394 395@comment obstack.h 396@comment GNU 397@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr}) 398When you are finished growing the object, use the function 399@code{obstack_finish} to close it off and return its final address. 400 401Once you have finished the object, the obstack is available for ordinary 402allocation or for growing another object. 403 404This function can return a null pointer under the same conditions as 405@code{obstack_alloc} (@pxref{Allocation in an Obstack}). 406@end deftypefun 407 408When you build an object by growing it, you will probably need to know 409afterward how long it became. You need not keep track of this as you grow 410the object, because you can find out the length from the obstack just 411before finishing the object with the function @code{obstack_object_size}, 412declared as follows: 413 414@comment obstack.h 415@comment GNU 416@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr}) 417This function returns the current size of the growing object, in bytes. 418Remember to call this function @emph{before} finishing the object. 419After it is finished, @code{obstack_object_size} will return zero. 420@end deftypefun 421 422If you have started growing an object and wish to cancel it, you should 423finish it and then free it, like this: 424 425@smallexample 426obstack_free (obstack_ptr, obstack_finish (obstack_ptr)); 427@end smallexample 428 429@noindent 430This has no effect if no object was growing. 431 432@cindex shrinking objects 433You can use @code{obstack_blank} with a negative size argument to make 434the current object smaller. Just don't try to shrink it beyond zero 435length---there's no telling what will happen if you do that. 436 437@node Extra Fast Growing 438@subsubsection Extra Fast Growing Objects 439@cindex efficiency and obstacks 440 441The usual functions for growing objects incur overhead for checking 442whether there is room for the new growth in the current chunk. If you 443are frequently constructing objects in small steps of growth, this 444overhead can be significant. 445 446You can reduce the overhead by using special ``fast growth'' 447functions that grow the object without checking. In order to have a 448robust program, you must do the checking yourself. If you do this checking 449in the simplest way each time you are about to add data to the object, you 450have not saved anything, because that is what the ordinary growth 451functions do. But if you can arrange to check less often, or check 452more efficiently, then you make the program faster. 453 454The function @code{obstack_room} returns the amount of room available 455in the current chunk. It is declared as follows: 456 457@comment obstack.h 458@comment GNU 459@deftypefun int obstack_room (struct obstack *@var{obstack-ptr}) 460This returns the number of bytes that can be added safely to the current 461growing object (or to an object about to be started) in obstack 462@var{obstack} using the fast growth functions. 463@end deftypefun 464 465While you know there is room, you can use these fast growth functions 466for adding data to a growing object: 467 468@comment obstack.h 469@comment GNU 470@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c}) 471The function @code{obstack_1grow_fast} adds one byte containing the 472character @var{c} to the growing object in obstack @var{obstack-ptr}. 473@end deftypefun 474 475@comment obstack.h 476@comment GNU 477@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data}) 478The function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)} 479bytes containing the value of @var{data} to the growing object in 480obstack @var{obstack-ptr}. 481@end deftypefun 482 483@comment obstack.h 484@comment GNU 485@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data}) 486The function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes 487containing the value of @var{data} to the growing object in obstack 488@var{obstack-ptr}. 489@end deftypefun 490 491@comment obstack.h 492@comment GNU 493@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size}) 494The function @code{obstack_blank_fast} adds @var{size} bytes to the 495growing object in obstack @var{obstack-ptr} without initializing them. 496@end deftypefun 497 498When you check for space using @code{obstack_room} and there is not 499enough room for what you want to add, the fast growth functions 500are not safe. In this case, simply use the corresponding ordinary 501growth function instead. Very soon this will copy the object to a 502new chunk; then there will be lots of room available again. 503 504So, each time you use an ordinary growth function, check afterward for 505sufficient space using @code{obstack_room}. Once the object is copied 506to a new chunk, there will be plenty of space again, so the program will 507start using the fast growth functions again. 508 509Here is an example: 510 511@smallexample 512@group 513void 514add_string (struct obstack *obstack, const char *ptr, int len) 515@{ 516 while (len > 0) 517 @{ 518 int room = obstack_room (obstack); 519 if (room == 0) 520 @{ 521 /* @r{Not enough room. Add one character slowly,} 522 @r{which may copy to a new chunk and make room.} */ 523 obstack_1grow (obstack, *ptr++); 524 len--; 525 @} 526 else 527 @{ 528 if (room > len) 529 room = len; 530 /* @r{Add fast as much as we have room for.} */ 531 len -= room; 532 while (room-- > 0) 533 obstack_1grow_fast (obstack, *ptr++); 534 @} 535 @} 536@} 537@end group 538@end smallexample 539 540@node Status of an Obstack 541@subsubsection Status of an Obstack 542@cindex obstack status 543@cindex status of obstack 544 545Here are functions that provide information on the current status of 546allocation in an obstack. You can use them to learn about an object while 547still growing it. 548 549@comment obstack.h 550@comment GNU 551@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr}) 552This function returns the tentative address of the beginning of the 553currently growing object in @var{obstack-ptr}. If you finish the object 554immediately, it will have that address. If you make it larger first, it 555may outgrow the current chunk---then its address will change! 556 557If no object is growing, this value says where the next object you 558allocate will start (once again assuming it fits in the current 559chunk). 560@end deftypefun 561 562@comment obstack.h 563@comment GNU 564@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr}) 565This function returns the address of the first free byte in the current 566chunk of obstack @var{obstack-ptr}. This is the end of the currently 567growing object. If no object is growing, @code{obstack_next_free} 568returns the same value as @code{obstack_base}. 569@end deftypefun 570 571@comment obstack.h 572@comment GNU 573@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr}) 574This function returns the size in bytes of the currently growing object. 575This is equivalent to 576 577@smallexample 578obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr}) 579@end smallexample 580@end deftypefun 581 582@node Obstacks Data Alignment 583@subsubsection Alignment of Data in Obstacks 584@cindex alignment (in obstacks) 585 586Each obstack has an @dfn{alignment boundary}; each object allocated in 587the obstack automatically starts on an address that is a multiple of the 588specified boundary. By default, this boundary is aligned so that 589the object can hold any type of data. 590 591To access an obstack's alignment boundary, use the macro 592@code{obstack_alignment_mask}, whose function prototype looks like 593this: 594 595@comment obstack.h 596@comment GNU 597@deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr}) 598The value is a bit mask; a bit that is 1 indicates that the corresponding 599bit in the address of an object should be 0. The mask value should be one 600less than a power of 2; the effect is that all object addresses are 601multiples of that power of 2. The default value of the mask is a value 602that allows aligned objects to hold any type of data: for example, if 603its value is 3, any type of data can be stored at locations whose 604addresses are multiples of 4. A mask value of 0 means an object can start 605on any multiple of 1 (that is, no alignment is required). 606 607The expansion of the macro @code{obstack_alignment_mask} is an lvalue, 608so you can alter the mask by assignment. For example, this statement: 609 610@smallexample 611obstack_alignment_mask (obstack_ptr) = 0; 612@end smallexample 613 614@noindent 615has the effect of turning off alignment processing in the specified obstack. 616@end deftypefn 617 618Note that a change in alignment mask does not take effect until 619@emph{after} the next time an object is allocated or finished in the 620obstack. If you are not growing an object, you can make the new 621alignment mask take effect immediately by calling @code{obstack_finish}. 622This will finish a zero-length object and then do proper alignment for 623the next object. 624 625@node Obstack Chunks 626@subsubsection Obstack Chunks 627@cindex efficiency of chunks 628@cindex chunks 629 630Obstacks work by allocating space for themselves in large chunks, and 631then parceling out space in the chunks to satisfy your requests. Chunks 632are normally 4096 bytes long unless you specify a different chunk size. 633The chunk size includes 8 bytes of overhead that are not actually used 634for storing objects. Regardless of the specified size, longer chunks 635will be allocated when necessary for long objects. 636 637The obstack library allocates chunks by calling the function 638@code{obstack_chunk_alloc}, which you must define. When a chunk is no 639longer needed because you have freed all the objects in it, the obstack 640library frees the chunk by calling @code{obstack_chunk_free}, which you 641must also define. 642 643These two must be defined (as macros) or declared (as functions) in each 644source file that uses @code{obstack_init} (@pxref{Creating Obstacks}). 645Most often they are defined as macros like this: 646 647@smallexample 648#define obstack_chunk_alloc malloc 649#define obstack_chunk_free free 650@end smallexample 651 652Note that these are simple macros (no arguments). Macro definitions with 653arguments will not work! It is necessary that @code{obstack_chunk_alloc} 654or @code{obstack_chunk_free}, alone, expand into a function name if it is 655not itself a function name. 656 657If you allocate chunks with @code{malloc}, the chunk size should be a 658power of 2. The default chunk size, 4096, was chosen because it is long 659enough to satisfy many typical requests on the obstack yet short enough 660not to waste too much memory in the portion of the last chunk not yet used. 661 662@comment obstack.h 663@comment GNU 664@deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr}) 665This returns the chunk size of the given obstack. 666@end deftypefn 667 668Since this macro expands to an lvalue, you can specify a new chunk size by 669assigning it a new value. Doing so does not affect the chunks already 670allocated, but will change the size of chunks allocated for that particular 671obstack in the future. It is unlikely to be useful to make the chunk size 672smaller, but making it larger might improve efficiency if you are 673allocating many objects whose size is comparable to the chunk size. Here 674is how to do so cleanly: 675 676@smallexample 677if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size}) 678 obstack_chunk_size (obstack_ptr) = @var{new-chunk-size}; 679@end smallexample 680 681@node Summary of Obstacks 682@subsubsection Summary of Obstack Functions 683 684Here is a summary of all the functions associated with obstacks. Each 685takes the address of an obstack (@code{struct obstack *}) as its first 686argument. 687 688@table @code 689@item void obstack_init (struct obstack *@var{obstack-ptr}) 690Initialize use of an obstack. @xref{Creating Obstacks}. 691 692@item void *obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size}) 693Allocate an object of @var{size} uninitialized bytes. 694@xref{Allocation in an Obstack}. 695 696@item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 697Allocate an object of @var{size} bytes, with contents copied from 698@var{address}. @xref{Allocation in an Obstack}. 699 700@item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 701Allocate an object of @var{size}+1 bytes, with @var{size} of them copied 702from @var{address}, followed by a null character at the end. 703@xref{Allocation in an Obstack}. 704 705@item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) 706Free @var{object} (and everything allocated in the specified obstack 707more recently than @var{object}). @xref{Freeing Obstack Objects}. 708 709@item void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size}) 710Add @var{size} uninitialized bytes to a growing object. 711@xref{Growing Objects}. 712 713@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 714Add @var{size} bytes, copied from @var{address}, to a growing object. 715@xref{Growing Objects}. 716 717@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) 718Add @var{size} bytes, copied from @var{address}, to a growing object, 719and then add another byte containing a null character. @xref{Growing 720Objects}. 721 722@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char}) 723Add one byte containing @var{data-char} to a growing object. 724@xref{Growing Objects}. 725 726@item void *obstack_finish (struct obstack *@var{obstack-ptr}) 727Finalize the object that is growing and return its permanent address. 728@xref{Growing Objects}. 729 730@item int obstack_object_size (struct obstack *@var{obstack-ptr}) 731Get the current size of the currently growing object. @xref{Growing 732Objects}. 733 734@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size}) 735Add @var{size} uninitialized bytes to a growing object without checking 736that there is enough room. @xref{Extra Fast Growing}. 737 738@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char}) 739Add one byte containing @var{data-char} to a growing object without 740checking that there is enough room. @xref{Extra Fast Growing}. 741 742@item int obstack_room (struct obstack *@var{obstack-ptr}) 743Get the amount of room now available for growing the current object. 744@xref{Extra Fast Growing}. 745 746@item int obstack_alignment_mask (struct obstack *@var{obstack-ptr}) 747The mask used for aligning the beginning of an object. This is an 748lvalue. @xref{Obstacks Data Alignment}. 749 750@item int obstack_chunk_size (struct obstack *@var{obstack-ptr}) 751The size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}. 752 753@item void *obstack_base (struct obstack *@var{obstack-ptr}) 754Tentative starting address of the currently growing object. 755@xref{Status of an Obstack}. 756 757@item void *obstack_next_free (struct obstack *@var{obstack-ptr}) 758Address just after the end of the currently growing object. 759@xref{Status of an Obstack}. 760@end table 761 762