| <!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>Boost Pool Interfaces</title> |
| </head> |
| |
| <body> |
| <img src="../../../boost.png" width="276" height="86" alt="C++ Boost"> |
| |
| <h1 align="center">Boost Pool Interfaces</h1> |
| |
| <h2>Introduction</h2> |
| |
| <p>There are several interfaces provided which allow users great flexibility |
| in how they want to use Pools. Review the <a href= |
| "concepts.html">concepts document</a> to get the basic understanding of how |
| Pools work.</p> |
| |
| <h2>Terminology and Tradeoffs</h2> |
| |
| <h3>Object Usage vs. Singleton Usage</h3> |
| |
| <p><em>Object Usage</em> is the method where each Pool is an object that may |
| be created and destroyed. Destroying a Pool implicitly frees all chunks that |
| have been allocated from it.</p> |
| |
| <p><em>Singleton Usage</em> is the method where each Pool is an object with |
| static duration; that is, it will not be destroyed until program exit. Pool |
| objects with Singleton Usage may be shared; thus, Singleton Usage implies |
| thread-safety as well. System memory allocated by Pool objects with |
| Singleton Usage may be freed through <span class= |
| "code">release_memory</span> or <span class="code">purge_memory</span>.</p> |
| |
| <h3>Out-of-Memory Conditions: Exceptions vs. Null Return</h3> |
| |
| <p>Some Pool interfaces throw exceptions when out-of-memory; others will |
| return 0. In general, unless mandated by the Standard, Pool interfaces will |
| always prefer to return 0 instead of throw an exception.</p> |
| |
| <h2>The Interfaces</h2> |
| |
| <h3>pool</h3> |
| |
| <p>The <a href="interfaces/pool.html">pool interface</a> is a simple Object |
| Usage interface with Null Return.</p> |
| |
| <p>Example:</p> |
| <pre class="code"> |
| void func() |
| { |
| boost::pool<> p(sizeof(int)); |
| for (int i = 0; i < 10000; ++i) |
| { |
| int * const t = p.malloc(); |
| ... // Do something with t; don't take the time to free() it |
| } |
| } // on function exit, p is destroyed, and all malloc()'ed ints are implicitly freed |
| </pre> |
| |
| <h3>object_pool</h3> |
| |
| <p>The <a href="interfaces/object_pool.html">object_pool interface</a> is an |
| Object Usage interface with Null Return, but is aware of the type of the |
| object for which it is allocating chunks. On destruction, any chunks that |
| have been allocated from that object_pool will have their destructors |
| called.</p> |
| |
| <p>Example:</p> |
| <pre class="code"> |
| struct X { ... }; // has destructor with side-effects |
| |
| void func() |
| { |
| boost::object_pool<X> p; |
| for (int i = 0; i < 10000; ++i) |
| { |
| X * const t = p.malloc(); |
| ... // Do something with t; don't take the time to free() it |
| } |
| } // on function exit, p is destroyed, and all destructors for the X objects are called |
| </pre> |
| |
| <h3>singleton_pool</h3> |
| |
| <p>The <a href="interfaces/singleton_pool.html">singleton_pool interface</a> |
| is a Singleton Usage interface with Null Return. It's just the same as the |
| pool interface but with Singleton Usage instead.</p> |
| |
| <p>Example:</p> |
| <pre class="code"> |
| struct MyPoolTag { }; |
| |
| typedef boost::singleton_pool<MyPoolTag, sizeof(int)> my_pool; |
| void func() |
| { |
| for (int i = 0; i < 10000; ++i) |
| { |
| int * const t = my_pool::malloc(); |
| ... // Do something with t; don't take the time to free() it |
| } |
| // Explicitly free all malloc()'ed int's |
| my_pool::purge_memory(); |
| } |
| </pre> |
| |
| <h3>pool_alloc</h3> |
| |
| <p>The <a href="interfaces/pool_alloc.html">pool_alloc interface</a> is a |
| Singleton Usage interface with Exceptions. It is built on the singleton_pool |
| interface, and provides a Standard Allocator-compliant class (for use in |
| containers, etc.).</p> |
| |
| <p>Example:</p> |
| <pre class="code"> |
| void func() |
| { |
| std::vector<int, boost::pool_allocator<int> > v; |
| for (int i = 0; i < 10000; ++i) |
| v.push_back(13); |
| } // Exiting the function does NOT free the system memory allocated by the pool allocator |
| // You must call |
| // boost::singleton_pool<boost::pool_allocator_tag, sizeof(int)>::release_memory() |
| // in order to force that |
| </pre> |
| |
| <h2>Future Directions</h2> |
| |
| <p>Another pool interface will be written: a base class for per-class pool |
| allocation. This "pool_base" interface will be Singleton Usage with |
| Exceptions, and built on the singleton_pool interface.</p> |
| <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> |