|
111
|
1 @node Obstacks
|
|
|
2 @subsection Obstacks
|
|
0
|
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
|
|
111
|
18 * Creating Obstacks:: How to declare an obstack in your program.
|
|
|
19 * Preparing for Obstacks:: Preparations needed before you can
|
|
|
20 use obstacks.
|
|
0
|
21 * Allocation in an Obstack:: Allocating objects in an obstack.
|
|
|
22 * Freeing Obstack Objects:: Freeing objects in an obstack.
|
|
111
|
23 * Obstack Functions:: The obstack functions are really macros.
|
|
0
|
24 * Growing Objects:: Making an object bigger by stages.
|
|
111
|
25 * Extra Fast Growing:: Extra-high-efficiency (though more
|
|
|
26 complicated) growing objects.
|
|
0
|
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;
|
|
111
|
30 efficiency considerations.
|
|
0
|
31 * Summary of Obstacks::
|
|
|
32 @end menu
|
|
|
33
|
|
|
34 @node Creating Obstacks
|
|
111
|
35 @subsubsection Creating Obstacks
|
|
0
|
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
|
|
111
|
48 to access the contents of the structure directly; use only the macros
|
|
0
|
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
|
|
111
|
58 All the macros that work with obstacks require you to specify which
|
|
0
|
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
|
|
111
|
76 @subsubsection Preparing for Using Obstacks
|
|
0
|
77
|
|
111
|
78 Each source file in which you plan to use obstacks
|
|
0
|
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
|
|
111
|
88 declare or define two macros that will be called by the
|
|
0
|
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
|
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}.
|
|
0
|
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
|
|
111
|
119 macro calls the obstack's @code{obstack_chunk_alloc} function. If
|
|
0
|
120 allocation of memory fails, the function pointed to by
|
|
|
121 @code{obstack_alloc_failed_handler} is called. The @code{obstack_init}
|
|
111
|
122 macro always returns 1 (Compatibility notice: Former versions of
|
|
0
|
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
|
|
111
|
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
|
|
0
|
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
|
|
111
|
187 @subsubsection Allocation in an Obstack
|
|
0
|
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
|
|
111
|
195 @deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size})
|
|
0
|
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}
|
|
111
|
199 object which represents the obstack. Each obstack macro
|
|
0
|
200 requires you to specify an @var{obstack-ptr} as the first argument.
|
|
|
201
|
|
111
|
202 This macro calls the obstack's @code{obstack_chunk_alloc} function if
|
|
0
|
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
|
|
111
|
224 To allocate a block with specified contents, use the macro @code{obstack_copy}.
|
|
0
|
225
|
|
|
226 @comment obstack.h
|
|
|
227 @comment GNU
|
|
111
|
228 @deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
|
|
0
|
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
|
|
111
|
237 @deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
|
|
0
|
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
|
|
111
|
242 The @code{obstack_copy0} macro is convenient for copying a sequence
|
|
0
|
243 of characters into an obstack as a null-terminated string. Here is an
|
|
|
244 example of its use:
|
|
|
245
|
|
|
246 @smallexample
|
|
|
247 char *
|
|
111
|
248 obstack_savestring (char *addr, size_t size)
|
|
0
|
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
|
|
111
|
259 @subsubsection Freeing Objects in an Obstack
|
|
0
|
260 @cindex freeing (obstacks)
|
|
|
261
|
|
111
|
262 To free an object allocated in an obstack, use the macro
|
|
0
|
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
|
|
111
|
291 @subsubsection Obstack Functions and Macros
|
|
0
|
292 @cindex macros
|
|
|
293
|
|
111
|
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).
|
|
0
|
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
|
|
111
|
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
|
|
0
|
327 @node Growing Objects
|
|
111
|
328 @subsubsection Growing Objects
|
|
0
|
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
|
|
111
|
336 this the technique of @dfn{growing objects}. The special macros
|
|
0
|
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.
|
|
111
|
340 Using one of the macros to add data to the object automatically
|
|
0
|
341 starts it. However, it is necessary to say explicitly when the object is
|
|
111
|
342 finished. This is done with @code{obstack_finish}.
|
|
0
|
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
|
|
111
|
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
|
|
0
|
356 @code{obstack_blank}, which adds space without initializing it.
|
|
|
357 @end deftypefun
|
|
|
358
|
|
|
359 @comment obstack.h
|
|
|
360 @comment GNU
|
|
111
|
361 @deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size})
|
|
0
|
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
|
|
111
|
370 @deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size})
|
|
0
|
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})
|
|
111
|
379 To add one character at a time, use @code{obstack_1grow}.
|
|
0
|
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})
|
|
111
|
386 Adding the value of a pointer one can use
|
|
0
|
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})
|
|
111
|
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
|
|
0
|
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})
|
|
111
|
402 When you are finished growing the object, use
|
|
0
|
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
|
|
111
|
411 the object, because you can find out the length from the obstack
|
|
|
412 with @code{obstack_object_size}, before finishing the object.
|
|
0
|
413
|
|
|
414 @comment obstack.h
|
|
|
415 @comment GNU
|
|
111
|
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.
|
|
0
|
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
|
|
111
|
433 @subsubsection Extra Fast Growing Objects
|
|
0
|
434 @cindex efficiency and obstacks
|
|
|
435
|
|
111
|
436 The usual macros for growing objects incur overhead for checking
|
|
0
|
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''
|
|
111
|
442 macros that grow the object without checking. In order to have a
|
|
0
|
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
|
|
111
|
446 macros do. But if you can arrange to check less often, or check
|
|
0
|
447 more efficiently, then you make the program faster.
|
|
|
448
|
|
111
|
449 @code{obstack_room} returns the amount of room available
|
|
|
450 in the current chunk.
|
|
0
|
451
|
|
|
452 @comment obstack.h
|
|
|
453 @comment GNU
|
|
111
|
454 @deftypefun size_t obstack_room (struct obstack *@var{obstack-ptr})
|
|
0
|
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
|
|
111
|
457 @var{obstack} using the fast growth macros.
|
|
0
|
458 @end deftypefun
|
|
|
459
|
|
111
|
460 While you know there is room, you can use these fast growth macros
|
|
0
|
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})
|
|
111
|
466 @code{obstack_1grow_fast} adds one byte containing the
|
|
0
|
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})
|
|
111
|
473 @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
|
|
0
|
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})
|
|
111
|
481 @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
|
|
0
|
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
|
|
111
|
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
|
|
0
|
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
|
|
111
|
494 enough room for what you want to add, the fast growth macros
|
|
0
|
495 are not safe. In this case, simply use the corresponding ordinary
|
|
111
|
496 growth macro instead. Very soon this will copy the object to a
|
|
0
|
497 new chunk; then there will be lots of room available again.
|
|
|
498
|
|
111
|
499 So, each time you use an ordinary growth macro, check afterward for
|
|
0
|
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
|
|
111
|
502 start using the fast growth macros again.
|
|
0
|
503
|
|
|
504 Here is an example:
|
|
|
505
|
|
|
506 @smallexample
|
|
|
507 @group
|
|
|
508 void
|
|
111
|
509 add_string (struct obstack *obstack, const char *ptr, size_t len)
|
|
0
|
510 @{
|
|
|
511 while (len > 0)
|
|
|
512 @{
|
|
111
|
513 size_t room = obstack_room (obstack);
|
|
0
|
514 if (room == 0)
|
|
|
515 @{
|
|
111
|
516 /* @r{Not enough room. Add one character slowly,}
|
|
0
|
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
|
|
111
|
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
|
|
0
|
542 @node Status of an Obstack
|
|
111
|
543 @subsubsection Status of an Obstack
|
|
0
|
544 @cindex obstack status
|
|
|
545 @cindex status of obstack
|
|
|
546
|
|
111
|
547 Here are macros that provide information on the current status of
|
|
0
|
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})
|
|
111
|
554 This macro returns the tentative address of the beginning of the
|
|
0
|
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})
|
|
111
|
567 This macro returns the address of the first free byte in the current
|
|
0
|
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
|
|
111
|
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.
|
|
0
|
577 This is equivalent to
|
|
|
578
|
|
|
579 @smallexample
|
|
111
|
580 ((size_t) (obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})))
|
|
0
|
581 @end smallexample
|
|
|
582 @end deftypefun
|
|
|
583
|
|
|
584 @node Obstacks Data Alignment
|
|
111
|
585 @subsubsection Alignment of Data in Obstacks
|
|
0
|
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
|
|
111
|
590 specified boundary. By default, this boundary is aligned so that
|
|
|
591 the object can hold any type of data.
|
|
0
|
592
|
|
|
593 To access an obstack's alignment boundary, use the macro
|
|
111
|
594 @code{obstack_alignment_mask}.
|
|
0
|
595
|
|
|
596 @comment obstack.h
|
|
|
597 @comment GNU
|
|
111
|
598 @deftypefn Macro size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr})
|
|
0
|
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
|
|
111
|
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
|
|
0
|
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
|
|
111
|
627 @subsubsection Obstack Chunks
|
|
0
|
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
|
|
111
|
665 @deftypefn Macro size_t obstack_chunk_size (struct obstack *@var{obstack-ptr})
|
|
0
|
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
|
|
111
|
683 @subsubsection Summary of Obstack Macros
|
|
0
|
684
|
|
111
|
685 Here is a summary of all the macros associated with obstacks. Each
|
|
0
|
686 takes the address of an obstack (@code{struct obstack *}) as its first
|
|
|
687 argument.
|
|
|
688
|
|
|
689 @table @code
|
|
111
|
690 @item int obstack_init (struct obstack *@var{obstack-ptr})
|
|
0
|
691 Initialize use of an obstack. @xref{Creating Obstacks}.
|
|
|
692
|
|
111
|
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})
|
|
0
|
706 Allocate an object of @var{size} uninitialized bytes.
|
|
|
707 @xref{Allocation in an Obstack}.
|
|
|
708
|
|
111
|
709 @item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
|
|
0
|
710 Allocate an object of @var{size} bytes, with contents copied from
|
|
|
711 @var{address}. @xref{Allocation in an Obstack}.
|
|
|
712
|
|
111
|
713 @item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
|
|
0
|
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
|
|
111
|
722 @item void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size})
|
|
0
|
723 Add @var{size} uninitialized bytes to a growing object.
|
|
|
724 @xref{Growing Objects}.
|
|
|
725
|
|
111
|
726 @item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
|
|
0
|
727 Add @var{size} bytes, copied from @var{address}, to a growing object.
|
|
|
728 @xref{Growing Objects}.
|
|
|
729
|
|
111
|
730 @item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
|
|
0
|
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
|
|
111
|
743 @item size_t obstack_object_size (struct obstack *@var{obstack-ptr})
|
|
0
|
744 Get the current size of the currently growing object. @xref{Growing
|
|
|
745 Objects}.
|
|
|
746
|
|
111
|
747 @item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size})
|
|
0
|
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
|
|
111
|
755 @item size_t obstack_room (struct obstack *@var{obstack-ptr})
|
|
0
|
756 Get the amount of room now available for growing the current object.
|
|
|
757 @xref{Extra Fast Growing}.
|
|
|
758
|
|
111
|
759 @item size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr})
|
|
0
|
760 The mask used for aligning the beginning of an object. This is an
|
|
|
761 lvalue. @xref{Obstacks Data Alignment}.
|
|
|
762
|
|
111
|
763 @item size_t obstack_chunk_size (struct obstack *@var{obstack-ptr})
|
|
0
|
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
|
