| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" |
| "http://www.w3.org/TR/html4/loose.dtd"> |
| |
| <html> |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| <link href="../pool.css" rel="stylesheet" type="text/css"> |
| |
| <title>Pool</title> |
| </head> |
| |
| <body> |
| <img src="../../../../boost.png" width="276" height="86" alt="C++ Boost"> |
| |
| <h1 align="center">Pool</h1> |
| |
| <h2>Introduction</h2> |
| |
| <p><span class="code">pool</span> is a fast memory allocator, and |
| guarantees proper alignment of all allocated chunks.</p> |
| |
| <p>pool.hpp provides two <a href="user_allocator.html">UserAllocator</a> |
| classes and a template class <span class="code">pool</span>, which extends |
| and generalizes the framework provided by the <a href= |
| "simple_segregated_storage.html">simple segregated storage</a> solution. |
| For information on other pool-based interfaces, see <a href= |
| "../interfaces.html">the other pool interfaces</a>.</p> |
| |
| <h2>Synopsis</h2> |
| <pre class="code"> |
| struct default_user_allocator_new_delete; // see <a href= |
| "user_allocator.html">User Allocators</a> |
| struct default_user_allocator_malloc_free; // see <a href= |
| "user_allocator.html">User Allocators</a> |
| |
| template <typename UserAllocator = default_user_allocator_new_delete> |
| class pool |
| { |
| private: |
| pool(const pool &); |
| void operator=(const pool &); |
| |
| public: |
| typedef UserAllocator user_allocator; |
| typedef typename UserAllocator::size_type size_type; |
| typedef typename UserAllocator::difference_type difference_type; |
| |
| explicit pool(size_type requested_size); |
| ~pool(); |
| |
| bool release_memory(); |
| bool purge_memory(); |
| |
| bool is_from(void * chunk) const; |
| size_type get_requested_size() const; |
| |
| void * malloc(); |
| void * ordered_malloc(); |
| void * ordered_malloc(size_type n); |
| |
| void free(void * chunk); |
| void ordered_free(void * chunk); |
| void free(void * chunks, size_type n); |
| void ordered_free(void * chunks, size_type n); |
| }; |
| </pre> |
| |
| <h2>Template Parameters</h2> |
| |
| <h3>UserAllocator</h3> |
| |
| <p>Defines the method that the Pool will use to allocate memory from the |
| system. See <a href="user_allocator.html">User Allocators</a> for |
| details.</p> |
| |
| <h2>Semantics</h2> |
| |
| <table border align="center" summary=""> |
| <caption> |
| <em>Symbol Table</em> |
| </caption> |
| |
| <tr> |
| <th>Symbol</th> |
| |
| <th>Meaning</th> |
| </tr> |
| |
| <tr> |
| <td class="code">Pool</td> |
| |
| <td class="code">pool<UserAllocator></td> |
| </tr> |
| |
| <tr> |
| <td class="code">t</td> |
| |
| <td>value of type <span class="code">Pool</span></td> |
| </tr> |
| |
| <tr> |
| <td class="code">u</td> |
| |
| <td>value of type <span class="code">const Pool</span></td> |
| </tr> |
| |
| <tr> |
| <td class="code">chunk</td> |
| |
| <td>value of type <span class="code">void *</span></td> |
| </tr> |
| |
| <tr> |
| <td class="code">n</td> |
| |
| <td>value of type <span class="code">size_type</span></td> |
| </tr> |
| |
| <tr> |
| <td class="code">RequestedSize</td> |
| |
| <td>value of type <span class="code">Pool::size_type</span>; must be |
| greater than 0</td> |
| </tr> |
| </table><br> |
| |
| <table border align="center" summary=""> |
| <caption> |
| <em>Typedefs</em> |
| </caption> |
| |
| <tr> |
| <th>Expression</th> |
| |
| <th>Type</th> |
| </tr> |
| |
| <tr> |
| <td class="code">Pool::user_allocator</td> |
| |
| <td class="code">UserAllocator</td> |
| </tr> |
| |
| <tr> |
| <td class="code">Pool::size_type</td> |
| |
| <td class="code">UserAllocator::size_type</td> |
| </tr> |
| |
| <tr> |
| <td class="code">Pool::difference_type</td> |
| |
| <td class="code">UserAllocator::difference_type</td> |
| </tr> |
| </table><br> |
| |
| <table border align="center" summary=""> |
| <caption> |
| <em>Constructors, Destructors, and Testing</em> |
| </caption> |
| |
| <tr> |
| <th>Expression</th> |
| |
| <th>Return Type</th> |
| |
| <th>Notes</th> |
| </tr> |
| |
| <tr> |
| <td class="code">Pool(RequestedSize)</td> |
| |
| <td>not used</td> |
| |
| <td>Constructs a new empty <span class="code">Pool</span> that can be |
| used to allocate chunks of size <span class= |
| "code">RequestedSize</span></td> |
| </tr> |
| |
| <tr> |
| <td class="code">(&t)->~Pool()</td> |
| |
| <td>not used</td> |
| |
| <td>Destructs the <span class="code">Pool</span>, freeing its list of |
| memory blocks</td> |
| </tr> |
| |
| <tr> |
| <td class="code">u.is_from(chunk)</td> |
| |
| <td class="code">bool</td> |
| |
| <td>Returns <span class="code">true</span> if <span class= |
| "code">chunk</span> was allocated from <span class="code">u</span> or |
| may be returned as the result of a future allocation from <span class= |
| "code">u</span>. Returns <span class="code">false</span> if |
| <span class="code">chunk</span> was allocated from some other pool or |
| may be returned as the result of a future allocation from some other |
| pool. Otherwise, the return value is meaningless; note that this |
| function may <strong>not</strong> be used to reliably test random |
| pointer values.</td> |
| </tr> |
| |
| <tr> |
| <td class="code">u.get_requested_size()</td> |
| |
| <td class="code">size_type</td> |
| |
| <td>Returns the value passed into the constructor. This value will not |
| change during the lifetime of a <span class="code">Pool</span> |
| object.</td> |
| </tr> |
| </table><br> |
| |
| <table border align="center" summary=""> |
| <caption> |
| <em>Allocation and Deallocation</em> |
| </caption> |
| |
| <tr> |
| <th>Expression</th> |
| |
| <th>Return Type</th> |
| |
| <th>Pre-Condition</th> |
| |
| <th>Notes</th> |
| </tr> |
| |
| <tr> |
| <td class="code">t.malloc()</td> |
| |
| <td class="code">void *</td> |
| |
| <td></td> |
| |
| <td>Allocates a chunk of memory. Searches in the list of memory blocks |
| for a block that has a free chunk, and returns that free chunk if |
| found. Otherwise, creates a new memory block, adds its free list to |
| <span class="code">t</span>'s free list, and returns a free chunk from |
| that block. If a new memory block cannot be allocated, returns |
| <span class="code">0</span>. Amortized O(1).</td> |
| </tr> |
| |
| <tr> |
| <td class="code">t.ordered_malloc()</td> |
| |
| <td class="code">void *</td> |
| |
| <td></td> |
| |
| <td>Same as above, only merges the free lists, to preserve order. |
| Amortized O(1).</td> |
| </tr> |
| |
| <tr> |
| <td class="code">t.ordered_malloc(n)</td> |
| |
| <td class="code">void *</td> |
| |
| <td></td> |
| |
| <td>Same as above, only allocates enough contiguous chunks to cover |
| <span class="code">n * requested_size</span> bytes. Amortized |
| O(n).</td> |
| </tr> |
| |
| <tr> |
| <td class="code">t.free(chunk)</td> |
| |
| <td class="code">void</td> |
| |
| <td><span class="code">chunk</span> must have been previously returned |
| by <span class="code">t.malloc()</span> or <span class= |
| "code">t.ordered_malloc()</span>.</td> |
| |
| <td>Deallocates a chunk of memory. Note that <span class= |
| "code">chunk</span> may not be <span class="code">0</span>. O(1).</td> |
| </tr> |
| |
| <tr> |
| <td class="code">t.ordered_free(chunk)</td> |
| |
| <td class="code">void</td> |
| |
| <td>Same as above</td> |
| |
| <td>Same as above, but is order-preserving. Note that <span class= |
| "code">chunk</span> may not be <span class="code">0</span>. O(N) with |
| respect to the size of the free list</td> |
| </tr> |
| |
| <tr> |
| <td class="code">t.free(chunk, n)</td> |
| |
| <td class="code">void</td> |
| |
| <td><span class="code">chunk</span> must have been previously returned |
| by <span class="code">t.ordered_malloc(n)</span>.</td> |
| |
| <td>Assumes that <span class="code">chunk</span> actually refers to a |
| block of chunks spanning <span class="code">n * partition_sz</span> |
| bytes; deallocates each chunk in that block. Note that <span class= |
| "code">chunk</span> may not be <span class="code">0</span>. O(n).</td> |
| </tr> |
| |
| <tr> |
| <td class="code">t.ordered_free(chunk, n)</td> |
| |
| <td class="code">void</td> |
| |
| <td><span class="code">chunk</span> must have been previously returned |
| by <span class="code">t.ordered_malloc(n)</span>.</td> |
| |
| <td>Assumes that <span class="code">chunk</span> actually refers to a |
| block of chunks spanning <span class="code">n * partition_sz</span> |
| bytes; deallocates each chunk in that block. Note that <span class= |
| "code">chunk</span> may not be <span class="code">0</span>. |
| Order-preserving. O(N + n) where N is the size of the free list.</td> |
| </tr> |
| |
| <tr> |
| <td class="code">t.release_memory()</td> |
| |
| <td class="code">bool</td> |
| |
| <td><span class="code">t</span> must be ordered.</td> |
| |
| <td>Frees every memory block that doesn't have any allocated chunks. |
| Returns <span class="code">true</span> if at least one memory block was |
| freed.</td> |
| </tr> |
| |
| <tr> |
| <td class="code">t.purge_memory()</td> |
| |
| <td class="code">bool</td> |
| |
| <td></td> |
| |
| <td>Frees every memory block. This function invalidates any pointers |
| previously returned by allocation functions of <span class= |
| "code">t</span>. Returns <span class="code">true</span> if at least one |
| memory block was freed.</td> |
| </tr> |
| </table> |
| |
| <h2>Symbols</h2> |
| |
| <ul> |
| <li>boost::default_user_allocator_new_delete</li> |
| |
| <li>boost::default_user_allocator_malloc_new</li> |
| |
| <li>boost::pool</li> |
| </ul> |
| |
| <h2><a href="../implementation/pool.html">Implementation Details</a></h2> |
| <hr> |
| |
| <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src= |
| "../../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional" |
| height="31" width="88"></a></p> |
| |
| <p>Revised |
| <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 |
| December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p> |
| |
| <p><i>Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT |
| com)</i></p> |
| |
| <p><i>Distributed under the Boost Software License, Version 1.0. (See |
| accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> |
| or copy at <a href= |
| "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p> |
| </body> |
| </html> |
