Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/pool/doc/interfaces/pool.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 10.1 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2"http://www.w3.org/TR/html4/loose.dtd">
3
4<html>
5<head>
6  <meta http-equiv="Content-Language" content="en-us">
7  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
8  <link href="../pool.css" rel="stylesheet" type="text/css">
9
10  <title>Pool</title>
11</head>
12
13<body>
14  <img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
15
16  <h1 align="center">Pool</h1>
17
18  <h2>Introduction</h2>
19
20  <p><span class="code">pool</span> is a fast memory allocator, and
21  guarantees proper alignment of all allocated chunks.</p>
22
23  <p>pool.hpp provides two <a href="user_allocator.html">UserAllocator</a>
24  classes and a template class <span class="code">pool</span>, which extends
25  and generalizes the framework provided by the <a href=
26  "simple_segregated_storage.html">simple segregated storage</a> solution.
27  For information on other pool-based interfaces, see <a href=
28  "../interfaces.html">the other pool interfaces</a>.</p>
29
30  <h2>Synopsis</h2>
31  <pre class="code">
32struct default_user_allocator_new_delete; // see <a href=
33"user_allocator.html">User Allocators</a>
34struct default_user_allocator_malloc_free; // see <a href=
35"user_allocator.html">User Allocators</a>
36
37template &lt;typename UserAllocator = default_user_allocator_new_delete&gt;
38class pool
39{
40  private:
41    pool(const pool &amp;);
42    void operator=(const pool &amp;);
43
44  public:
45    typedef UserAllocator user_allocator;
46    typedef typename UserAllocator::size_type size_type;
47    typedef typename UserAllocator::difference_type difference_type;
48
49    explicit pool(size_type requested_size);
50    ~pool();
51
52    bool release_memory();
53    bool purge_memory();
54
55    bool is_from(void * chunk) const;
56    size_type get_requested_size() const;
57
58    void * malloc();
59    void * ordered_malloc();
60    void * ordered_malloc(size_type n);
61
62    void free(void * chunk);
63    void ordered_free(void * chunk);
64    void free(void * chunks, size_type n);
65    void ordered_free(void * chunks, size_type n);
66};
67</pre>
68
69  <h2>Template Parameters</h2>
70
71  <h3>UserAllocator</h3>
72
73  <p>Defines the method that the Pool will use to allocate memory from the
74  system. See <a href="user_allocator.html">User Allocators</a> for
75  details.</p>
76
77  <h2>Semantics</h2>
78
79  <table border align="center" summary="">
80    <caption>
81      <em>Symbol Table</em>
82    </caption>
83
84    <tr>
85      <th>Symbol</th>
86
87      <th>Meaning</th>
88    </tr>
89
90    <tr>
91      <td class="code">Pool</td>
92
93      <td class="code">pool&lt;UserAllocator&gt;</td>
94    </tr>
95
96    <tr>
97      <td class="code">t</td>
98
99      <td>value of type <span class="code">Pool</span></td>
100    </tr>
101
102    <tr>
103      <td class="code">u</td>
104
105      <td>value of type <span class="code">const Pool</span></td>
106    </tr>
107
108    <tr>
109      <td class="code">chunk</td>
110
111      <td>value of type <span class="code">void *</span></td>
112    </tr>
113
114    <tr>
115      <td class="code">n</td>
116
117      <td>value of type <span class="code">size_type</span></td>
118    </tr>
119
120    <tr>
121      <td class="code">RequestedSize</td>
122
123      <td>value of type <span class="code">Pool::size_type</span>; must be
124      greater than 0</td>
125    </tr>
126  </table><br>
127
128  <table border align="center" summary="">
129    <caption>
130      <em>Typedefs</em>
131    </caption>
132
133    <tr>
134      <th>Expression</th>
135
136      <th>Type</th>
137    </tr>
138
139    <tr>
140      <td class="code">Pool::user_allocator</td>
141
142      <td class="code">UserAllocator</td>
143    </tr>
144
145    <tr>
146      <td class="code">Pool::size_type</td>
147
148      <td class="code">UserAllocator::size_type</td>
149    </tr>
150
151    <tr>
152      <td class="code">Pool::difference_type</td>
153
154      <td class="code">UserAllocator::difference_type</td>
155    </tr>
156  </table><br>
157
158  <table border align="center" summary="">
159    <caption>
160      <em>Constructors, Destructors, and Testing</em>
161    </caption>
162
163    <tr>
164      <th>Expression</th>
165
166      <th>Return Type</th>
167
168      <th>Notes</th>
169    </tr>
170
171    <tr>
172      <td class="code">Pool(RequestedSize)</td>
173
174      <td>not used</td>
175
176      <td>Constructs a new empty <span class="code">Pool</span> that can be
177      used to allocate chunks of size <span class=
178      "code">RequestedSize</span></td>
179    </tr>
180
181    <tr>
182      <td class="code">(&amp;t)-&gt;~Pool()</td>
183
184      <td>not used</td>
185
186      <td>Destructs the <span class="code">Pool</span>, freeing its list of
187      memory blocks</td>
188    </tr>
189
190    <tr>
191      <td class="code">u.is_from(chunk)</td>
192
193      <td class="code">bool</td>
194
195      <td>Returns <span class="code">true</span> if <span class=
196      "code">chunk</span> was allocated from <span class="code">u</span> or
197      may be returned as the result of a future allocation from <span class=
198      "code">u</span>. Returns <span class="code">false</span> if
199      <span class="code">chunk</span> was allocated from some other pool or
200      may be returned as the result of a future allocation from some other
201      pool. Otherwise, the return value is meaningless; note that this
202      function may <strong>not</strong> be used to reliably test random
203      pointer values.</td>
204    </tr>
205
206    <tr>
207      <td class="code">u.get_requested_size()</td>
208
209      <td class="code">size_type</td>
210
211      <td>Returns the value passed into the constructor. This value will not
212      change during the lifetime of a <span class="code">Pool</span>
213      object.</td>
214    </tr>
215  </table><br>
216
217  <table border align="center" summary="">
218    <caption>
219      <em>Allocation and Deallocation</em>
220    </caption>
221
222    <tr>
223      <th>Expression</th>
224
225      <th>Return Type</th>
226
227      <th>Pre-Condition</th>
228
229      <th>Notes</th>
230    </tr>
231
232    <tr>
233      <td class="code">t.malloc()</td>
234
235      <td class="code">void *</td>
236
237      <td></td>
238
239      <td>Allocates a chunk of memory. Searches in the list of memory blocks
240      for a block that has a free chunk, and returns that free chunk if
241      found. Otherwise, creates a new memory block, adds its free list to
242      <span class="code">t</span>'s free list, and returns a free chunk from
243      that block. If a new memory block cannot be allocated, returns
244      <span class="code">0</span>. Amortized O(1).</td>
245    </tr>
246
247    <tr>
248      <td class="code">t.ordered_malloc()</td>
249
250      <td class="code">void *</td>
251
252      <td></td>
253
254      <td>Same as above, only merges the free lists, to preserve order.
255      Amortized O(1).</td>
256    </tr>
257
258    <tr>
259      <td class="code">t.ordered_malloc(n)</td>
260
261      <td class="code">void *</td>
262
263      <td></td>
264
265      <td>Same as above, only allocates enough contiguous chunks to cover
266      <span class="code">n * requested_size</span> bytes. Amortized
267      O(n).</td>
268    </tr>
269
270    <tr>
271      <td class="code">t.free(chunk)</td>
272
273      <td class="code">void</td>
274
275      <td><span class="code">chunk</span> must have been previously returned
276      by <span class="code">t.malloc()</span> or <span class=
277      "code">t.ordered_malloc()</span>.</td>
278
279      <td>Deallocates a chunk of memory. Note that <span class=
280      "code">chunk</span> may not be <span class="code">0</span>. O(1).</td>
281    </tr>
282
283    <tr>
284      <td class="code">t.ordered_free(chunk)</td>
285
286      <td class="code">void</td>
287
288      <td>Same as above</td>
289
290      <td>Same as above, but is order-preserving. Note that <span class=
291      "code">chunk</span> may not be <span class="code">0</span>. O(N) with
292      respect to the size of the free list</td>
293    </tr>
294
295    <tr>
296      <td class="code">t.free(chunk, n)</td>
297
298      <td class="code">void</td>
299
300      <td><span class="code">chunk</span> must have been previously returned
301      by <span class="code">t.ordered_malloc(n)</span>.</td>
302
303      <td>Assumes that <span class="code">chunk</span> actually refers to a
304      block of chunks spanning <span class="code">n * partition_sz</span>
305      bytes; deallocates each chunk in that block. Note that <span class=
306      "code">chunk</span> may not be <span class="code">0</span>. O(n).</td>
307    </tr>
308
309    <tr>
310      <td class="code">t.ordered_free(chunk, n)</td>
311
312      <td class="code">void</td>
313
314      <td><span class="code">chunk</span> must have been previously returned
315      by <span class="code">t.ordered_malloc(n)</span>.</td>
316
317      <td>Assumes that <span class="code">chunk</span> actually refers to a
318      block of chunks spanning <span class="code">n * partition_sz</span>
319      bytes; deallocates each chunk in that block. Note that <span class=
320      "code">chunk</span> may not be <span class="code">0</span>.
321      Order-preserving. O(N + n) where N is the size of the free list.</td>
322    </tr>
323
324    <tr>
325      <td class="code">t.release_memory()</td>
326
327      <td class="code">bool</td>
328
329      <td><span class="code">t</span> must be ordered.</td>
330
331      <td>Frees every memory block that doesn't have any allocated chunks.
332      Returns <span class="code">true</span> if at least one memory block was
333      freed.</td>
334    </tr>
335
336    <tr>
337      <td class="code">t.purge_memory()</td>
338
339      <td class="code">bool</td>
340
341      <td></td>
342
343      <td>Frees every memory block. This function invalidates any pointers
344      previously returned by allocation functions of <span class=
345      "code">t</span>. Returns <span class="code">true</span> if at least one
346      memory block was freed.</td>
347    </tr>
348  </table>
349
350  <h2>Symbols</h2>
351
352  <ul>
353    <li>boost::default_user_allocator_new_delete</li>
354
355    <li>boost::default_user_allocator_malloc_new</li>
356
357    <li>boost::pool</li>
358  </ul>
359
360  <h2><a href="../implementation/pool.html">Implementation Details</a></h2>
361  <hr>
362
363  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
364  "http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
365  height="31" width="88"></a></p>
366
367  <p>Revised
368  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05
369  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
370
371  <p><i>Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT
372  com)</i></p>
373
374  <p><i>Distributed under the Boost Software License, Version 1.0. (See
375  accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a>
376  or copy at <a href=
377  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
378</body>
379</html>
Note: See TracBrowser for help on using the repository browser.