| <!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_alloc - Boost Pool Standard Allocators</title> |
| </head> |
| |
| <body> |
| <img src="../../../../boost.png" width="276" height="86" alt="C++ Boost"> |
| |
| <h1 align="center">pool_alloc - Boost Pool Standard Allocators</h1> |
| |
| <h2>Introduction</h2> |
| |
| <p>pool_alloc.hpp provides two template types that can be used for fast and |
| efficient memory allocation. These types both satisfy the Standard |
| Allocator requirements [20.1.5] and the additional requirements in |
| [20.1.5/4], so they can be used with Standard or user-supplied containers. |
| 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 pool_allocator_tag { }; |
| |
| template <typename T, |
| typename UserAllocator = default_user_allocator_new_delete> |
| class pool_allocator |
| { |
| public: |
| typedef UserAllocator user_allocator; |
| typedef T value_type; |
| typedef value_type * pointer; |
| typedef const value_type * const_pointer; |
| typedef value_type & reference; |
| typedef const value_type & const_reference; |
| typedef typename pool<UserAllocator>::size_type size_type; |
| typedef typename pool<UserAllcoator>::difference_type difference_type; |
| |
| template <typename U> |
| struct rebind |
| { typedef pool_allocator<U, UserAllocator> other; }; |
| |
| public: |
| pool_allocator(); |
| pool_allocator(const pool_allocator &); |
| // The following is not explicit, mimicking std::allocator [20.4.1] |
| template <typename U> |
| pool_allocator(const pool_allocator<U, UserAllocator> &); |
| pool_allocator & operator=(const pool_allocator &); |
| ~pool_allocator(); |
| |
| static pointer address(reference r); |
| static const_pointer address(const_reference s); |
| static size_type max_size(); |
| static void construct(pointer ptr, const value_type & t); |
| static void destroy(pointer ptr); |
| |
| bool operator==(const pool_allocator &) const; |
| bool operator!=(const pool_allocator &) const; |
| |
| static pointer allocate(size_type n); |
| static pointer allocate(size_type n, pointer); |
| static void deallocate(pointer ptr, size_type n); |
| }; |
| |
| struct fast_pool_allocator_tag { }; |
| |
| template <typename T |
| typename UserAllocator = default_user_allocator_new_delete> |
| class fast_pool_allocator |
| { |
| public: |
| typedef UserAllocator user_allocator; |
| typedef T value_type; |
| typedef value_type * pointer; |
| typedef const value_type * const_pointer; |
| typedef value_type & reference; |
| typedef const value_type & const_reference; |
| typedef typename pool<UserAllocator>::size_type size_type; |
| typedef typename pool<UserAllocator>::difference_type difference_type; |
| |
| template <typename U> |
| struct rebind |
| { typedef fast_pool_allocator<U, UserAllocator> other; }; |
| |
| public: |
| fast_pool_allocator(); |
| fast_pool_allocator(const fast_pool_allocator &); |
| // The following is not explicit, mimicking std::allocator [20.4.1] |
| template <typename U> |
| fast_pool_allocator(const fast_pool_allocator<U, UserAllocator> &); |
| fast_pool_allocator & operator=(const fast_pool_allocator &); |
| ~fast_pool_allocator(); |
| |
| static pointer address(reference r); |
| static const_pointer address(const_reference s); |
| static size_type max_size(); |
| static void construct(pointer ptr, const value_type & t); |
| static void destroy(pointer ptr); |
| |
| bool operator==(const fast_pool_allocator &) const; |
| bool operator!=(const fast_pool_allocator &) const; |
| |
| static pointer allocate(size_type n); |
| static pointer allocate(size_type n, pointer); |
| static void deallocate(pointer ptr, size_type n); |
| |
| static pointer allocate(); |
| static void deallocate(pointer ptr); |
| }; |
| </pre> |
| |
| <h2>Template Parameters</h2> |
| |
| <h3>T</h3> |
| |
| <p>The first template parameter is the type of object to |
| allocate/deallocate.</p> |
| |
| <h3>UserAllocator</h3> |
| |
| <p>Defines the method that the underlying Pool will use to allocate memory |
| from the system. See <a href="user_allocator.html">User Allocators</a> for |
| details.</p> |
| |
| <h2>Semantics</h2> |
| |
| <p>Both of the pool allocators above satisfy all Standard Allocator |
| requirements, as laid out in the Standard [20.1.5]. They also both satisfy |
| the additional requirements found in [20.1.5/4]; this permits their usage |
| with any Standard-compliant container.</p> |
| |
| <p>In addition, the <span class="code">fast_pool_allocator</span> also |
| provides an additional allocation and an additional deallocation |
| function:</p> |
| |
| <table border align="center" summary=""> |
| <caption> |
| <em>Symbol Table</em> |
| </caption> |
| |
| <tr> |
| <th>Symbol</th> |
| |
| <th>Meaning</th> |
| </tr> |
| |
| <tr> |
| <td class="code">PoolAlloc</td> |
| |
| <td><span class="code">fast_pool_allocator<T, |
| UserAllocator></span></td> |
| </tr> |
| |
| <tr> |
| <td class="code">p</td> |
| |
| <td>value of type <span class="code">T *</span></td> |
| </tr> |
| </table><br> |
| |
| <table border align="center" summary=""> |
| <caption> |
| <em>Additional allocation/deallocation functions (<span class= |
| "code">fast_pool_allocator</span> only)</em> |
| </caption> |
| |
| <tr> |
| <th>Expression</th> |
| |
| <th>Return Type</th> |
| |
| <th>Semantic Equivalence</th> |
| </tr> |
| |
| <tr> |
| <td class="code">PoolAlloc::allocate()</td> |
| |
| <td class="code">T *</td> |
| |
| <td class="code">PoolAlloc::allocate(1)</td> |
| </tr> |
| |
| <tr> |
| <td class="code">PoolAlloc::deallocate(p)</td> |
| |
| <td>void</td> |
| |
| <td class="code">PoolAlloc::deallocate(p, 1)</td> |
| </tr> |
| </table> |
| |
| <p>The typedef <span class="code">user_allocator</span> publishes the value |
| of the <span class="code">UserAllocator</span> template parameter.</p> |
| |
| <h2>Notes</h2> |
| |
| <p>If the allocation functions run out of memory, they will throw |
| <span class="code">std::bad_alloc</span>.</p> |
| |
| <p>The underlying Pool type used by the allocators is accessible through |
| the <a href="singleton_pool.html">Singleton Pool Interface</a>. The |
| identifying tag used for <span class="code">pool_allocator</span> is |
| <span class="code">pool_allocator_tag</span>, and the tag used for |
| <span class="code">fast_pool_allocator</span> is <span class= |
| "code">fast_pool_allocator_tag</span>. All template parameters of the |
| allocators (including <a href= |
| "../implementation/pool_alloc.html">implementation-specific ones</a>) |
| determine the type of the underlying Pool, with the exception of the first |
| parameter <span class="code">T</span>, whose size is used instead.</p> |
| |
| <p>Since the size of <span class="code">T</span> is used to determine the |
| type of the underlying Pool, each allocator for different types of the same |
| size <em>will share</em> the same underlying pool. The tag class prevents |
| pools from being shared between <span class="code">pool_allocator</span> |
| and <span class="code">fast_pool_allocator</span>. For example, on a system |
| where sizeof(int) == sizeof(void *), <span class= |
| "code">pool_allocator<int></span> and <span class= |
| "code">pool_allocator<void *></span> will both allocate/deallocate |
| from/to the same pool.</p> |
| |
| <p>If there is only one thread running before <span class= |
| "code">main()</span> starts and after <span class="code">main()</span> |
| ends, then both allocators are completely thread-safe.</p> |
| |
| <h2>The Fast Pool Allocator</h2> |
| |
| <p><span class="code">pool_allocator</span> is a more general-purpose |
| solution, geared towards efficiently servicing requests for any number of |
| contiguous chunks. <span class="code">fast_pool_allocator</span> is also a |
| general-purpose solution, but is geared towards efficiently servicing |
| requests for one chunk at a time; it will work for contiguous chunks, but |
| not as well as <span class="code">pool_allocator</span>. If you are |
| seriously concerned about performance, use <span class= |
| "code">fast_pool_allocator</span> when dealing with containers such as |
| <span class="code">std::list</span>, and use <span class= |
| "code">pool_allocator</span> when dealing with containers such as |
| <span class="code">std::vector</span>.</p> |
| |
| <h2>Symbols</h2> |
| |
| <ul> |
| <li>boost::pool_allocator</li> |
| |
| <li>boost::pool_allocator_tag</li> |
| |
| <li>boost::fast_pool_allocator</li> |
| |
| <li>boost::fast_pool_allocator_tag</li> |
| </ul> |
| |
| <h2><a href="../implementation/pool_alloc.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> |