<!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>