| 1 | @node Obstacks |
| 2 | @subsection Obstacks |
| 3 | @cindex obstacks |
| 4 | |
| 5 | An @dfn{obstack} is a pool of memory containing a stack of objects. You |
| 6 | can create any number of separate obstacks, and then allocate objects in |
| 7 | specified obstacks. Within each obstack, the last object allocated must |
| 8 | always be the first one freed, but distinct obstacks are independent of |
| 9 | each other. |
| 10 | |
| 11 | Aside from this one constraint of order of freeing, obstacks are totally |
| 12 | general: an obstack can contain any number of objects of any size. They |
| 13 | are implemented with macros, so allocation is usually very fast as long as |
| 14 | the objects are usually small. And the only space overhead per object is |
| 15 | the 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 | |
| 37 | The utilities for manipulating obstacks are declared in the header |
| 38 | file @file{obstack.h}. |
| 39 | @pindex obstack.h |
| 40 | |
| 41 | @comment obstack.h |
| 42 | @comment GNU |
| 43 | @deftp {Data Type} {struct obstack} |
| 44 | An obstack is represented by a data structure of type @code{struct |
| 45 | obstack}. This structure has a small fixed size; it records the status |
| 46 | of the obstack and how to find the space in which objects are allocated. |
| 47 | It does not contain any of the objects themselves. You should not try |
| 48 | to access the contents of the structure directly; use only the macros |
| 49 | described in this chapter. |
| 50 | @end deftp |
| 51 | |
| 52 | You can declare variables of type @code{struct obstack} and use them as |
| 53 | obstacks, or you can allocate obstacks dynamically like any other kind |
| 54 | of object. Dynamic allocation of obstacks allows your program to have a |
| 55 | variable number of different stacks. (You can even allocate an |
| 56 | obstack structure in another obstack, but this is rarely useful.) |
| 57 | |
| 58 | All the macros that work with obstacks require you to specify which |
| 59 | obstack to use. You do this with a pointer of type @code{struct obstack |
| 60 | *}. In the following, we often say ``an obstack'' when strictly |
| 61 | speaking the object at hand is such a pointer. |
| 62 | |
| 63 | The objects in the obstack are packed into large blocks called |
| 64 | @dfn{chunks}. The @code{struct obstack} structure points to a chain of |
| 65 | the chunks currently in use. |
| 66 | |
| 67 | The obstack library obtains a new chunk whenever you allocate an object |
| 68 | that won't fit in the previous chunk. Since the obstack library manages |
| 69 | chunks automatically, you don't need to pay much attention to them, but |
| 70 | you do need to supply a function which the obstack library should use to |
| 71 | get a chunk. Usually you supply a function which uses @code{malloc} |
| 72 | directly or indirectly. You must also supply a function to free a chunk. |
| 73 | These matters are described in the following section. |
| 74 | |
| 75 | @node Preparing for Obstacks |
| 76 | @subsubsection Preparing for Using Obstacks |
| 77 | |
| 78 | Each source file in which you plan to use obstacks |
| 79 | must 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 |
| 87 | Also, if the source file uses the macro @code{obstack_init}, it must |
| 88 | declare or define two macros that will be called by the |
| 89 | obstack library. One, @code{obstack_chunk_alloc}, is used to allocate |
| 90 | the chunks of memory into which objects are packed. The other, |
| 91 | @code{obstack_chunk_free}, is used to return chunks when the objects in |
| 92 | them are freed. These macros should appear before any use of obstacks |
| 93 | in the source file. |
| 94 | |
| 95 | Usually 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 |
| 97 | the 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 |
| 105 | Though the memory you get using obstacks really comes from @code{malloc}, |
| 106 | using obstacks is faster because @code{malloc} is called less often, for |
| 107 | larger blocks of memory. @xref{Obstack Chunks}, for full details. |
| 108 | |
| 109 | At run time, before the program can use a @code{struct obstack} object |
| 110 | as 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}) |
| 118 | Initialize obstack @var{obstack-ptr} for allocation of objects. This |
| 119 | macro calls the obstack's @code{obstack_chunk_alloc} function. If |
| 120 | allocation of memory fails, the function pointed to by |
| 121 | @code{obstack_alloc_failed_handler} is called. The @code{obstack_init} |
| 122 | macro always returns 1 (Compatibility notice: Former versions of |
| 123 | obstack returned 0 if allocation failed). |
| 124 | @end deftypefun |
| 125 | |
| 126 | Here are two examples of how to allocate the space for an obstack and |
| 127 | initialize it. First, an obstack that is a static variable: |
| 128 | |
| 129 | @smallexample |
| 130 | static struct obstack myobstack; |
| 131 | @dots{} |
| 132 | obstack_init (&myobstack); |
| 133 | @end smallexample |
| 134 | |
| 135 | @noindent |
| 136 | Second, an obstack that is itself dynamically allocated: |
| 137 | |
| 138 | @smallexample |
| 139 | struct obstack *myobstack_ptr |
| 140 | = (struct obstack *) xmalloc (sizeof (struct obstack)); |
| 141 | |
| 142 | obstack_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) |
| 148 | Like @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 *)) |
| 155 | Like @code{obstack_init}, specifying chunk size, chunk |
| 156 | alignment, and memory allocation functions. A @var{chunk_size} or |
| 157 | @var{alignment} of zero results in the default size or alignment |
| 158 | respectively 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) |
| 164 | Like @code{obstack_specify_allocation}, but specifying memory |
| 165 | allocation 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 |
| 171 | The value of this variable is a pointer to a function that |
| 172 | @code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate |
| 173 | memory. The default action is to print a message and abort. |
| 174 | You should supply a function that either calls @code{exit} |
| 175 | (@pxref{Program Termination, , , libc, The GNU C Library Reference Manual}) or @code{longjmp} (@pxref{Non-Local |
| 176 | Exits, , , libc, The GNU C Library Reference Manual}) and doesn't return. |
| 177 | |
| 178 | @smallexample |
| 179 | void my_obstack_alloc_failed (void) |
| 180 | @dots{} |
| 181 | obstack_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 | |
| 190 | The 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}) |
| 196 | This allocates an uninitialized block of @var{size} bytes in an obstack |
| 197 | and returns its address. Here @var{obstack-ptr} specifies which obstack |
| 198 | to allocate the block in; it is the address of the @code{struct obstack} |
| 199 | object which represents the obstack. Each obstack macro |
| 200 | requires you to specify an @var{obstack-ptr} as the first argument. |
| 201 | |
| 202 | This macro calls the obstack's @code{obstack_chunk_alloc} function if |
| 203 | it 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 | |
| 208 | For example, here is a function that allocates a copy of a string @var{str} |
| 209 | in a specific obstack, which is in the variable @code{string_obstack}: |
| 210 | |
| 211 | @smallexample |
| 212 | struct obstack string_obstack; |
| 213 | |
| 214 | char * |
| 215 | copystring (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 | |
| 224 | To 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}) |
| 229 | This allocates a block and initializes it by copying @var{size} |
| 230 | bytes 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}) |
| 238 | Like @code{obstack_copy}, but appends an extra byte containing a null |
| 239 | character. This extra byte is not counted in the argument @var{size}. |
| 240 | @end deftypefun |
| 241 | |
| 242 | The @code{obstack_copy0} macro is convenient for copying a sequence |
| 243 | of characters into an obstack as a null-terminated string. Here is an |
| 244 | example of its use: |
| 245 | |
| 246 | @smallexample |
| 247 | char * |
| 248 | obstack_savestring (char *addr, size_t size) |
| 249 | @{ |
| 250 | return obstack_copy0 (&myobstack, addr, size); |
| 251 | @} |
| 252 | @end smallexample |
| 253 | |
| 254 | @noindent |
| 255 | Contrast 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 | |
| 262 | To free an object allocated in an obstack, use the macro |
| 263 | @code{obstack_free}. Since the obstack is a stack of objects, freeing |
| 264 | one object automatically frees all other objects allocated more recently |
| 265 | in the same obstack. |
| 266 | |
| 267 | @comment obstack.h |
| 268 | @comment GNU |
| 269 | @deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) |
| 270 | If @var{object} is a null pointer, everything allocated in the obstack |
| 271 | is freed. Otherwise, @var{object} must be the address of an object |
| 272 | allocated in the obstack. Then @var{object} is freed, along with |
| 273 | everything allocated in @var{obstack} since @var{object}. |
| 274 | @end deftypefun |
| 275 | |
| 276 | Note that if @var{object} is a null pointer, the result is an |
| 277 | uninitialized obstack. To free all memory in an obstack but leave it |
| 278 | valid for further allocation, call @code{obstack_free} with the address |
| 279 | of the first object allocated on the obstack: |
| 280 | |
| 281 | @smallexample |
| 282 | obstack_free (obstack_ptr, first_object_allocated_ptr); |
| 283 | @end smallexample |
| 284 | |
| 285 | Recall that the objects in an obstack are grouped into chunks. When all |
| 286 | the objects in a chunk become free, the obstack library automatically |
| 287 | frees the chunk (@pxref{Preparing for Obstacks}). Then other |
| 288 | obstacks, 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 | |
| 294 | The interfaces for using obstacks are shown here as functions to |
| 295 | specify the return type and argument types, but they are really |
| 296 | defined as macros. This means that the arguments don't actually have |
| 297 | types, but they generally behave as if they have the types shown. |
| 298 | You can call these macros like functions, but you cannot use them in |
| 299 | any other way (for example, you cannot take their address). |
| 300 | |
| 301 | Calling the macros requires a special precaution: namely, the first |
| 302 | operand (the obstack pointer) may not contain any side effects, because |
| 303 | it may be computed more than once. For example, if you write this: |
| 304 | |
| 305 | @smallexample |
| 306 | obstack_alloc (get_obstack (), 4); |
| 307 | @end smallexample |
| 308 | |
| 309 | @noindent |
| 310 | you will find that @code{get_obstack} may be called several times. |
| 311 | If you use @code{*obstack_list_ptr++} as the obstack pointer argument, |
| 312 | you will get very strange results since the incrementation may occur |
| 313 | several times. |
| 314 | |
| 315 | If you use the GNU C compiler, this precaution is not necessary, because |
| 316 | various language extensions in GNU C permit defining the macros so as to |
| 317 | compute each argument only once. |
| 318 | |
| 319 | Note that arguments other than the first will only be evaluated once, |
| 320 | even 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 | |
| 332 | Because memory in obstack chunks is used sequentially, it is possible to |
| 333 | build up an object step by step, adding one or more bytes at a time to the |
| 334 | end of the object. With this technique, you do not need to know how much |
| 335 | data you will put in the object until you come to the end of it. We call |
| 336 | this the technique of @dfn{growing objects}. The special macros |
| 337 | for adding data to the growing object are described in this section. |
| 338 | |
| 339 | You don't need to do anything special when you start to grow an object. |
| 340 | Using one of the macros to add data to the object automatically |
| 341 | starts it. However, it is necessary to say explicitly when the object is |
| 342 | finished. This is done with @code{obstack_finish}. |
| 343 | |
| 344 | The actual address of the object thus built up is not known until the |
| 345 | object is finished. Until then, it always remains possible that you will |
| 346 | add so much data that the object must be copied into a new chunk. |
| 347 | |
| 348 | While the obstack is in use for a growing object, you cannot use it for |
| 349 | ordinary allocation of another object. If you try to do so, the space |
| 350 | already 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}) |
| 355 | The 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}) |
| 362 | To add a block of initialized space, use @code{obstack_grow}, which is |
| 363 | the growing-object analogue of @code{obstack_copy}. It adds @var{size} |
| 364 | bytes 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}) |
| 371 | This is the growing-object analogue of @code{obstack_copy0}. It adds |
| 372 | @var{size} bytes copied from @var{data}, followed by an additional null |
| 373 | character. |
| 374 | @end deftypefun |
| 375 | |
| 376 | @comment obstack.h |
| 377 | @comment GNU |
| 378 | @deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c}) |
| 379 | To add one character at a time, use @code{obstack_1grow}. |
| 380 | It 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}) |
| 386 | Adding the value of a pointer one can use |
| 387 | @code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes |
| 388 | containing 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}) |
| 394 | A single value of type @code{int} can be added by using |
| 395 | @code{obstack_int_grow}. It adds @code{sizeof (int)} bytes to |
| 396 | the 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}) |
| 402 | When you are finished growing the object, use |
| 403 | @code{obstack_finish} to close it off and return its final address. |
| 404 | |
| 405 | Once you have finished the object, the obstack is available for ordinary |
| 406 | allocation or for growing another object. |
| 407 | @end deftypefun |
| 408 | |
| 409 | When you build an object by growing it, you will probably need to know |
| 410 | afterward how long it became. You need not keep track of this as you grow |
| 411 | the object, because you can find out the length from the obstack |
| 412 | with @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}) |
| 417 | This macro returns the current size of the growing object, in bytes. |
| 418 | Remember to call @code{obstack_object_size} @emph{before} finishing the object. |
| 419 | After it is finished, @code{obstack_object_size} will return zero. |
| 420 | @end deftypefun |
| 421 | |
| 422 | If you have started growing an object and wish to cancel it, you should |
| 423 | finish it and then free it, like this: |
| 424 | |
| 425 | @smallexample |
| 426 | obstack_free (obstack_ptr, obstack_finish (obstack_ptr)); |
| 427 | @end smallexample |
| 428 | |
| 429 | @noindent |
| 430 | This 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 | |
| 436 | The usual macros for growing objects incur overhead for checking |
| 437 | whether there is room for the new growth in the current chunk. If you |
| 438 | are frequently constructing objects in small steps of growth, this |
| 439 | overhead can be significant. |
| 440 | |
| 441 | You can reduce the overhead by using special ``fast growth'' |
| 442 | macros that grow the object without checking. In order to have a |
| 443 | robust program, you must do the checking yourself. If you do this checking |
| 444 | in the simplest way each time you are about to add data to the object, you |
| 445 | have not saved anything, because that is what the ordinary growth |
| 446 | macros do. But if you can arrange to check less often, or check |
| 447 | more efficiently, then you make the program faster. |
| 448 | |
| 449 | @code{obstack_room} returns the amount of room available |
| 450 | in the current chunk. |
| 451 | |
| 452 | @comment obstack.h |
| 453 | @comment GNU |
| 454 | @deftypefun size_t obstack_room (struct obstack *@var{obstack-ptr}) |
| 455 | This returns the number of bytes that can be added safely to the current |
| 456 | growing object (or to an object about to be started) in obstack |
| 457 | @var{obstack} using the fast growth macros. |
| 458 | @end deftypefun |
| 459 | |
| 460 | While you know there is room, you can use these fast growth macros |
| 461 | for 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 |
| 467 | character @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 *)} |
| 474 | bytes containing the value of @var{data} to the growing object in |
| 475 | obstack @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 |
| 482 | containing 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 |
| 490 | growing object in obstack @var{obstack-ptr} without initializing them. |
| 491 | @end deftypefun |
| 492 | |
| 493 | When you check for space using @code{obstack_room} and there is not |
| 494 | enough room for what you want to add, the fast growth macros |
| 495 | are not safe. In this case, simply use the corresponding ordinary |
| 496 | growth macro instead. Very soon this will copy the object to a |
| 497 | new chunk; then there will be lots of room available again. |
| 498 | |
| 499 | So, each time you use an ordinary growth macro, check afterward for |
| 500 | sufficient space using @code{obstack_room}. Once the object is copied |
| 501 | to a new chunk, there will be plenty of space again, so the program will |
| 502 | start using the fast growth macros again. |
| 503 | |
| 504 | Here is an example: |
| 505 | |
| 506 | @smallexample |
| 507 | @group |
| 508 | void |
| 509 | add_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 |
| 536 | You can use @code{obstack_blank_fast} with a ``negative'' size |
| 537 | argument to make the current object smaller. Just don't try to shrink |
| 538 | it beyond zero length---there's no telling what will happen if you do |
| 539 | that. 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 | |
| 547 | Here are macros that provide information on the current status of |
| 548 | allocation in an obstack. You can use them to learn about an object while |
| 549 | still growing it. |
| 550 | |
| 551 | @comment obstack.h |
| 552 | @comment GNU |
| 553 | @deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr}) |
| 554 | This macro returns the tentative address of the beginning of the |
| 555 | currently growing object in @var{obstack-ptr}. If you finish the object |
| 556 | immediately, it will have that address. If you make it larger first, it |
| 557 | may outgrow the current chunk---then its address will change! |
| 558 | |
| 559 | If no object is growing, this value says where the next object you |
| 560 | allocate will start (once again assuming it fits in the current |
| 561 | chunk). |
| 562 | @end deftypefun |
| 563 | |
| 564 | @comment obstack.h |
| 565 | @comment GNU |
| 566 | @deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr}) |
| 567 | This macro returns the address of the first free byte in the current |
| 568 | chunk of obstack @var{obstack-ptr}. This is the end of the currently |
| 569 | growing object. If no object is growing, @code{obstack_next_free} |
| 570 | returns 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}) |
| 576 | This macro returns the size in bytes of the currently growing object. |
| 577 | This 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 | |
| 588 | Each obstack has an @dfn{alignment boundary}; each object allocated in |
| 589 | the obstack automatically starts on an address that is a multiple of the |
| 590 | specified boundary. By default, this boundary is aligned so that |
| 591 | the object can hold any type of data. |
| 592 | |
| 593 | To 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}) |
| 599 | The value is a bit mask; a bit that is 1 indicates that the corresponding |
| 600 | bit in the address of an object should be 0. The mask value should be one |
| 601 | less than a power of 2; the effect is that all object addresses are |
| 602 | multiples of that power of 2. The default value of the mask is a value |
| 603 | that allows aligned objects to hold any type of data: for example, if |
| 604 | its value is 3, any type of data can be stored at locations whose |
| 605 | addresses are multiples of 4. A mask value of 0 means an object can start |
| 606 | on any multiple of 1 (that is, no alignment is required). |
| 607 | |
| 608 | The expansion of the macro @code{obstack_alignment_mask} is an lvalue, |
| 609 | so you can alter the mask by assignment. For example, this statement: |
| 610 | |
| 611 | @smallexample |
| 612 | obstack_alignment_mask (obstack_ptr) = 0; |
| 613 | @end smallexample |
| 614 | |
| 615 | @noindent |
| 616 | has the effect of turning off alignment processing in the specified obstack. |
| 617 | @end deftypefn |
| 618 | |
| 619 | Note 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 |
| 621 | obstack. If you are not growing an object, you can make the new |
| 622 | alignment mask take effect immediately by calling @code{obstack_finish}. |
| 623 | This will finish a zero-length object and then do proper alignment for |
| 624 | the next object. |
| 625 | |
| 626 | @node Obstack Chunks |
| 627 | @subsubsection Obstack Chunks |
| 628 | @cindex efficiency of chunks |
| 629 | @cindex chunks |
| 630 | |
| 631 | Obstacks work by allocating space for themselves in large chunks, and |
| 632 | then parceling out space in the chunks to satisfy your requests. Chunks |
| 633 | are normally 4096 bytes long unless you specify a different chunk size. |
| 634 | The chunk size includes 8 bytes of overhead that are not actually used |
| 635 | for storing objects. Regardless of the specified size, longer chunks |
| 636 | will be allocated when necessary for long objects. |
| 637 | |
| 638 | The obstack library allocates chunks by calling the function |
| 639 | @code{obstack_chunk_alloc}, which you must define. When a chunk is no |
| 640 | longer needed because you have freed all the objects in it, the obstack |
| 641 | library frees the chunk by calling @code{obstack_chunk_free}, which you |
| 642 | must also define. |
| 643 | |
| 644 | These two must be defined (as macros) or declared (as functions) in each |
| 645 | source file that uses @code{obstack_init} (@pxref{Creating Obstacks}). |
| 646 | Most 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 | |
| 653 | Note that these are simple macros (no arguments). Macro definitions with |
| 654 | arguments will not work! It is necessary that @code{obstack_chunk_alloc} |
| 655 | or @code{obstack_chunk_free}, alone, expand into a function name if it is |
| 656 | not itself a function name. |
| 657 | |
| 658 | If you allocate chunks with @code{malloc}, the chunk size should be a |
| 659 | power of 2. The default chunk size, 4096, was chosen because it is long |
| 660 | enough to satisfy many typical requests on the obstack yet short enough |
| 661 | not 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}) |
| 666 | This returns the chunk size of the given obstack. |
| 667 | @end deftypefn |
| 668 | |
| 669 | Since this macro expands to an lvalue, you can specify a new chunk size by |
| 670 | assigning it a new value. Doing so does not affect the chunks already |
| 671 | allocated, but will change the size of chunks allocated for that particular |
| 672 | obstack in the future. It is unlikely to be useful to make the chunk size |
| 673 | smaller, but making it larger might improve efficiency if you are |
| 674 | allocating many objects whose size is comparable to the chunk size. Here |
| 675 | is how to do so cleanly: |
| 676 | |
| 677 | @smallexample |
| 678 | if (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 | |
| 685 | Here is a summary of all the macros associated with obstacks. Each |
| 686 | takes the address of an obstack (@code{struct obstack *}) as its first |
| 687 | argument. |
| 688 | |
| 689 | @table @code |
| 690 | @item int obstack_init (struct obstack *@var{obstack-ptr}) |
| 691 | Initialize use of an obstack. @xref{Creating Obstacks}. |
| 692 | |
| 693 | @item int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size) |
| 694 | Initialize 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 *)) |
| 698 | Initialize use of an obstack, specifying intial chunk size, chunk |
| 699 | alignment, 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) |
| 702 | Like @code{obstack_specify_allocation}, but specifying memory |
| 703 | allocation functions that take an extra first argument, @var{arg}. |
| 704 | |
| 705 | @item void *obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size}) |
| 706 | Allocate 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}) |
| 710 | Allocate 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}) |
| 714 | Allocate an object of @var{size}+1 bytes, with @var{size} of them copied |
| 715 | from @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}) |
| 719 | Free @var{object} (and everything allocated in the specified obstack |
| 720 | more recently than @var{object}). @xref{Freeing Obstack Objects}. |
| 721 | |
| 722 | @item void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size}) |
| 723 | Add @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}) |
| 727 | Add @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}) |
| 731 | Add @var{size} bytes, copied from @var{address}, to a growing object, |
| 732 | and then add another byte containing a null character. @xref{Growing |
| 733 | Objects}. |
| 734 | |
| 735 | @item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char}) |
| 736 | Add 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}) |
| 740 | Finalize 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}) |
| 744 | Get the current size of the currently growing object. @xref{Growing |
| 745 | Objects}. |
| 746 | |
| 747 | @item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size}) |
| 748 | Add @var{size} uninitialized bytes to a growing object without checking |
| 749 | that there is enough room. @xref{Extra Fast Growing}. |
| 750 | |
| 751 | @item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char}) |
| 752 | Add one byte containing @var{data-char} to a growing object without |
| 753 | checking that there is enough room. @xref{Extra Fast Growing}. |
| 754 | |
| 755 | @item size_t obstack_room (struct obstack *@var{obstack-ptr}) |
| 756 | Get 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}) |
| 760 | The mask used for aligning the beginning of an object. This is an |
| 761 | lvalue. @xref{Obstacks Data Alignment}. |
| 762 | |
| 763 | @item size_t obstack_chunk_size (struct obstack *@var{obstack-ptr}) |
| 764 | The size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}. |
| 765 | |
| 766 | @item void *obstack_base (struct obstack *@var{obstack-ptr}) |
| 767 | Tentative 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}) |
| 771 | Address just after the end of the currently growing object. |
| 772 | @xref{Status of an Obstack}. |
| 773 | @end table |
| 774 | |