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